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 local json = 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.allowEmptyElement / calls.allowEmptyElement / object.allowEmptyElement : boolean::
 116         Specifies if missing values are allowed, replacing them with the value of 'undefined' or 'null' if undefined not allowed.
 117         Example cases:
 118                 [1,, 3] ==> { 1, json.util.undefined, 3 }
 119                 { x: }  ==> { x = json.util.undefined }
 120                 call(1,, 3) ==> call(1, json.util.undefined, 3)
 121
 122 array.trailingComma / calls.trailingComma / object.trailingComma : boolean::
 123     Specifies if extraneous trailing commas are ignored in declaration
 124
 125 calls.defs : map<string | LPEG, function | boolean>::
 126     Defines set of specifically permitted function definitions.
 127     If boolean value, determines if allowed or not, decoded as a call object.
 128     Function return-value is the decoded result.
 129     Function definition:  `function(name, [arguments])` : output-value
 130
 131 calls.allowUndefined : boolean::
 132     Specifies if undefined call definitions are decoded as call objects.
 133
 134 number.frac : boolean::
 135     Specifies if numbers can have a decimal component (ex: `.01`)
 136
 137 number.exp : boolean::
 138     Specifies if exponents are allowed (ex: `1e2`)
 139
 140 number.hex : boolean::
 141     Specifies if hexadecimal numbers are allowed (ex: `0xDEADBEEF`)
 142
 143 object.number : boolean::
 144     Specifies if numbers can be object keys
 145
 146 object.identifier : boolean::
 147     Specifies if unquoted 'identifiers' can be object keys (matching `[A-Za-z_][A-Za-z0-9_]*`)
 148
 149 strings.badChars : string::
 150     Set of characters that should not be present in a string
 151
 152 strings.additionalEscapes : LPeg expression::
 153     LPeg expression to handle output (ex: `lpeg.C(1)` would take `\k` and spit out `k`)
 154
 155 strings.escapeCheck : non-consuming LPeg expression::
 156     LPeg expression to check if a given character is allowed to be an escape value
 157
 158 strings.decodeUnicode::
 159     `function (XX, YY)` handling \uXXYY situation to output decoded unicode sequence
 160
 161 strings.strict_quotes : boolean::
 162     Specifies if the `'` character is considered a quoting specifier
 163
 164 ==== Default configuration
 165
 166 [source,lua]
 167 ----
 168 unicodeWhitespace = true
 169 initialObject = false
 170 allowUndefined = true
 171 array.trailingComma = true
 172 number.frac = true
 173 number.exp = true
 174 number.hex = false
 175 object.number = true
 176 object.identifier = true
 177 object.trailingComma = true
 178 strings.badChars = '' -- No characters considered bad in a string
 179 strings.additionalEscapes = false, -- disallow untranslated escapes
 180 strings.escapeCheck = #lpeg.S('bfnrtv/\\"xu\'z'),
 181 strings.decodeUnicode = utf8DecodeUnicode,
 182 strings.strict_quotes = false
 183 ----
 184
 185 ==== Strict configuration
 186
 187 [source,lua]
 188 ----
 189 initialObject = true
 190 allowUndefined = false
 191 array.trailingComma = false
 192 object.identifier = false
 193 object.trailingComma = false
 194 strings.badChars = '\b\f\n\r\t\v'
 195 strings.additionalEscapes = false -- no additional escapes
 196 strings.escapeCheck = #lpeg.S('bfnrtv/\\"u') --only these are allowed to be escaped
 197 strings.strict_quotes = true
 198 ----
 199
 200 AUTHOR
 201 ------
 202 Written by Thomas Harning Jr., <harningt@gmail.com>
 203
 204 REFERENCES
 205 ----------
 206 http://www.inf.puc-rio.br/~roberto/lpeg[LPeg]
 207
 208 http://json.org[JSON]
 209
 210 COPYING
 211 -------
 212 Copyright (C) 2008-2009 Thomas Harning Jr.  Free use of this software is granted
 213 under the terms of the MIT license.