manual.txt 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168
  1. = Lua CJSON 2.1devel Manual =
  2. Mark Pulford <mark@kyne.com.au>
  3. :revdate: 1st March 2012
  4. Overview
  5. --------
  6. The Lua CJSON module provides JSON support for Lua.
  7. *Features*::
  8. - Fast, standards compliant encoding/parsing routines
  9. - Full support for JSON with UTF-8, including decoding surrogate pairs
  10. - Optional run-time support for common exceptions to the JSON
  11. specification (infinity, NaN,..)
  12. - No dependencies on other libraries
  13. *Caveats*::
  14. - UTF-16 and UTF-32 are not supported
  15. Lua CJSON is covered by the MIT license. Review the file +LICENSE+ for
  16. details.
  17. API (Functions)
  18. ---------------
  19. Synopsis
  20. ~~~~~~~~
  21. [source,lua]
  22. ------------
  23. -- Translate Lua value to/from JSON
  24. text = cjson.encode(value)
  25. value = cjson.decode(text)
  26. Module Instantiation
  27. ~~~~~~~~~~~~~~~~~~~~
  28. decode
  29. ~~~~~~
  30. [source,lua]
  31. ------------
  32. value = cjson.decode(json_text)
  33. ------------
  34. +cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value
  35. or table.
  36. UTF-16 and UTF-32 JSON strings are not supported.
  37. +cjson.decode+ requires that any NULL (ASCII 0) and double quote (ASCII
  38. 34) characters are escaped within strings. All escape codes will be
  39. decoded and other bytes will be passed transparently. UTF-8 characters
  40. are not validated during decoding and should be checked elsewhere if
  41. required.
  42. JSON +null+ will be converted to a NULL +lightuserdata+ value. This can
  43. be compared with +cjson.null+ for convenience.
  44. By default, numbers incompatible with the JSON specification (infinity,
  45. NaN, hexadecimal) can be decoded. This default can be changed with
  46. <<decode_invalid_numbers,+cjson.decode_invalid_numbers+>>.
  47. .Example: Decoding
  48. [source,lua]
  49. json_text = '[ true, { "foo": "bar" } ]'
  50. value = cjson.decode(json_text)
  51. -- Returns: { true, { foo = "bar" } }
  52. [CAUTION]
  53. Care must be taken after decoding JSON objects with numeric keys. Each
  54. numeric key will be stored as a Lua +string+. Any subsequent code
  55. assuming type +number+ may break.
  56. [[encode]]
  57. encode
  58. ~~~~~~
  59. [source,lua]
  60. ------------
  61. json_text = cjson.encode(value)
  62. ------------
  63. +cjson.encode+ will serialise a Lua value into a string containing the
  64. JSON representation.
  65. +cjson.encode+ supports the following types:
  66. - +boolean+
  67. - +lightuserdata+ (NULL value only)
  68. - +nil+
  69. - +number+
  70. - +string+
  71. - +table+
  72. The remaining Lua types will generate an error:
  73. - +function+
  74. - +lightuserdata+ (non-NULL values)
  75. - +thread+
  76. - +userdata+
  77. By default, numbers are encoded with 14 significant digits. Refer to
  78. <<encode_number_precision,+cjson.encode_number_precision+>> for details.
  79. Lua CJSON will escape the following characters within each UTF-8 string:
  80. - Control characters (ASCII 0 - 31)
  81. - Double quote (ASCII 34)
  82. - Forward slash (ASCII 47)
  83. - Blackslash (ASCII 92)
  84. - Delete (ASCII 127)
  85. All other bytes are passed transparently.
  86. [CAUTION]
  87. =========
  88. Lua CJSON will successfully encode/decode binary strings, but this is
  89. technically not supported by JSON and may not be compatible with other
  90. JSON libraries. To ensure the output is valid JSON, applications should
  91. ensure all Lua strings passed to +cjson.encode+ are UTF-8.
  92. Base64 is commonly used to encode binary data as the most efficient
  93. encoding under UTF-8 can only reduce the encoded size by a further
  94. &#126;8%. Lua Base64 routines can be found in the
  95. http://w3.impa.br/%7Ediego/software/luasocket/[LuaSocket] and
  96. http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/#lbase64[lbase64] packages.
  97. =========
  98. Lua CJSON uses a heuristic to determine whether to encode a Lua table as
  99. a JSON array or an object. A Lua table with only positive integer keys
  100. of type +number+ will be encoded as a JSON array. All other tables will
  101. be encoded as a JSON object.
  102. Lua CJSON does not use metamethods when serialising tables.
  103. - +rawget+ is used to iterate over Lua arrays
  104. - +next+ is used to iterate over Lua objects
  105. Lua arrays with missing entries (_sparse arrays_) may optionally be
  106. encoded in several different ways. Refer to
  107. <<encode_sparse_array,+cjson.encode_sparse_array+>> for details.
  108. JSON object keys are always strings. Hence +cjson.encode+ only supports
  109. table keys which are type +number+ or +string+. All other types will
  110. generate an error.
  111. [NOTE]
  112. Standards compliant JSON must be encapsulated in either an object (+{}+)
  113. or an array (+[]+). If strictly standards compliant JSON is desired, a
  114. table must be passed to +cjson.encode+.
  115. By default, encoding the following Lua values will generate errors:
  116. - Numbers incompatible with the JSON specification (infinity, NaN)
  117. - Tables nested more than 1000 levels deep
  118. - Excessively sparse Lua arrays
  119. .Example: Encoding
  120. [source,lua]
  121. value = { true, { foo = "bar" } }
  122. json_text = cjson.encode(value)
  123. -- Returns: '[true,{"foo":"bar"}]'
  124. // vi:ft=asciidoc tw=72: