README.md

   1 ## LuaJSON
   2 JSON Parser/Constructor for Lua
   3
   4 ### Author:
   5 Thomas Harning Jr. <harningt@gmail.com>
   6
   7 ### Source code:
   8 http://repo.or.cz/luajson
   9
  10 ### Bug reports:
  11 http://github.com/harningt/luajson
  12 harningt@gmail.com
  13
  14 ### Requirements
  15 Lua 5.1, 5.2, 5.3, LuaJIT 2.0, or LuaJIT 2.1
  16 LPeg (Tested with 0.7, 0.8, 0.9, 0.10, 0.12rc2, 1.0.1)
  17 For regressionTest:
  18         lfs (Tested with 1.6.3)
  19 ### For lunit-tests:
  20 lunitx >= 0.8
  21
  22 ### NOTE:
  23 LPeg 0.11 may not work - it crashed during my initial tests,
  24 it is not in the test matrix.
  25
  26 ### Lua versions tested recently:
  27 * Lua 5.1.5
  28 * Lua 5.2.4
  29 * Lua 5.3.4
  30 * LuaJIT-2.0.4
  31 * LuaJIT-2.1.0-beta2
  32
  33 ### License
  34 All-but tests: MIT-style, See LICENSE for details
  35 tests/*:       Public Domain / MIT - whichever is least restrictive
  36
  37 ### Module/Function overview:
  38 ### json.encode (callable module referencing json.encode.encode)
  39 ___encode ( value : ANY-valid )___
  40
  41 Takes in a JSON-encodable value and returns the JSON-encoded text
  42 Valid input types:
  43 * table
  44 * array-like table (spec below)
  45 * string
  46 * number
  47 * boolean
  48 * 'null' - represented by json.util.null
  49
  50 Table keys (string,number,boolean) are encoded as strings, others are erroneus
  51 Table values are any valid input-type
  52 Array-like tables are converted into JSON arrays...
  53 Position 1 maps to JSON Array position 0
  54
  55 ### json.decode (callable module referencing json.decode.decode)
  56 ___decode (data : string, strict : optional boolean)___
  57
  58 Takes in a string of JSON data and converts it into a Lua object
  59 If 'strict' is set, then the strict JSON rule-set is used
  60
  61 ### json.util
  62 #### Useful utilities
  63 ___null___
  64
  65 Reference value to represent 'null' in a well-defined way to
  66 allow for null values to be inserted into an array/table
  67
  68    undefined
  69
  70 Reference value to represent 'undefined' in a well-defined
  71 way to allow for undefined values to be inserted into an
  72 array/table.
  73
  74    IsArray (t : ANY)
  75
  76 Checks if the passed in object is a plain-old-array based on
  77 whether or not is has the LuaJSON array metatable attached
  78 or the custom __is_luajson_array metadata key stored.
  79
  80    InitArray(t: table)
  81
  82 Sets the 'array' marker metatable to guarantee the table is
  83 represented as a LuaJSON array type.
  84
  85    isCall (t : ANY)
  86
  87 Checks if the passed in object is a LuaJSON call object.
  88
  89    buildCall(name : string, ... parameters)
  90
  91 Builds a call object with the given name and set of parameters.
  92 The name is stored in the 'name' field and the parameters in
  93 the 'parameters' field as an array.
  94
  95 #### Additional Utilities
  96    clone (t : table)
  97
  98 Shallow-clones a table by iterating using pairs and assigning.
  99
 100 ___printValue (tab : ANY, name : string)
 101
 102 recursively prints out all object values - if duplicates found, reference printed
 103
 104 ___merge (t : table, ... : tables)
 105
 106 Shallow-merges a sequence of tables onto table t by iterating over each using
 107 pairs and assigning.
 108
 109 #### Internal Utilities - Not to Use
 110    decodeCall
 111    doOptionMerge
 112
 113 ### Attribution
 114 parsing test suite from JSON_checker project of http://www.json.org/
 115 No listed license for these files in their package.