docs/LuaJSON.txt

   1 LuaJSON(3)
   2 ==========
   3 :Author: Thomas Harning
   4 :Email:  harningt@gmail.com
   5 :Date:   2009/04/29
   6
   7 NAME
   8 ----
   9 luajson - JSON encoder/decoder for Lua
  10
  11 SYNOPSIS
  12 --------
  13 require("json")
  14
  15 json.decode("json-string" [, parameters])
  16
  17 json.decode.getDecoder(parameters)
  18
  19 json.encode(lua_value [, parameters])
  20
  21 json.encode.getEncoder(parameters)
  22
  23 DESCRIPTION
  24 -----------
  25 json.decode("json-string" [, parameters])::
  26     Obtains a JSON decoder using `getDecoder` with the parameters specified,
  27     then performs the decoding operation.
  28
  29 json.encode(lua_value [, parameters])::
  30     Obtains a JSON encoder using `getEncoder` with the parameters specified,
  31     then performs the encoding operation.
  32
  33 json.decode.getDecoder(parameters)::
  34     Obtains a JSON decoder configured with the given parameters or defaults.
  35
  36 json.encode.getEncoder(parameters)::
  37     Obtains a JSON encoder configured with the given parameters or defaults.
  38
  39 json.encode.strict::
  40     A default parameter specification containing 'strict' rules for encoding
  41
  42 json.decode.strict::
  43     A default parameter specification containing 'strict' rules for decoding
  44
  45 === COMMON PARAMETERS
  46
  47 initialObject : boolean::
  48     Specifies if the outermost element be an array or object
  49
  50 allowUndefined : boolean::
  51     Specifies if 'undefined' is an allowed value
  52
  53 null : any::
  54     Placeholder object for null values
  55
  56 undefined : any::
  57     Placeholder for undefined values
  58
  59 number.nan : boolean::
  60     Specifies if NaN is an allowed value
  61
  62 number.inf : boolean::
  63     Specifies if +/-Infinity is an allowed value
  64
  65 === ENCODER-SPECIFIC PARAMETERS
  66
  67 preProcess : `function(object)`::
  68     Called for every value to be encoded, optionally altering.
  69     If returns `nil` then no value change occurs.
  70
  71 output : function::
  72     Function that returns an encoder specification (TBD), if null
  73     default used that returns a string.
  74
  75 array.isArray : `function(object)`::
  76     If `true`/`false` returned, then the value is authoritatively
  77     an array or not
  78
  79 strings.xEncode : boolean::
  80     Specifies if binary values are to be encoded with \xNN rather than \uNNNN
  81
  82 strings.encodeSet : string::
  83     http://www.lua.org/manual/5.1/manual.html#5.4.1[gmatch-style] set of
  84     characters that need to be escaped (to be contained in `[]`)
  85
  86 strings.encodeSetAppend : string::
  87     Set of characters that need to be escaped (to be contained in `[]`).
  88     Appended to the current encodeSet.
  89
  90 ==== Default Configuration
  91 [source,lua]
  92 ----
  93 array.isArray == json-util's isArray implementation
  94 allowUndefined = true
  95 number.nan = true
  96 number.inf = true
  97 strings.xEncode = false
  98 strings.encodeSet = '\\"/%z\1-\031'
  99 ----
 100
 101 ==== Strict Configuration
 102 [source,lua]
 103 ----
 104 initialObject = true
 105 allowUndefined = false
 106 number.nan = false
 107 number.inf = false
 108 ----
 109
 110 === DECODER-SPECIFIC PARAMETERS
 111
 112 unicodeWhitespace : boolean::
 113     Specifies if unicode whitespace characters are counted
 114
 115 array.trailingComma / object.trailingComma : boolean::
 116     Specifies if extraneous trailing commas are ignored in declaration
 117
 118 calls.defs : map<string | LPEG, function | boolean>::
 119     Defines set of specifically permitted function definitions.
 120     If boolean value, determines if allowed or not, decoded as a call object.
 121     Function return-value is the decoded result.
 122     Function definition:  `function(name, [arguments])` : output-value
 123
 124 calls.allowUndefined : boolean::
 125     Specifies if undefined call definitions are decoded as call objects.
 126
 127 number.frac : boolean::
 128     Specifies if numbers can have a decimal component (ex: `.01`)
 129
 130 number.exp : boolean::
 131     Specifies if exponents are allowed (ex: `1e2`)
 132
 133 number.hex : boolean::
 134     Specifies if hexadecimal numbers are allowed (ex: `0xDEADBEEF`)
 135
 136 object.number : boolean::
 137     Specifies if numbers can be object keys
 138
 139 object.identifier : boolean::
 140     Specifies if unquoted 'identifiers' can be object keys (matching `[A-Za-z_][A-Za-z0-9_]*`)
 141
 142 strings.badChars : string::
 143     Set of characters that should not be present in a string
 144
 145 strings.additionalEscapes : LPeg expression::
 146     LPeg expression to handle output (ex: `lpeg.C(1)` would take `\k` and spit out `k`)
 147
 148 strings.escapeCheck : non-consuming LPeg expression::
 149     LPeg expression to check if a given character is allowed to be an escape value
 150
 151 strings.decodeUnicode::
 152     `function (XX, YY)` handling \uXXYY situation to output decoded unicode sequence
 153
 154 strings.strict_quotes : boolean::
 155     Specifies if the `'` character is considered a quoting specifier
 156
 157 ==== Default configuration
 158
 159 [source,lua]
 160 ----
 161 unicodeWhitespace = true
 162 initialObject = false
 163 allowUndefined = true
 164 array.trailingComma = true
 165 number.frac = true
 166 number.exp = true
 167 number.hex = false
 168 object.number = true
 169 object.identifier = true
 170 object.trailingComma = true
 171 strings.badChars = '' -- No characters considered bad in a string
 172 strings.additionalEscapes = false, -- disallow untranslated escapes
 173 strings.escapeCheck = #lpeg.S('bfnrtv/\\"xu\'z'),
 174 strings.decodeUnicode = utf8DecodeUnicode,
 175 strings.strict_quotes = false
 176 ----
 177
 178 ==== Strict configuration
 179
 180 [source,lua]
 181 ----
 182 initialObject = true
 183 allowUndefined = false
 184 array.trailingComma = false
 185 object.identifier = false
 186 object.trailingComma = false
 187 strings.badChars = '\b\f\n\r\t\v'
 188 strings.additionalEscapes = false -- no additional escapes
 189 strings.escapeCheck = #lpeg.S('bfnrtv/\\"u') --only these are allowed to be escaped
 190 strings.strict_quotes = true
 191 ----
 192
 193 AUTHOR
 194 ------
 195 Written by Thomas Harning Jr., <harningt@gmail.com>
 196
 197 REFERENCES
 198 ----------
 199 http://www.inf.puc-rio.br/~roberto/lpeg[LPeg]
 200
 201 http://json.org[JSON]
 202
 203 COPYING
 204 -------
 205 Copyright (C) 2008-2009 Thomas Harning Jr.  Free use of this software is granted
 206 under the terms of the MIT license.