LuaJSON(3) ========== :Author: Thomas Harning :Email: harningt@gmail.com :Date: 2009/04/29 NAME ---- luajson - JSON encoder/decoder for Lua SYNOPSIS -------- require("json") json.decode("json-string" [, parameters]) json.decode.getDecoder(parameters) json.encode(lua_value [, parameters]) json.encode.getEncoder(parameters) DESCRIPTION ----------- json.decode("json-string" [, parameters]):: Obtains a JSON decoder using `getDecoder` with the parameters specified, then performs the decoding operation. json.encode(lua_value [, parameters]):: Obtains a JSON encoder using `getEncoder` with the parameters specified, then performs the encoding operation. json.decode.getDecoder(parameters):: Obtains a JSON decoder configured with the given parameters or defaults. json.encode.getEncoder(parameters):: Obtains a JSON encoder configured with the given parameters or defaults. json.encode.strict:: A default parameter specification containing 'strict' rules for encoding json.decode.strict:: A default parameter specification containing 'strict' rules for decoding === COMMON PARAMETERS initialObject : boolean:: Specifies if the outermost element be an array or object allowUndefined : boolean:: Specifies if 'undefined' is an allowed value null : any:: Placeholder object for null values undefined : any:: Placeholder for undefined values number.nan : boolean:: Specifies if NaN is an allowed value number.inf : boolean:: Specifies if +/-Infinity is an allowed value === ENCODER-SPECIFIC PARAMETERS preProcess : `function(object)`:: Called for every value to be encoded, optionally altering. If returns `nil` then no value change occurs. output : function:: Function that returns an encoder specification (TBD), if null default used that returns a string. array.isArray : `function(object)`:: If `true`/`false` returned, then the value is authoritatively an array or not strings.xEncode : boolean:: Specifies if binary values are to be encoded with \xNN rather than \uNNNN strings.encodeSet : string:: http://www.lua.org/manual/5.1/manual.html#5.4.1[gmatch-style] set of characters that need to be escaped (to be contained in `[]`) strings.encodeSetAppend : string:: Set of characters that need to be escaped (to be contained in `[]`). Appended to the current encodeSet. ==== Default Configuration [source,lua] ---- array.isArray == json-util's isArray implementation allowUndefined = true number.nan = true number.inf = true strings.xEncode = false strings.encodeSet = '\\"/%z\1-\031' ---- ==== Strict Configuration [source,lua] ---- initialObject = true allowUndefined = false number.nan = false number.inf = false ---- === DECODER-SPECIFIC PARAMETERS unicodeWhitespace : boolean:: Specifies if unicode whitespace characters are counted array.trailingComma / object.trailingComma : boolean:: Specifies if extraneous trailing commas are ignored in declaration calls.defs : map<string | LPEG, function | boolean>:: Defines set of specifically permitted function definitions. If boolean value, determines if allowed or not, decoded as a call object. Function return-value is the decoded result. Function definition: `function(name, [arguments])` : output-value calls.allowUndefined : boolean:: Specifies if undefined call definitions are decoded as call objects. number.frac : boolean:: Specifies if numbers can have a decimal component (ex: `.01`) number.exp : boolean:: Specifies if exponents are allowed (ex: `1e2`) number.hex : boolean:: Specifies if hexadecimal numbers are allowed (ex: `0xDEADBEEF`) object.number : boolean:: Specifies if numbers can be object keys object.identifier : boolean:: Specifies if unquoted 'identifiers' can be object keys (matching `[A-Za-z_][A-Za-z0-9_]*`) strings.badChars : string:: Set of characters that should not be present in a string strings.additionalEscapes : LPeg expression:: LPeg expression to handle output (ex: `lpeg.C(1)` would take `\k` and spit out `k`) strings.escapeCheck : non-consuming LPeg expression:: LPeg expression to check if a given character is allowed to be an escape value strings.decodeUnicode:: `function (XX, YY)` handling \uXXYY situation to output decoded unicode sequence strings.strict_quotes : boolean:: Specifies if the `'` character is considered a quoting specifier ==== Default configuration [source,lua] ---- unicodeWhitespace = true initialObject = false allowUndefined = true array.trailingComma = true number.frac = true number.exp = true number.hex = false object.number = true object.identifier = true object.trailingComma = true strings.badChars = '' -- No characters considered bad in a string strings.additionalEscapes = false, -- disallow untranslated escapes strings.escapeCheck = #lpeg.S('bfnrtv/\\"xu\'z'), strings.decodeUnicode = utf8DecodeUnicode, strings.strict_quotes = false ---- ==== Strict configuration [source,lua] ---- initialObject = true allowUndefined = false array.trailingComma = false object.identifier = false object.trailingComma = false strings.badChars = '\b\f\n\r\t\v' strings.additionalEscapes = false -- no additional escapes strings.escapeCheck = #lpeg.S('bfnrtv/\\"u') --only these are allowed to be escaped strings.strict_quotes = true ---- AUTHOR ------ Written by Thomas Harning Jr., <harningt@gmail.com> REFERENCES ---------- http://www.inf.puc-rio.br/~roberto/lpeg[LPeg] http://json.org[JSON] COPYING ------- Copyright (C) 2008-2009 Thomas Harning Jr. Free use of this software is granted under the terms of the MIT license.