Artifact Content — dkjson

Artifact b6e655914d6bf281711323fb1fc7495cdcb9b029:

Wiki page [dkjson] by dhkolf 2013-09-28 19:30:35.
D 2013-09-28T19:30:35.170
L dkjson
P df3403756f40cfa476388adb35f0b96ba334da91
U dhkolf
W 7835
<h1>JSON Module for Lua</h1>

<h2>Introduction</h2>

This is a JSON module written in [http://www.lua.org/|Lua]. It supports UTF-8.

[http://www.json.org/|JSON (JavaScript Object Notation)] is a format for serializing data based on the syntax for JavaScript data structures.  It is an ideal format for transmitting data between different applications and commonly used for dynamic web pages.  It can also be used to save Lua data structures, but you should be aware that not every Lua table can be represented by the JSON standard.  For example tables that contain both string keys and an array part cannot be exactly represented by JSON.  You can solve this by putting your array data in an explicit subtable.

dkjson is written in Lua without any dependencies, but
when [http://www.inf.puc-rio.br/~roberto/lpeg/|LPeg] is available dkjson uses it to speed up decoding.

<h2>Download</h2>
  *  [./raw/dkjson.lua?name=0b725e9e99117b71a1f62e921c98bf3327ac8809 | dkjson.lua]

The full [Documentation|documentation including the license] is available here in the wiki or as Markdown text in the source file.

dkjson is free software released under the same conditions as the Lua interpreter.  Please remember to mention external code you are using in your software.

<h2>Examples</h2>

<h3>Encoding</h3>

<pre><code><nowiki>
<span class="luakeyword">local</span> json = <span class="lualibrary">require</span> (<span class="luastring">"dkjson"</span>)

<span class="luakeyword">local</span> tbl = {
  animals = { <span class="luastring">"dog"</span>, <span class="luastring">"cat"</span>, <span class="luastring">"aardvark"</span> },
  instruments = { <span class="luastring">"violin"</span>, <span class="luastring">"trombone"</span>, <span class="luastring">"theremin"</span> },
  bugs = json.null,
  trees = <span class="luakeyword">nil</span>
}

<span class="luakeyword">local</span> str = json.encode (tbl, { indent = <span class="luakeyword">true</span> })

<span class="lualibrary">print</span> (str)
</nowiki></code></pre>

<h4>Output</h4>

<pre><code><nowiki>
{
  "bugs":null,
  "instruments":["violin","trombone","theremin"],
  "animals":["dog","cat","aardvark"]
}
</nowiki></code></pre>

<h3>Decoding</h3>

<pre><code><nowiki>
<span class="luakeyword">local</span> json = <span class="lualibrary">require</span> (<span class="luastring">"dkjson"</span>)

<span class="luakeyword">local</span> str = <span class="luastring">[[
{
  "numbers": [ 2, 3, -20.23e+2, -4 ],
  "currency": "\u20AC"
}
]]</span>

<span class="luakeyword">local</span> obj, pos, err = json.decode (str, 1, <span class="luakeyword">nil</span>)
<span class="luakeyword">if</span> err <span class="luakeyword">then</span>
  <span class="lualibrary">print</span> (<span class="luastring">"Error:"</span>, err)
<span class="luakeyword">else</span>
  <span class="lualibrary">print</span> (<span class="luastring">"currency"</span>, obj.currency)
  <span class="luakeyword">for</span> i = 1,#obj.numbers <span class="luakeyword">do</span>
    <span class="lualibrary">print</span> (i, obj.numbers[i])
  <span class="luakeyword">end</span>
<span class="luakeyword">end</span>

</nowiki></code></pre>


<h4>Output</h4>

<pre><nowiki>
currency	€
1	2
2	3
3	-2023
4	-4
</nowiki></pre>

<h2>Versions</h2>

<h3>Version 2.4 (2013-09-28)</h3>

  *  Download [./raw/dkjson.lua?name=0b725e9e99117b71a1f62e921c98bf3327ac8809 | dkjson.lua version 2.4]

Changes since version 2.3:

  *  Fixed encoding and decoding of numbers in different numeric locales.
  *  Prevent using version 0.11 of LPeg (causes segmentation faults on
     some systems).

<h3>Version 1.3 (2013-09-28)</h3>

  *  Download [./raw/dkjson.lua?name=142fe16d14a71a477eee9822133e2d61eaf35443 | dkjson.lua version 1.3]

Changes since version 1.2:

  *  Fixed encoding and decoding of numbers in different numeric locales.

<h3>Version 2.3 (2013-04-14)</h3>

  *  Download [./raw/dkjson.lua?name=1a7969ae3ff9a6e0268e6555d31092213060fd62 | dkjson.lua version 2.3]

Changes since version 2.2:

  *  Corrected the range of escaped characters.  Among other characters
     U+2029 was missing, which would cause trouble when [http://timelessrepo.com/json-isnt-a-javascript-subset|parsed by a
     JavaScript interpreter.]
  *  Added options to register the module table in a global variable.
     This is useful in environments where functions similar to require are
     not available.

<h3>Version 1.2 (2013-04-14)</h3>

  *  Download [./raw/dkjson.lua?name=4a05ad81d10e8cd5c27f7eb985717fefb26f8044 | dkjson.lua version 1.2]

Changes since version 1.1:

  *  Corrected the range of escaped characters.  Among other characters
     U+2029 was missing, which would cause trouble when parsed by a
     JavaScript interpreter.
  *  Locations for error messages were off by one in the first line.


<h3>Version 2.2 (2012-04-28)</h3>

  *  Download [./raw/dkjson.lua?name=2e0832b4027614d5d5c708a971d4f1c6ec04affb | dkjson.lua version 2.2]

Changes since version 2.1:

  *  __jsontype is only used for empty tables.
  *  It is possible to decode tables without assigning metatables.
  *  Locations for error messages were off by one in the first line.
  *  There is no LPeg version of json.quotestring anymore.

<h3>Version 2.1 (2011-07-08)</h3>

  *  Download [./raw/dkjson.lua?name=6bb6b9b6a57c0013caaf74a0be212c20ce6cf689 | dkjson.lua version 2.1]

Changes since version 2.0:

  *  Changed the documentation to Markdown format.
  *  LPeg is now parsing only a single value at a time to avoid running
     out of Lua stack for big arrays and objects.
  *  Read __tojson, __jsontype and __jsonorder even from blocked metatables
     through the debug module.
  *  Fixed decoding single numbers (only affected the non-LPeg mode).
  *  Corrected the range of escaped Unicode control characters.

<h3>Version 1.1 (2011-07-08)</h3>

  *  Download [./raw/dkjson.lua?name=32a53e69326ac6231c942f0175700cb119ac8108 | dkjson.lua version 1.1]

Changes since version 1.0:

  *  The values NaN/+Inf/-Inf are recognised and encoded as "null" like in
     the original JavaScript implementation.
  *  Read __tojson even from blocked metatables through the debug module.
  *  Fixed decoding single numbers.
  *  Corrected the range of escaped Unicode control characters.

<h3>Version 2.0 (2011-05-30)</h3>

  *  Download [./raw/dkjson.lua?name=35630290e43b332a84fb3a5504765ef6db8b7c49 | dkjson.lua version 2.0]

Changes since version 1.0:

  *  Optional LPeg support.
  *  Invalid input data for encoding raises errors instead of returning nil
     and the error message. (Invalid data for encoding is usually a
     programming error. Raising an error removes the work of explicitly
     checking the result).
  *  The metatable field __jsontype can control whether a Lua table is
     encoded as a JSON array or object. (Mainly useful for empty tables).
  *  When decoding, two metatables are created. One is used to mark the arrays
     while the other one is used for the objects. (The metatables are
     created once for each decoding operation to make sandboxing possible.
     However, you can specify your own metatables as arguments).
  *  There are no spaces added any longer when encoding.
  *  It is possible to explicitly sort keys for encoding by providing an array with key
     names to the option "keyorder" or the metatable field __jsonorder.
  *  The values NaN/+Inf/-Inf are recognised and encoded as "null" like in
     the original JavaScript implementation.

<h3>Version 1.0 (2010-08-28)</h3>

Initial version.

  *  Download [./raw/dkjson.lua?name=718e2b58667c2ef544fed4e28fc474267e260cb1 | dkjson.lua version 1.0]

Z 0cc657e68f056b8a47f2ba4fc035e903