| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" |
| 2 |
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 6 |
<meta name="generator" content="AsciiDoc 8.4.5" /> |
| 7 |
<title>Lua CJSON 2.1.0 Manual</title> |
| 8 |
<style type="text/css"> |
| 9 |
/* Debug borders */ |
| 10 |
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { |
| 11 |
/* |
| 12 |
border: 1px solid red; |
| 13 |
*/ |
| 14 |
} |
| 15 |
|
| 16 |
body { |
| 17 |
margin: 1em 5% 1em 5%; |
| 18 |
} |
| 19 |
|
| 20 |
a { |
| 21 |
color: blue; |
| 22 |
text-decoration: underline; |
| 23 |
} |
| 24 |
a:visited { |
| 25 |
color: fuchsia; |
| 26 |
} |
| 27 |
|
| 28 |
em { |
| 29 |
font-style: italic; |
| 30 |
color: navy; |
| 31 |
} |
| 32 |
|
| 33 |
strong { |
| 34 |
font-weight: bold; |
| 35 |
color: #083194; |
| 36 |
} |
| 37 |
|
| 38 |
tt { |
| 39 |
color: navy; |
| 40 |
} |
| 41 |
|
| 42 |
h1, h2, h3, h4, h5, h6 { |
| 43 |
color: #527bbd; |
| 44 |
font-family: sans-serif; |
| 45 |
margin-top: 1.2em; |
| 46 |
margin-bottom: 0.5em; |
| 47 |
line-height: 1.3; |
| 48 |
} |
| 49 |
|
| 50 |
h1, h2, h3 { |
| 51 |
border-bottom: 2px solid silver; |
| 52 |
} |
| 53 |
h2 { |
| 54 |
padding-top: 0.5em; |
| 55 |
} |
| 56 |
h3 { |
| 57 |
float: left; |
| 58 |
} |
| 59 |
h3 + * { |
| 60 |
clear: left; |
| 61 |
} |
| 62 |
|
| 63 |
div.sectionbody { |
| 64 |
font-family: serif; |
| 65 |
margin-left: 0; |
| 66 |
} |
| 67 |
|
| 68 |
hr { |
| 69 |
border: 1px solid silver; |
| 70 |
} |
| 71 |
|
| 72 |
p { |
| 73 |
margin-top: 0.5em; |
| 74 |
margin-bottom: 0.5em; |
| 75 |
} |
| 76 |
|
| 77 |
ul, ol, li > p { |
| 78 |
margin-top: 0; |
| 79 |
} |
| 80 |
|
| 81 |
pre { |
| 82 |
padding: 0; |
| 83 |
margin: 0; |
| 84 |
} |
| 85 |
|
| 86 |
span#author { |
| 87 |
color: #527bbd; |
| 88 |
font-family: sans-serif; |
| 89 |
font-weight: bold; |
| 90 |
font-size: 1.1em; |
| 91 |
} |
| 92 |
span#email { |
| 93 |
} |
| 94 |
span#revnumber, span#revdate, span#revremark { |
| 95 |
font-family: sans-serif; |
| 96 |
} |
| 97 |
|
| 98 |
div#footer { |
| 99 |
font-family: sans-serif; |
| 100 |
font-size: small; |
| 101 |
border-top: 2px solid silver; |
| 102 |
padding-top: 0.5em; |
| 103 |
margin-top: 4.0em; |
| 104 |
} |
| 105 |
div#footer-text { |
| 106 |
float: left; |
| 107 |
padding-bottom: 0.5em; |
| 108 |
} |
| 109 |
div#footer-badges { |
| 110 |
float: right; |
| 111 |
padding-bottom: 0.5em; |
| 112 |
} |
| 113 |
|
| 114 |
div#preamble { |
| 115 |
margin-top: 1.5em; |
| 116 |
margin-bottom: 1.5em; |
| 117 |
} |
| 118 |
div.tableblock, div.imageblock, div.exampleblock, div.verseblock, |
| 119 |
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, |
| 120 |
div.admonitionblock { |
| 121 |
margin-top: 1.5em; |
| 122 |
margin-bottom: 1.5em; |
| 123 |
} |
| 124 |
div.admonitionblock { |
| 125 |
margin-top: 2.5em; |
| 126 |
margin-bottom: 2.5em; |
| 127 |
} |
| 128 |
|
| 129 |
div.content { /* Block element content. */ |
| 130 |
padding: 0; |
| 131 |
} |
| 132 |
|
| 133 |
/* Block element titles. */ |
| 134 |
div.title, caption.title { |
| 135 |
color: #527bbd; |
| 136 |
font-family: sans-serif; |
| 137 |
font-weight: bold; |
| 138 |
text-align: left; |
| 139 |
margin-top: 1.0em; |
| 140 |
margin-bottom: 0.5em; |
| 141 |
} |
| 142 |
div.title + * { |
| 143 |
margin-top: 0; |
| 144 |
} |
| 145 |
|
| 146 |
td div.title:first-child { |
| 147 |
margin-top: 0.0em; |
| 148 |
} |
| 149 |
div.content div.title:first-child { |
| 150 |
margin-top: 0.0em; |
| 151 |
} |
| 152 |
div.content + div.title { |
| 153 |
margin-top: 0.0em; |
| 154 |
} |
| 155 |
|
| 156 |
div.sidebarblock > div.content { |
| 157 |
background: #ffffee; |
| 158 |
border: 1px solid silver; |
| 159 |
padding: 0.5em; |
| 160 |
} |
| 161 |
|
| 162 |
div.listingblock > div.content { |
| 163 |
border: 1px solid silver; |
| 164 |
background: #f4f4f4; |
| 165 |
padding: 0.5em; |
| 166 |
} |
| 167 |
|
| 168 |
div.quoteblock { |
| 169 |
padding-left: 2.0em; |
| 170 |
margin-right: 10%; |
| 171 |
} |
| 172 |
div.quoteblock > div.attribution { |
| 173 |
padding-top: 0.5em; |
| 174 |
text-align: right; |
| 175 |
} |
| 176 |
|
| 177 |
div.verseblock { |
| 178 |
padding-left: 2.0em; |
| 179 |
margin-right: 10%; |
| 180 |
} |
| 181 |
div.verseblock > div.content { |
| 182 |
white-space: pre; |
| 183 |
} |
| 184 |
div.verseblock > div.attribution { |
| 185 |
padding-top: 0.75em; |
| 186 |
text-align: left; |
| 187 |
} |
| 188 |
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */ |
| 189 |
div.verseblock + div.attribution { |
| 190 |
text-align: left; |
| 191 |
} |
| 192 |
|
| 193 |
div.admonitionblock .icon { |
| 194 |
vertical-align: top; |
| 195 |
font-size: 1.1em; |
| 196 |
font-weight: bold; |
| 197 |
text-decoration: underline; |
| 198 |
color: #527bbd; |
| 199 |
padding-right: 0.5em; |
| 200 |
} |
| 201 |
div.admonitionblock td.content { |
| 202 |
padding-left: 0.5em; |
| 203 |
border-left: 2px solid silver; |
| 204 |
} |
| 205 |
|
| 206 |
div.exampleblock > div.content { |
| 207 |
border-left: 2px solid silver; |
| 208 |
padding: 0.5em; |
| 209 |
} |
| 210 |
|
| 211 |
div.imageblock div.content { padding-left: 0; } |
| 212 |
span.image img { border-style: none; } |
| 213 |
a.image:visited { color: white; } |
| 214 |
|
| 215 |
dl { |
| 216 |
margin-top: 0.8em; |
| 217 |
margin-bottom: 0.8em; |
| 218 |
} |
| 219 |
dt { |
| 220 |
margin-top: 0.5em; |
| 221 |
margin-bottom: 0; |
| 222 |
font-style: normal; |
| 223 |
color: navy; |
| 224 |
} |
| 225 |
dd > *:first-child { |
| 226 |
margin-top: 0.1em; |
| 227 |
} |
| 228 |
|
| 229 |
ul, ol { |
| 230 |
list-style-position: outside; |
| 231 |
} |
| 232 |
ol.arabic { |
| 233 |
list-style-type: decimal; |
| 234 |
} |
| 235 |
ol.loweralpha { |
| 236 |
list-style-type: lower-alpha; |
| 237 |
} |
| 238 |
ol.upperalpha { |
| 239 |
list-style-type: upper-alpha; |
| 240 |
} |
| 241 |
ol.lowerroman { |
| 242 |
list-style-type: lower-roman; |
| 243 |
} |
| 244 |
ol.upperroman { |
| 245 |
list-style-type: upper-roman; |
| 246 |
} |
| 247 |
|
| 248 |
div.compact ul, div.compact ol, |
| 249 |
div.compact p, div.compact p, |
| 250 |
div.compact div, div.compact div { |
| 251 |
margin-top: 0.1em; |
| 252 |
margin-bottom: 0.1em; |
| 253 |
} |
| 254 |
|
| 255 |
div.tableblock > table { |
| 256 |
border: 3px solid #527bbd; |
| 257 |
} |
| 258 |
thead { |
| 259 |
font-family: sans-serif; |
| 260 |
font-weight: bold; |
| 261 |
} |
| 262 |
tfoot { |
| 263 |
font-weight: bold; |
| 264 |
} |
| 265 |
td > div.verse { |
| 266 |
white-space: pre; |
| 267 |
} |
| 268 |
p.table { |
| 269 |
margin-top: 0; |
| 270 |
} |
| 271 |
/* Because the table frame attribute is overriden by CSS in most browsers. */ |
| 272 |
div.tableblock > table[frame="void"] { |
| 273 |
border-style: none; |
| 274 |
} |
| 275 |
div.tableblock > table[frame="hsides"] { |
| 276 |
border-left-style: none; |
| 277 |
border-right-style: none; |
| 278 |
} |
| 279 |
div.tableblock > table[frame="vsides"] { |
| 280 |
border-top-style: none; |
| 281 |
border-bottom-style: none; |
| 282 |
} |
| 283 |
|
| 284 |
|
| 285 |
div.hdlist { |
| 286 |
margin-top: 0.8em; |
| 287 |
margin-bottom: 0.8em; |
| 288 |
} |
| 289 |
div.hdlist tr { |
| 290 |
padding-bottom: 15px; |
| 291 |
} |
| 292 |
dt.hdlist1.strong, td.hdlist1.strong { |
| 293 |
font-weight: bold; |
| 294 |
} |
| 295 |
td.hdlist1 { |
| 296 |
vertical-align: top; |
| 297 |
font-style: normal; |
| 298 |
padding-right: 0.8em; |
| 299 |
color: navy; |
| 300 |
} |
| 301 |
td.hdlist2 { |
| 302 |
vertical-align: top; |
| 303 |
} |
| 304 |
div.hdlist.compact tr { |
| 305 |
margin: 0; |
| 306 |
padding-bottom: 0; |
| 307 |
} |
| 308 |
|
| 309 |
.comment { |
| 310 |
background: yellow; |
| 311 |
} |
| 312 |
|
| 313 |
@media print { |
| 314 |
div#footer-badges { display: none; } |
| 315 |
} |
| 316 |
|
| 317 |
div#toctitle { |
| 318 |
color: #527bbd; |
| 319 |
font-family: sans-serif; |
| 320 |
font-size: 1.1em; |
| 321 |
font-weight: bold; |
| 322 |
margin-top: 1.0em; |
| 323 |
margin-bottom: 0.1em; |
| 324 |
} |
| 325 |
|
| 326 |
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { |
| 327 |
margin-top: 0; |
| 328 |
margin-bottom: 0; |
| 329 |
} |
| 330 |
div.toclevel2 { |
| 331 |
margin-left: 2em; |
| 332 |
font-size: 0.9em; |
| 333 |
} |
| 334 |
div.toclevel3 { |
| 335 |
margin-left: 4em; |
| 336 |
font-size: 0.9em; |
| 337 |
} |
| 338 |
div.toclevel4 { |
| 339 |
margin-left: 6em; |
| 340 |
font-size: 0.9em; |
| 341 |
} |
| 342 |
/* Workarounds for IE6's broken and incomplete CSS2. */ |
| 343 |
|
| 344 |
div.sidebar-content { |
| 345 |
background: #ffffee; |
| 346 |
border: 1px solid silver; |
| 347 |
padding: 0.5em; |
| 348 |
} |
| 349 |
div.sidebar-title, div.image-title { |
| 350 |
color: #527bbd; |
| 351 |
font-family: sans-serif; |
| 352 |
font-weight: bold; |
| 353 |
margin-top: 0.0em; |
| 354 |
margin-bottom: 0.5em; |
| 355 |
} |
| 356 |
|
| 357 |
div.listingblock div.content { |
| 358 |
border: 1px solid silver; |
| 359 |
background: #f4f4f4; |
| 360 |
padding: 0.5em; |
| 361 |
} |
| 362 |
|
| 363 |
div.quoteblock-attribution { |
| 364 |
padding-top: 0.5em; |
| 365 |
text-align: right; |
| 366 |
} |
| 367 |
|
| 368 |
div.verseblock-content { |
| 369 |
white-space: pre; |
| 370 |
} |
| 371 |
div.verseblock-attribution { |
| 372 |
padding-top: 0.75em; |
| 373 |
text-align: left; |
| 374 |
} |
| 375 |
|
| 376 |
div.exampleblock-content { |
| 377 |
border-left: 2px solid silver; |
| 378 |
padding-left: 0.5em; |
| 379 |
} |
| 380 |
|
| 381 |
/* IE6 sets dynamically generated links as visited. */ |
| 382 |
div#toc a:visited { color: blue; } |
| 383 |
</style> |
| 384 |
<script type="text/javascript"> |
| 385 |
/*<+'])'); |
| 420 |
// Function that scans the DOM tree for header elements (the DOM2 |
| 421 |
// nodeIterator API would be a better technique but not supported by all |
| 422 |
// browsers). |
| 423 |
var iterate = function (el) { |
| 424 |
for (var i = el.firstChild; i != null; i = i.nextSibling) { |
| 425 |
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { |
| 426 |
var mo = re.exec(i.tagName) |
| 427 |
if (mo) |
| 428 |
result[result.length] = new TocEntry(i, getText(i), mo[1]-1); |
| 429 |
iterate(i); |
| 430 |
} |
| 431 |
} |
| 432 |
} |
| 433 |
iterate(el); |
| 434 |
return result; |
| 435 |
} |
| 436 |
|
| 437 |
// This function does the work. toclevels = 1..4. |
| 438 |
function generateToc(toclevels) { |
| 439 |
var toc = document.getElementById("toc"); |
| 440 |
var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels); |
| 441 |
for (var i = 0; i < entries.length; ++i) { |
| 442 |
var entry = entries[i]; |
| 443 |
if (entry.element.id == "") |
| 444 |
entry.element.id = "toc" + i; |
| 445 |
var a = document.createElement("a"); |
| 446 |
a.href = "#" + entry.element.id; |
| 447 |
a.appendChild(document.createTextNode(entry.text)); |
| 448 |
var div = document.createElement("div"); |
| 449 |
div.appendChild(a); |
| 450 |
div.className = "toclevel" + entry.toclevel; |
| 451 |
toc.appendChild(div); |
| 452 |
} |
| 453 |
if (entries.length == 0) |
| 454 |
document.getElementById("header").removeChild(toc); |
| 455 |
} |
| 456 |
/*]]>*/ |
| 457 |
</script> |
| 458 |
</head> |
| 459 |
<body> |
| 460 |
<div id="header"> |
| 461 |
<h1>Lua CJSON 2.1.0 Manual</h1> |
| 462 |
<span id="author">Mark Pulford</span><br /> |
| 463 |
<span id="email"><tt><<a href="mailto:[email protected]">[email protected]</a>></tt></span><br /> |
| 464 |
<span id="revdate">1st March 2012</span> |
| 465 |
<div id="toc"> |
| 466 |
<div id="toctitle">Table of Contents</div> |
| 467 |
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript> |
| 468 |
</div> |
| 469 |
</div> |
| 470 |
<h2 id="_overview">1. Overview</h2> |
| 471 |
<div class="sectionbody"> |
| 472 |
<div class="paragraph"><p>The Lua CJSON module provides JSON support for Lua.</p></div> |
| 473 |
<div class="dlist"><dl> |
| 474 |
<dt class="hdlist1"> |
| 475 |
<strong>Features</strong> |
| 476 |
</dt> |
| 477 |
<dd> |
| 478 |
<div class="ulist"><ul> |
| 479 |
<li> |
| 480 |
<p> |
| 481 |
Fast, standards compliant encoding/parsing routines |
| 482 |
</p> |
| 483 |
</li> |
| 484 |
<li> |
| 485 |
<p> |
| 486 |
Full support for JSON with UTF-8, including decoding surrogate pairs |
| 487 |
</p> |
| 488 |
</li> |
| 489 |
<li> |
| 490 |
<p> |
| 491 |
Optional run-time support for common exceptions to the JSON |
| 492 |
specification (infinity, NaN,..) |
| 493 |
</p> |
| 494 |
</li> |
| 495 |
<li> |
| 496 |
<p> |
| 497 |
No dependencies on other libraries |
| 498 |
</p> |
| 499 |
</li> |
| 500 |
</ul></div> |
| 501 |
</dd> |
| 502 |
<dt class="hdlist1"> |
| 503 |
<strong>Caveats</strong> |
| 504 |
</dt> |
| 505 |
<dd> |
| 506 |
<div class="ulist"><ul> |
| 507 |
<li> |
| 508 |
<p> |
| 509 |
UTF-16 and UTF-32 are not supported |
| 510 |
</p> |
| 511 |
</li> |
| 512 |
</ul></div> |
| 513 |
</dd> |
| 514 |
</dl></div> |
| 515 |
<div class="paragraph"><p>Lua CJSON is covered by the MIT license. Review the file <tt>LICENSE</tt> for |
| 516 |
details.</p></div> |
| 517 |
<div class="paragraph"><p>The latest version of this software is available from the |
| 518 |
<a href="http://www.kyne.com.au/%7Emark/software/lua-cjson.php">Lua CJSON website</a>.</p></div> |
| 519 |
<div class="paragraph"><p>Feel free to email me if you have any patches, suggestions, or comments.</p></div> |
| 520 |
</div> |
| 521 |
<h2 id="_installation">2. Installation</h2> |
| 522 |
<div class="sectionbody"> |
| 523 |
<div class="paragraph"><p>Lua CJSON requires either <a href="http://www.lua.org">Lua</a> 5.1, Lua 5.2, or |
| 524 |
<a href="http://www.luajit.org">LuaJIT</a> to build.</p></div> |
| 525 |
<div class="paragraph"><p>The build method can be selected from 4 options:</p></div> |
| 526 |
<div class="dlist"><dl> |
| 527 |
<dt class="hdlist1"> |
| 528 |
Make |
| 529 |
</dt> |
| 530 |
<dd> |
| 531 |
<p> |
| 532 |
Unix (including Linux, BSD, Mac OSX & Solaris), Windows |
| 533 |
</p> |
| 534 |
</dd> |
| 535 |
<dt class="hdlist1"> |
| 536 |
CMake |
| 537 |
</dt> |
| 538 |
<dd> |
| 539 |
<p> |
| 540 |
Unix, Windows |
| 541 |
</p> |
| 542 |
</dd> |
| 543 |
<dt class="hdlist1"> |
| 544 |
RPM |
| 545 |
</dt> |
| 546 |
<dd> |
| 547 |
<p> |
| 548 |
Linux |
| 549 |
</p> |
| 550 |
</dd> |
| 551 |
<dt class="hdlist1"> |
| 552 |
LuaRocks |
| 553 |
</dt> |
| 554 |
<dd> |
| 555 |
<p> |
| 556 |
Unix, Windows |
| 557 |
</p> |
| 558 |
</dd> |
| 559 |
</dl></div> |
| 560 |
<h3 id="_make">2.1. Make</h3><div style="clear:left"></div> |
| 561 |
<div class="paragraph"><p>The included <tt>Makefile</tt> has generic settings.</p></div> |
| 562 |
<div class="paragraph"><p>First, review and update the included makefile to suit your platform (if |
| 563 |
required).</p></div> |
| 564 |
<div class="paragraph"><p>Next, build and install the module:</p></div> |
| 565 |
<div class="exampleblock"> |
| 566 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 567 |
by Lorenzo Bettini |
| 568 |
http://www.lorenzobettini.it |
| 569 |
http://www.gnu.org/software/src-highlite --> |
| 570 |
<pre><tt>make install</tt></pre></div></div> |
| 571 |
<div class="paragraph"><p>Or install manually into your Lua module directory:</p></div> |
| 572 |
<div class="exampleblock"> |
| 573 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 574 |
by Lorenzo Bettini |
| 575 |
http://www.lorenzobettini.it |
| 576 |
http://www.gnu.org/software/src-highlite --> |
| 577 |
<pre><tt>make |
| 578 |
cp cjson<span style="color: #990000">.</span>so <span style="color: #009900">$LUA_MODULE_DIRECTORY</span></tt></pre></div></div> |
| 579 |
<h3 id="_cmake">2.2. CMake</h3><div style="clear:left"></div> |
| 580 |
<div class="paragraph"><p><a href="http://www.cmake.org">CMake</a> can generate build configuration for many |
| 581 |
different platforms (including Unix and Windows).</p></div> |
| 582 |
<div class="paragraph"><p>First, generate the makefile for your platform using CMake. If CMake is |
| 583 |
unable to find Lua, manually set the <tt>LUA_DIR</tt> environment variable to |
| 584 |
the base prefix of your Lua 5.1 installation.</p></div> |
| 585 |
<div class="paragraph"><p>While <tt>cmake</tt> is used in the example below, <tt>ccmake</tt> or <tt>cmake-gui</tt> may |
| 586 |
be used to present an interface for changing the default build options.</p></div> |
| 587 |
<div class="exampleblock"> |
| 588 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 589 |
by Lorenzo Bettini |
| 590 |
http://www.lorenzobettini.it |
| 591 |
http://www.gnu.org/software/src-highlite --> |
| 592 |
<pre><tt>mkdir build |
| 593 |
cd build |
| 594 |
<span style="font-style: italic"><span style="color: #9A1900"># Optional: export LUA_DIR=$LUA51_PREFIX</span></span> |
| 595 |
cmake <span style="color: #990000">..</span></tt></pre></div></div> |
| 596 |
<div class="paragraph"><p>Next, build and install the module:</p></div> |
| 597 |
<div class="exampleblock"> |
| 598 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 599 |
by Lorenzo Bettini |
| 600 |
http://www.lorenzobettini.it |
| 601 |
http://www.gnu.org/software/src-highlite --> |
| 602 |
<pre><tt>make install |
| 603 |
<span style="font-style: italic"><span style="color: #9A1900"># Or:</span></span> |
| 604 |
make |
| 605 |
cp cjson<span style="color: #990000">.</span>so <span style="color: #009900">$LUA_MODULE_DIRECTORY</span></tt></pre></div></div> |
| 606 |
<div class="paragraph"><p>Review the |
| 607 |
<a href="http://www.cmake.org/cmake/help/documentation.html">CMake documentation</a> |
| 608 |
for further details.</p></div> |
| 609 |
<h3 id="_rpm">2.3. RPM</h3><div style="clear:left"></div> |
| 610 |
<div class="paragraph"><p>Linux distributions using <a href="http://rpm.org">RPM</a> can create a package via |
| 611 |
the included RPM spec file. Ensure the <tt>rpm-build</tt> package (or similar) |
| 612 |
has been installed.</p></div> |
| 613 |
<div class="paragraph"><p>Build and install the module via RPM:</p></div> |
| 614 |
<div class="exampleblock"> |
| 615 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 616 |
by Lorenzo Bettini |
| 617 |
http://www.lorenzobettini.it |
| 618 |
http://www.gnu.org/software/src-highlite --> |
| 619 |
<pre><tt>rpmbuild -tb lua-cjson-<span style="color: #993399">2.1</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz |
| 620 |
rpm -Uvh <span style="color: #009900">$LUA_CJSON_RPM</span></tt></pre></div></div> |
| 621 |
<h3 id="_luarocks">2.4. LuaRocks</h3><div style="clear:left"></div> |
| 622 |
<div class="paragraph"><p><a href="http://luarocks.org">LuaRocks</a> can be used to install and manage Lua |
| 623 |
modules on a wide range of platforms (including Windows).</p></div> |
| 624 |
<div class="paragraph"><p>First, extract the Lua CJSON source package.</p></div> |
| 625 |
<div class="paragraph"><p>Next, install the module:</p></div> |
| 626 |
<div class="exampleblock"> |
| 627 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 628 |
by Lorenzo Bettini |
| 629 |
http://www.lorenzobettini.it |
| 630 |
http://www.gnu.org/software/src-highlite --> |
| 631 |
<pre><tt>cd lua-cjson-<span style="color: #993399">2.1</span><span style="color: #990000">.</span><span style="color: #993399">0</span> |
| 632 |
luarocks make</tt></pre></div></div> |
| 633 |
<div class="admonitionblock"> |
| 634 |
<table><tr> |
| 635 |
<td class="icon"> |
| 636 |
<div class="title">Note</div> |
| 637 |
</td> |
| 638 |
<td class="content">LuaRocks does not support platform specific configuration for Solaris. |
| 639 |
On Solaris, you may need to manually uncomment <tt>USE_INTERNAL_ISINF</tt> in |
| 640 |
the rockspec before building this module.</td> |
| 641 |
</tr></table> |
| 642 |
</div> |
| 643 |
<div class="paragraph"><p>Review the <a href="http://luarocks.org/en/Documentation">LuaRocks documentation</a> |
| 644 |
for further details.</p></div> |
| 645 |
<h3 id="build_options">2.5. Build Options (#define)</h3><div style="clear:left"></div> |
| 646 |
<div class="paragraph"><p>Lua CJSON offers several <tt>#define</tt> build options to address portability |
| 647 |
issues, and enable non-default features. Some build methods may |
| 648 |
automatically set platform specific options if required. Other features |
| 649 |
should be enabled manually.</p></div> |
| 650 |
<div class="dlist"><dl> |
| 651 |
<dt class="hdlist1"> |
| 652 |
USE_INTERNAL_ISINF |
| 653 |
</dt> |
| 654 |
<dd> |
| 655 |
<p> |
| 656 |
Workaround for Solaris platforms missing <tt>isinf</tt>. |
| 657 |
</p> |
| 658 |
</dd> |
| 659 |
<dt class="hdlist1"> |
| 660 |
DISABLE_INVALID_NUMBERS |
| 661 |
</dt> |
| 662 |
<dd> |
| 663 |
<p> |
| 664 |
Recommended on platforms where <tt>strtod</tt> / |
| 665 |
<tt>sprintf</tt> are not POSIX compliant (eg, Windows MinGW). Prevents |
| 666 |
<tt>cjson.encode_invalid_numbers</tt> and <tt>cjson.decode_invalid_numbers</tt> from |
| 667 |
being enabled. However, <tt>cjson.encode_invalid_numbers</tt> may still be |
| 668 |
set to <tt>"null"</tt>. When using the Lua CJSON built-in floating point |
| 669 |
conversion this option is unnecessary and is ignored. |
| 670 |
</p> |
| 671 |
</dd> |
| 672 |
</dl></div> |
| 673 |
<h4 id="_built_in_floating_point_conversion">2.5.1. Built-in floating point conversion</h4> |
| 674 |
<div class="paragraph"><p>Lua CJSON may be built with David Gay’s |
| 675 |
<a href="http://www.netlib.org/fp/">floating point conversion routines</a>. This can |
| 676 |
increase overall performance by up to 50% on some platforms when |
| 677 |
converting a large amount of numeric data. However, this option reduces |
| 678 |
portability and is disabled by default.</p></div> |
| 679 |
<div class="dlist"><dl> |
| 680 |
<dt class="hdlist1"> |
| 681 |
USE_INTERNAL_FPCONV |
| 682 |
</dt> |
| 683 |
<dd> |
| 684 |
<p> |
| 685 |
Enable internal number conversion routines. |
| 686 |
</p> |
| 687 |
</dd> |
| 688 |
<dt class="hdlist1"> |
| 689 |
IEEE_BIG_ENDIAN |
| 690 |
</dt> |
| 691 |
<dd> |
| 692 |
<p> |
| 693 |
Must be set on big endian architectures. |
| 694 |
</p> |
| 695 |
</dd> |
| 696 |
<dt class="hdlist1"> |
| 697 |
MULTIPLE_THREADS |
| 698 |
</dt> |
| 699 |
<dd> |
| 700 |
<p> |
| 701 |
Must be set if Lua CJSON may be used in a |
| 702 |
multi-threaded application. Requires the <em>pthreads</em> library. |
| 703 |
</p> |
| 704 |
</dd> |
| 705 |
</dl></div> |
| 706 |
</div> |
| 707 |
<h2 id="_api_functions">3. API (Functions)</h2> |
| 708 |
<div class="sectionbody"> |
| 709 |
<h3 id="_synopsis">3.1. Synopsis</h3><div style="clear:left"></div> |
| 710 |
<div class="listingblock"> |
| 711 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 712 |
by Lorenzo Bettini |
| 713 |
http://www.lorenzobettini.it |
| 714 |
http://www.gnu.org/software/src-highlite --> |
| 715 |
<pre><tt><span style="font-style: italic"><span style="color: #9A1900">-- Module instantiation</span></span> |
| 716 |
<span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson"</span> |
| 717 |
<span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson2 <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">new</span></span><span style="color: #990000">()</span> |
| 718 |
<span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson_safe <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson.safe"</span> |
| 719 |
|
| 720 |
<span style="font-style: italic"><span style="color: #9A1900">-- Translate Lua value to/from JSON</span></span> |
| 721 |
text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span> |
| 722 |
value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>text<span style="color: #990000">)</span> |
| 723 |
|
| 724 |
<span style="font-style: italic"><span style="color: #9A1900">-- Get and/or set Lua CJSON configuration</span></span> |
| 725 |
setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span> |
| 726 |
setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span> |
| 727 |
keep <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_keep_buffer</span></span><span style="color: #990000">([</span>keep<span style="color: #990000">])</span> |
| 728 |
depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span> |
| 729 |
depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span> |
| 730 |
convert<span style="color: #990000">,</span> ratio<span style="color: #990000">,</span> safe <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">([</span>convert<span style="color: #990000">[,</span> ratio<span style="color: #990000">[,</span> safe<span style="color: #990000">]]])</span></tt></pre></div></div> |
| 731 |
<h3 id="_module_instantiation">3.2. Module Instantiation</h3><div style="clear:left"></div> |
| 732 |
<div class="listingblock"> |
| 733 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 734 |
by Lorenzo Bettini |
| 735 |
http://www.lorenzobettini.it |
| 736 |
http://www.gnu.org/software/src-highlite --> |
| 737 |
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson"</span> |
| 738 |
<span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson2 <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">new</span></span><span style="color: #990000">()</span> |
| 739 |
<span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson_safe <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson.safe"</span></tt></pre></div></div> |
| 740 |
<div class="paragraph"><p>Import Lua CJSON via the Lua <tt>require</tt> function. Lua CJSON does not |
| 741 |
register a global module table.</p></div> |
| 742 |
<div class="paragraph"><p>The <tt>cjson</tt> module will throw an error during JSON conversion if any |
| 743 |
invalid data is encountered. Refer to <a href="#cjson_encode"><tt>cjson.encode</tt></a> |
| 744 |
and <a href="#cjson_decode"><tt>cjson.decode</tt></a> for details.</p></div> |
| 745 |
<div class="paragraph"><p>The <tt>cjson.safe</tt> module behaves identically to the <tt>cjson</tt> module, |
| 746 |
except when errors are encountered during JSON conversion. On error, the |
| 747 |
<tt>cjson_safe.encode</tt> and <tt>cjson_safe.decode</tt> functions will return |
| 748 |
<tt>nil</tt> followed by the error message.</p></div> |
| 749 |
<div class="paragraph"><p><tt>cjson.new</tt> can be used to instantiate an independent copy of the Lua |
| 750 |
CJSON module. The new module has a separate persistent encoding buffer, |
| 751 |
and default settings.</p></div> |
| 752 |
<div class="paragraph"><p>Lua CJSON can support Lua implementations using multiple preemptive |
| 753 |
threads within a single Lua state provided the persistent encoding |
| 754 |
buffer is not shared. This can be achieved by one of the following |
| 755 |
methods:</p></div> |
| 756 |
<div class="ulist"><ul> |
| 757 |
<li> |
| 758 |
<p> |
| 759 |
Disabling the persistent encoding buffer with |
| 760 |
<a href="#encode_keep_buffer"><tt>cjson.encode_keep_buffer</tt></a> |
| 761 |
</p> |
| 762 |
</li> |
| 763 |
<li> |
| 764 |
<p> |
| 765 |
Ensuring each thread calls <a href="#encode"><tt>cjson.encode</tt></a> separately (ie, |
| 766 |
treat <tt>cjson.encode</tt> as non-reentrant). |
| 767 |
</p> |
| 768 |
</li> |
| 769 |
<li> |
| 770 |
<p> |
| 771 |
Using a separate <tt>cjson</tt> module table per preemptive thread |
| 772 |
(<tt>cjson.new</tt>) |
| 773 |
</p> |
| 774 |
</li> |
| 775 |
</ul></div> |
| 776 |
<div class="admonitionblock"> |
| 777 |
<table><tr> |
| 778 |
<td class="icon"> |
| 779 |
<div class="title">Note</div> |
| 780 |
</td> |
| 781 |
<td class="content">Lua CJSON uses <tt>strtod</tt> and <tt>snprintf</tt> to perform numeric conversion as |
| 782 |
they are usually well supported, fast and bug free. However, these |
| 783 |
functions require a workaround for JSON encoding/parsing under locales |
| 784 |
using a comma decimal separator. Lua CJSON detects the current locale |
| 785 |
during instantiation to determine and automatically implement the |
| 786 |
workaround if required. Lua CJSON should be reinitialised via |
| 787 |
<tt>cjson.new</tt> if the locale of the current process changes. Using a |
| 788 |
different locale per thread is not supported.</td> |
| 789 |
</tr></table> |
| 790 |
</div> |
| 791 |
<h3 id="_decode">3.3. decode</h3><div style="clear:left"></div> |
| 792 |
<div class="listingblock"> |
| 793 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 794 |
by Lorenzo Bettini |
| 795 |
http://www.lorenzobettini.it |
| 796 |
http://www.gnu.org/software/src-highlite --> |
| 797 |
<pre><tt>value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>json_text<span style="color: #990000">)</span></tt></pre></div></div> |
| 798 |
<div class="paragraph"><p><tt>cjson.decode</tt> will deserialise any UTF-8 JSON string into a Lua value |
| 799 |
or table.</p></div> |
| 800 |
<div class="paragraph"><p>UTF-16 and UTF-32 JSON strings are not supported.</p></div> |
| 801 |
<div class="paragraph"><p><tt>cjson.decode</tt> requires that any NULL (ASCII 0) and double quote (ASCII |
| 802 |
34) characters are escaped within strings. All escape codes will be |
| 803 |
decoded and other bytes will be passed transparently. UTF-8 characters |
| 804 |
are not validated during decoding and should be checked elsewhere if |
| 805 |
required.</p></div> |
| 806 |
<div class="paragraph"><p>JSON <tt>null</tt> will be converted to a NULL <tt>lightuserdata</tt> value. This can |
| 807 |
be compared with <tt>cjson.null</tt> for convenience.</p></div> |
| 808 |
<div class="paragraph"><p>By default, numbers incompatible with the JSON specification (infinity, |
| 809 |
NaN, hexadecimal) can be decoded. This default can be changed with |
| 810 |
<a href="#decode_invalid_numbers"><tt>cjson.decode_invalid_numbers</tt></a>.</p></div> |
| 811 |
<div class="exampleblock"> |
| 812 |
<div class="title">Example: Decoding</div> |
| 813 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 814 |
by Lorenzo Bettini |
| 815 |
http://www.lorenzobettini.it |
| 816 |
http://www.gnu.org/software/src-highlite --> |
| 817 |
<pre><tt>json_text <span style="color: #990000">=</span> <span style="color: #FF0000">'[ true, { "foo": "bar" } ]'</span> |
| 818 |
value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>json_text<span style="color: #990000">)</span> |
| 819 |
<span style="font-style: italic"><span style="color: #9A1900">-- Returns: { true, { foo = "bar" } }</span></span></tt></pre></div></div> |
| 820 |
<div class="admonitionblock"> |
| 821 |
<table><tr> |
| 822 |
<td class="icon"> |
| 823 |
<div class="title">Caution</div> |
| 824 |
</td> |
| 825 |
<td class="content">Care must be taken after decoding JSON objects with numeric keys. Each |
| 826 |
numeric key will be stored as a Lua <tt>string</tt>. Any subsequent code |
| 827 |
assuming type <tt>number</tt> may break.</td> |
| 828 |
</tr></table> |
| 829 |
</div> |
| 830 |
<h3 id="decode_invalid_numbers">3.4. decode_invalid_numbers</h3><div style="clear:left"></div> |
| 831 |
<div class="listingblock"> |
| 832 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 833 |
by Lorenzo Bettini |
| 834 |
http://www.lorenzobettini.it |
| 835 |
http://www.gnu.org/software/src-highlite --> |
| 836 |
<pre><tt>setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span> |
| 837 |
<span style="font-style: italic"><span style="color: #9A1900">-- "setting" must be a boolean. Default: true.</span></span></tt></pre></div></div> |
| 838 |
<div class="paragraph"><p>Lua CJSON may generate an error when trying to decode numbers not |
| 839 |
supported by the JSON specification. <em>Invalid numbers</em> are defined as:</p></div> |
| 840 |
<div class="ulist"><ul> |
| 841 |
<li> |
| 842 |
<p> |
| 843 |
infinity |
| 844 |
</p> |
| 845 |
</li> |
| 846 |
<li> |
| 847 |
<p> |
| 848 |
not-a-number (NaN) |
| 849 |
</p> |
| 850 |
</li> |
| 851 |
<li> |
| 852 |
<p> |
| 853 |
hexadecimal |
| 854 |
</p> |
| 855 |
</li> |
| 856 |
</ul></div> |
| 857 |
<div class="paragraph"><p>Available settings:</p></div> |
| 858 |
<div class="dlist"><dl> |
| 859 |
<dt class="hdlist1"> |
| 860 |
<tt>true</tt> |
| 861 |
</dt> |
| 862 |
<dd> |
| 863 |
<p> |
| 864 |
Accept and decode <em>invalid numbers</em>. This is the default |
| 865 |
setting. |
| 866 |
</p> |
| 867 |
</dd> |
| 868 |
<dt class="hdlist1"> |
| 869 |
<tt>false</tt> |
| 870 |
</dt> |
| 871 |
<dd> |
| 872 |
<p> |
| 873 |
Throw an error when <em>invalid numbers</em> are encountered. |
| 874 |
</p> |
| 875 |
</dd> |
| 876 |
</dl></div> |
| 877 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 878 |
argument is provided.</p></div> |
| 879 |
<h3 id="decode_max_depth">3.5. decode_max_depth</h3><div style="clear:left"></div> |
| 880 |
<div class="listingblock"> |
| 881 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 882 |
by Lorenzo Bettini |
| 883 |
http://www.lorenzobettini.it |
| 884 |
http://www.gnu.org/software/src-highlite --> |
| 885 |
<pre><tt>depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span> |
| 886 |
<span style="font-style: italic"><span style="color: #9A1900">-- "depth" must be a positive integer. Default: 1000.</span></span></tt></pre></div></div> |
| 887 |
<div class="paragraph"><p>Lua CJSON will generate an error when parsing deeply nested JSON once |
| 888 |
the maximum array/object depth has been exceeded. This check prevents |
| 889 |
unnecessarily complicated JSON from slowing down the application, or |
| 890 |
crashing the application due to lack of process stack space.</p></div> |
| 891 |
<div class="paragraph"><p>An error may be generated before the depth limit is hit if Lua is unable |
| 892 |
to allocate more objects on the Lua stack.</p></div> |
| 893 |
<div class="paragraph"><p>By default, Lua CJSON will reject JSON with arrays and/or objects nested |
| 894 |
more than 1000 levels deep.</p></div> |
| 895 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 896 |
argument is provided.</p></div> |
| 897 |
<h3 id="encode">3.6. encode</h3><div style="clear:left"></div> |
| 898 |
<div class="listingblock"> |
| 899 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 900 |
by Lorenzo Bettini |
| 901 |
http://www.lorenzobettini.it |
| 902 |
http://www.gnu.org/software/src-highlite --> |
| 903 |
<pre><tt>json_text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span></tt></pre></div></div> |
| 904 |
<div class="paragraph"><p><tt>cjson.encode</tt> will serialise a Lua value into a string containing the |
| 905 |
JSON representation.</p></div> |
| 906 |
<div class="paragraph"><p><tt>cjson.encode</tt> supports the following types:</p></div> |
| 907 |
<div class="ulist"><ul> |
| 908 |
<li> |
| 909 |
<p> |
| 910 |
<tt>boolean</tt> |
| 911 |
</p> |
| 912 |
</li> |
| 913 |
<li> |
| 914 |
<p> |
| 915 |
<tt>lightuserdata</tt> (NULL value only) |
| 916 |
</p> |
| 917 |
</li> |
| 918 |
<li> |
| 919 |
<p> |
| 920 |
<tt>nil</tt> |
| 921 |
</p> |
| 922 |
</li> |
| 923 |
<li> |
| 924 |
<p> |
| 925 |
<tt>number</tt> |
| 926 |
</p> |
| 927 |
</li> |
| 928 |
<li> |
| 929 |
<p> |
| 930 |
<tt>string</tt> |
| 931 |
</p> |
| 932 |
</li> |
| 933 |
<li> |
| 934 |
<p> |
| 935 |
<tt>table</tt> |
| 936 |
</p> |
| 937 |
</li> |
| 938 |
</ul></div> |
| 939 |
<div class="paragraph"><p>The remaining Lua types will generate an error:</p></div> |
| 940 |
<div class="ulist"><ul> |
| 941 |
<li> |
| 942 |
<p> |
| 943 |
<tt>function</tt> |
| 944 |
</p> |
| 945 |
</li> |
| 946 |
<li> |
| 947 |
<p> |
| 948 |
<tt>lightuserdata</tt> (non-NULL values) |
| 949 |
</p> |
| 950 |
</li> |
| 951 |
<li> |
| 952 |
<p> |
| 953 |
<tt>thread</tt> |
| 954 |
</p> |
| 955 |
</li> |
| 956 |
<li> |
| 957 |
<p> |
| 958 |
<tt>userdata</tt> |
| 959 |
</p> |
| 960 |
</li> |
| 961 |
</ul></div> |
| 962 |
<div class="paragraph"><p>By default, numbers are encoded with 14 significant digits. Refer to |
| 963 |
<a href="#encode_number_precision"><tt>cjson.encode_number_precision</tt></a> for details.</p></div> |
| 964 |
<div class="paragraph"><p>Lua CJSON will escape the following characters within each UTF-8 string:</p></div> |
| 965 |
<div class="ulist"><ul> |
| 966 |
<li> |
| 967 |
<p> |
| 968 |
Control characters (ASCII 0 - 31) |
| 969 |
</p> |
| 970 |
</li> |
| 971 |
<li> |
| 972 |
<p> |
| 973 |
Double quote (ASCII 34) |
| 974 |
</p> |
| 975 |
</li> |
| 976 |
<li> |
| 977 |
<p> |
| 978 |
Forward slash (ASCII 47) |
| 979 |
</p> |
| 980 |
</li> |
| 981 |
<li> |
| 982 |
<p> |
| 983 |
Blackslash (ASCII 92) |
| 984 |
</p> |
| 985 |
</li> |
| 986 |
<li> |
| 987 |
<p> |
| 988 |
Delete (ASCII 127) |
| 989 |
</p> |
| 990 |
</li> |
| 991 |
</ul></div> |
| 992 |
<div class="paragraph"><p>All other bytes are passed transparently.</p></div> |
| 993 |
<div class="admonitionblock"> |
| 994 |
<table><tr> |
| 995 |
<td class="icon"> |
| 996 |
<div class="title">Caution</div> |
| 997 |
</td> |
| 998 |
<td class="content"> |
| 999 |
<div class="paragraph"><p>Lua CJSON will successfully encode/decode binary strings, but this is |
| 1000 |
technically not supported by JSON and may not be compatible with other |
| 1001 |
JSON libraries. To ensure the output is valid JSON, applications should |
| 1002 |
ensure all Lua strings passed to <tt>cjson.encode</tt> are UTF-8.</p></div> |
| 1003 |
<div class="paragraph"><p>Base64 is commonly used to encode binary data as the most efficient |
| 1004 |
encoding under UTF-8 can only reduce the encoded size by a further |
| 1005 |
~8%. Lua Base64 routines can be found in the |
| 1006 |
<a href="http://w3.impa.br/%7Ediego/software/luasocket/">LuaSocket</a> and |
| 1007 |
<a href="http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/#lbase64">lbase64</a> packages.</p></div> |
| 1008 |
</td> |
| 1009 |
</tr></table> |
| 1010 |
</div> |
| 1011 |
<div class="paragraph"><p>Lua CJSON uses a heuristic to determine whether to encode a Lua table as |
| 1012 |
a JSON array or an object. A Lua table with only positive integer keys |
| 1013 |
of type <tt>number</tt> will be encoded as a JSON array. All other tables will |
| 1014 |
be encoded as a JSON object.</p></div> |
| 1015 |
<div class="paragraph"><p>Lua CJSON does not use metamethods when serialising tables.</p></div> |
| 1016 |
<div class="ulist"><ul> |
| 1017 |
<li> |
| 1018 |
<p> |
| 1019 |
<tt>rawget</tt> is used to iterate over Lua arrays |
| 1020 |
</p> |
| 1021 |
</li> |
| 1022 |
<li> |
| 1023 |
<p> |
| 1024 |
<tt>next</tt> is used to iterate over Lua objects |
| 1025 |
</p> |
| 1026 |
</li> |
| 1027 |
</ul></div> |
| 1028 |
<div class="paragraph"><p>Lua arrays with missing entries (<em>sparse arrays</em>) may optionally be |
| 1029 |
encoded in several different ways. Refer to |
| 1030 |
<a href="#encode_sparse_array"><tt>cjson.encode_sparse_array</tt></a> for details.</p></div> |
| 1031 |
<div class="paragraph"><p>JSON object keys are always strings. Hence <tt>cjson.encode</tt> only supports |
| 1032 |
table keys which are type <tt>number</tt> or <tt>string</tt>. All other types will |
| 1033 |
generate an error.</p></div> |
| 1034 |
<div class="admonitionblock"> |
| 1035 |
<table><tr> |
| 1036 |
<td class="icon"> |
| 1037 |
<div class="title">Note</div> |
| 1038 |
</td> |
| 1039 |
<td class="content">Standards compliant JSON must be encapsulated in either an object (<tt>{}</tt>) |
| 1040 |
or an array (<tt>[]</tt>). If strictly standards compliant JSON is desired, a |
| 1041 |
table must be passed to <tt>cjson.encode</tt>.</td> |
| 1042 |
</tr></table> |
| 1043 |
</div> |
| 1044 |
<div class="paragraph"><p>By default, encoding the following Lua values will generate errors:</p></div> |
| 1045 |
<div class="ulist"><ul> |
| 1046 |
<li> |
| 1047 |
<p> |
| 1048 |
Numbers incompatible with the JSON specification (infinity, NaN) |
| 1049 |
</p> |
| 1050 |
</li> |
| 1051 |
<li> |
| 1052 |
<p> |
| 1053 |
Tables nested more than 1000 levels deep |
| 1054 |
</p> |
| 1055 |
</li> |
| 1056 |
<li> |
| 1057 |
<p> |
| 1058 |
Excessively sparse Lua arrays |
| 1059 |
</p> |
| 1060 |
</li> |
| 1061 |
</ul></div> |
| 1062 |
<div class="paragraph"><p>These defaults can be changed with:</p></div> |
| 1063 |
<div class="ulist"><ul> |
| 1064 |
<li> |
| 1065 |
<p> |
| 1066 |
<a href="#encode_invalid_numbers"><tt>cjson.encode_invalid_numbers</tt></a> |
| 1067 |
</p> |
| 1068 |
</li> |
| 1069 |
<li> |
| 1070 |
<p> |
| 1071 |
<a href="#encode_max_depth"><tt>cjson.encode_max_depth</tt></a> |
| 1072 |
</p> |
| 1073 |
</li> |
| 1074 |
<li> |
| 1075 |
<p> |
| 1076 |
<a href="#encode_sparse_array"><tt>cjson.encode_sparse_array</tt></a> |
| 1077 |
</p> |
| 1078 |
</li> |
| 1079 |
</ul></div> |
| 1080 |
<div class="exampleblock"> |
| 1081 |
<div class="title">Example: Encoding</div> |
| 1082 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1083 |
by Lorenzo Bettini |
| 1084 |
http://www.lorenzobettini.it |
| 1085 |
http://www.gnu.org/software/src-highlite --> |
| 1086 |
<pre><tt>value <span style="color: #990000">=</span> <span style="color: #FF0000">{</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> foo <span style="color: #990000">=</span> <span style="color: #FF0000">"bar"</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span> |
| 1087 |
json_text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span> |
| 1088 |
<span style="font-style: italic"><span style="color: #9A1900">-- Returns: '[true,{"foo":"bar"}]'</span></span></tt></pre></div></div> |
| 1089 |
<h3 id="encode_invalid_numbers">3.7. encode_invalid_numbers</h3><div style="clear:left"></div> |
| 1090 |
<div class="listingblock"> |
| 1091 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1092 |
by Lorenzo Bettini |
| 1093 |
http://www.lorenzobettini.it |
| 1094 |
http://www.gnu.org/software/src-highlite --> |
| 1095 |
<pre><tt>setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span> |
| 1096 |
<span style="font-style: italic"><span style="color: #9A1900">-- "setting" must a boolean or "null". Default: false.</span></span></tt></pre></div></div> |
| 1097 |
<div class="paragraph"><p>Lua CJSON may generate an error when encoding floating point numbers not |
| 1098 |
supported by the JSON specification (<em>invalid numbers</em>):</p></div> |
| 1099 |
<div class="ulist"><ul> |
| 1100 |
<li> |
| 1101 |
<p> |
| 1102 |
infinity |
| 1103 |
</p> |
| 1104 |
</li> |
| 1105 |
<li> |
| 1106 |
<p> |
| 1107 |
not-a-number (NaN) |
| 1108 |
</p> |
| 1109 |
</li> |
| 1110 |
</ul></div> |
| 1111 |
<div class="paragraph"><p>Available settings:</p></div> |
| 1112 |
<div class="dlist"><dl> |
| 1113 |
<dt class="hdlist1"> |
| 1114 |
<tt>true</tt> |
| 1115 |
</dt> |
| 1116 |
<dd> |
| 1117 |
<p> |
| 1118 |
Allow <em>invalid numbers</em> to be encoded. This will generate |
| 1119 |
non-standard JSON, but this output is supported by some libraries. |
| 1120 |
</p> |
| 1121 |
</dd> |
| 1122 |
<dt class="hdlist1"> |
| 1123 |
<tt>"null"</tt> |
| 1124 |
</dt> |
| 1125 |
<dd> |
| 1126 |
<p> |
| 1127 |
Encode <em>invalid numbers</em> as a JSON <tt>null</tt> value. This allows |
| 1128 |
infinity and NaN to be encoded into valid JSON. |
| 1129 |
</p> |
| 1130 |
</dd> |
| 1131 |
<dt class="hdlist1"> |
| 1132 |
<tt>false</tt> |
| 1133 |
</dt> |
| 1134 |
<dd> |
| 1135 |
<p> |
| 1136 |
Throw an error when attempting to encode <em>invalid numbers</em>. |
| 1137 |
This is the default setting. |
| 1138 |
</p> |
| 1139 |
</dd> |
| 1140 |
</dl></div> |
| 1141 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 1142 |
argument is provided.</p></div> |
| 1143 |
<h3 id="encode_keep_buffer">3.8. encode_keep_buffer</h3><div style="clear:left"></div> |
| 1144 |
<div class="listingblock"> |
| 1145 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1146 |
by Lorenzo Bettini |
| 1147 |
http://www.lorenzobettini.it |
| 1148 |
http://www.gnu.org/software/src-highlite --> |
| 1149 |
<pre><tt>keep <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_keep_buffer</span></span><span style="color: #990000">([</span>keep<span style="color: #990000">])</span> |
| 1150 |
<span style="font-style: italic"><span style="color: #9A1900">-- "keep" must be a boolean. Default: true.</span></span></tt></pre></div></div> |
| 1151 |
<div class="paragraph"><p>Lua CJSON can reuse the JSON encoding buffer to improve performance.</p></div> |
| 1152 |
<div class="paragraph"><p>Available settings:</p></div> |
| 1153 |
<div class="dlist"><dl> |
| 1154 |
<dt class="hdlist1"> |
| 1155 |
<tt>true</tt> |
| 1156 |
</dt> |
| 1157 |
<dd> |
| 1158 |
<p> |
| 1159 |
The buffer will grow to the largest size required and is not |
| 1160 |
freed until the Lua CJSON module is garbage collected. This is the |
| 1161 |
default setting. |
| 1162 |
</p> |
| 1163 |
</dd> |
| 1164 |
<dt class="hdlist1"> |
| 1165 |
<tt>false</tt> |
| 1166 |
</dt> |
| 1167 |
<dd> |
| 1168 |
<p> |
| 1169 |
Free the encode buffer after each call to <tt>cjson.encode</tt>. |
| 1170 |
</p> |
| 1171 |
</dd> |
| 1172 |
</dl></div> |
| 1173 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 1174 |
argument is provided.</p></div> |
| 1175 |
<h3 id="encode_max_depth">3.9. encode_max_depth</h3><div style="clear:left"></div> |
| 1176 |
<div class="listingblock"> |
| 1177 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1178 |
by Lorenzo Bettini |
| 1179 |
http://www.lorenzobettini.it |
| 1180 |
http://www.gnu.org/software/src-highlite --> |
| 1181 |
<pre><tt>depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span> |
| 1182 |
<span style="font-style: italic"><span style="color: #9A1900">-- "depth" must be a positive integer. Default: 1000.</span></span></tt></pre></div></div> |
| 1183 |
<div class="paragraph"><p>Once the maximum table depth has been exceeded Lua CJSON will generate |
| 1184 |
an error. This prevents a deeply nested or recursive data structure from |
| 1185 |
crashing the application.</p></div> |
| 1186 |
<div class="paragraph"><p>By default, Lua CJSON will generate an error when trying to encode data |
| 1187 |
structures with more than 1000 nested tables.</p></div> |
| 1188 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 1189 |
argument is provided.</p></div> |
| 1190 |
<div class="exampleblock"> |
| 1191 |
<div class="title">Example: Recursive Lua table</div> |
| 1192 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1193 |
by Lorenzo Bettini |
| 1194 |
http://www.lorenzobettini.it |
| 1195 |
http://www.gnu.org/software/src-highlite --> |
| 1196 |
<pre><tt>a <span style="color: #990000">=</span> <span style="color: #FF0000">{}</span><span style="color: #990000">;</span> a<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> a</tt></pre></div></div> |
| 1197 |
<h3 id="encode_number_precision">3.10. encode_number_precision</h3><div style="clear:left"></div> |
| 1198 |
<div class="listingblock"> |
| 1199 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1200 |
by Lorenzo Bettini |
| 1201 |
http://www.lorenzobettini.it |
| 1202 |
http://www.gnu.org/software/src-highlite --> |
| 1203 |
<pre><tt>precision <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_number_precision</span></span><span style="color: #990000">([</span>precision<span style="color: #990000">])</span> |
| 1204 |
<span style="font-style: italic"><span style="color: #9A1900">-- "precision" must be an integer between 1 and 14. Default: 14.</span></span></tt></pre></div></div> |
| 1205 |
<div class="paragraph"><p>The amount of significant digits returned by Lua CJSON when encoding |
| 1206 |
numbers can be changed to balance accuracy versus performance. For data |
| 1207 |
structures containing many numbers, setting |
| 1208 |
<tt>cjson.encode_number_precision</tt> to a smaller integer, for example <tt>3</tt>, |
| 1209 |
can improve encoding performance by up to 50%.</p></div> |
| 1210 |
<div class="paragraph"><p>By default, Lua CJSON will output 14 significant digits when converting |
| 1211 |
a number to text.</p></div> |
| 1212 |
<div class="paragraph"><p>The current setting is always returned, and is only updated when an |
| 1213 |
argument is provided.</p></div> |
| 1214 |
<h3 id="encode_sparse_array">3.11. encode_sparse_array</h3><div style="clear:left"></div> |
| 1215 |
<div class="listingblock"> |
| 1216 |
<div class="content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1217 |
by Lorenzo Bettini |
| 1218 |
http://www.lorenzobettini.it |
| 1219 |
http://www.gnu.org/software/src-highlite --> |
| 1220 |
<pre><tt>convert<span style="color: #990000">,</span> ratio<span style="color: #990000">,</span> safe <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">([</span>convert<span style="color: #990000">[,</span> ratio<span style="color: #990000">[,</span> safe<span style="color: #990000">]]])</span> |
| 1221 |
<span style="font-style: italic"><span style="color: #9A1900">-- "convert" must be a boolean. Default: false.</span></span> |
| 1222 |
<span style="font-style: italic"><span style="color: #9A1900">-- "ratio" must be a positive integer. Default: 2.</span></span> |
| 1223 |
<span style="font-style: italic"><span style="color: #9A1900">-- "safe" must be a positive integer. Default: 10.</span></span></tt></pre></div></div> |
| 1224 |
<div class="paragraph"><p>Lua CJSON classifies a Lua table into one of three kinds when encoding a |
| 1225 |
JSON array. This is determined by the number of values missing from the |
| 1226 |
Lua array as follows:</p></div> |
| 1227 |
<div class="dlist"><dl> |
| 1228 |
<dt class="hdlist1"> |
| 1229 |
Normal |
| 1230 |
</dt> |
| 1231 |
<dd> |
| 1232 |
<p> |
| 1233 |
All values are available. |
| 1234 |
</p> |
| 1235 |
</dd> |
| 1236 |
<dt class="hdlist1"> |
| 1237 |
Sparse |
| 1238 |
</dt> |
| 1239 |
<dd> |
| 1240 |
<p> |
| 1241 |
At least 1 value is missing. |
| 1242 |
</p> |
| 1243 |
</dd> |
| 1244 |
<dt class="hdlist1"> |
| 1245 |
Excessively sparse |
| 1246 |
</dt> |
| 1247 |
<dd> |
| 1248 |
<p> |
| 1249 |
The number of values missing exceeds the configured |
| 1250 |
ratio. |
| 1251 |
</p> |
| 1252 |
</dd> |
| 1253 |
</dl></div> |
| 1254 |
<div class="paragraph"><p>Lua CJSON encodes sparse Lua arrays as JSON arrays using JSON <tt>null</tt> for |
| 1255 |
the missing entries.</p></div> |
| 1256 |
<div class="paragraph"><p>An array is excessively sparse when all the following conditions are |
| 1257 |
met:</p></div> |
| 1258 |
<div class="ulist"><ul> |
| 1259 |
<li> |
| 1260 |
<p> |
| 1261 |
<tt>ratio</tt> > <tt>0</tt> |
| 1262 |
</p> |
| 1263 |
</li> |
| 1264 |
<li> |
| 1265 |
<p> |
| 1266 |
<em>maximum_index</em> > <tt>safe</tt> |
| 1267 |
</p> |
| 1268 |
</li> |
| 1269 |
<li> |
| 1270 |
<p> |
| 1271 |
<em>maximum_index</em> > <em>item_count</em> * <tt>ratio</tt> |
| 1272 |
</p> |
| 1273 |
</li> |
| 1274 |
</ul></div> |
| 1275 |
<div class="paragraph"><p>Lua CJSON will never consider an array to be <em>excessively sparse</em> when |
| 1276 |
<tt>ratio</tt> = <tt>0</tt>. The <tt>safe</tt> limit ensures that small Lua arrays are always |
| 1277 |
encoded as sparse arrays.</p></div> |
| 1278 |
<div class="paragraph"><p>By default, attempting to encode an <em>excessively sparse</em> array will |
| 1279 |
generate an error. If <tt>convert</tt> is set to <tt>true</tt>, <em>excessively sparse</em> |
| 1280 |
arrays will be converted to a JSON object.</p></div> |
| 1281 |
<div class="paragraph"><p>The current settings are always returned. A particular setting is only |
| 1282 |
changed when the argument is provided (non-<tt>nil</tt>).</p></div> |
| 1283 |
<div class="exampleblock"> |
| 1284 |
<div class="title">Example: Encoding a sparse array</div> |
| 1285 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1286 |
by Lorenzo Bettini |
| 1287 |
http://www.lorenzobettini.it |
| 1288 |
http://www.gnu.org/software/src-highlite --> |
| 1289 |
<pre><tt>cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span><span style="color: #FF0000">{</span> <span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"data"</span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span> |
| 1290 |
<span style="font-style: italic"><span style="color: #9A1900">-- Returns: '[null,null,"data"]'</span></span></tt></pre></div></div> |
| 1291 |
<div class="exampleblock"> |
| 1292 |
<div class="title">Example: Enabling conversion to a JSON object</div> |
| 1293 |
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4 |
| 1294 |
by Lorenzo Bettini |
| 1295 |
http://www.lorenzobettini.it |
| 1296 |
http://www.gnu.org/software/src-highlite --> |
| 1297 |
<pre><tt>cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">)</span> |
| 1298 |
cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span><span style="color: #FF0000">{</span> <span style="color: #990000">[</span><span style="color: #993399">1000</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"excessively sparse"</span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span> |
| 1299 |
<span style="font-style: italic"><span style="color: #9A1900">-- Returns: '{"1000":"excessively sparse"}'</span></span></tt></pre></div></div> |
| 1300 |
</div> |
| 1301 |
<h2 id="_api_variables">4. API (Variables)</h2> |
| 1302 |
<div class="sectionbody"> |
| 1303 |
<h3 id="_name">4.1. _NAME</h3><div style="clear:left"></div> |
| 1304 |
<div class="paragraph"><p>The name of the Lua CJSON module (<tt>"cjson"</tt>).</p></div> |
| 1305 |
<h3 id="_version">4.2. _VERSION</h3><div style="clear:left"></div> |
| 1306 |
<div class="paragraph"><p>The version number of the Lua CJSON module (<tt>"2.1.0"</tt>).</p></div> |
| 1307 |
<h3 id="_null">4.3. null</h3><div style="clear:left"></div> |
| 1308 |
<div class="paragraph"><p>Lua CJSON decodes JSON <tt>null</tt> as a Lua <tt>lightuserdata</tt> NULL pointer. |
| 1309 |
<tt>cjson.null</tt> is provided for comparison.</p></div> |
| 1310 |
</div> |
| 1311 |
<h2 id="_references">5. References</h2> |
| 1312 |
<div class="sectionbody"> |
| 1313 |
<div class="ulist"><ul> |
| 1314 |
<li> |
| 1315 |
<p> |
| 1316 |
<a href="http://tools.ietf.org/html/rfc4627">RFC 4627</a> |
| 1317 |
</p> |
| 1318 |
</li> |
| 1319 |
<li> |
| 1320 |
<p> |
| 1321 |
<a href="http://www.json.org/">JSON website</a> |
| 1322 |
</p> |
| 1323 |
</li> |
| 1324 |
</ul></div> |
| 1325 |
</div> |
| 1326 |
<div id="footer"> |
| 1327 |
<div id="footer-text"> |
| 1328 |
Last updated 2012-03-01 22:52:58 CST |
| 1329 |
</div> |
| 1330 |
</div> |
| 1331 |
</body> |
| 1332 |
</html> |