1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
Lua CJSON v1.0
==============
Lua CJSON is covered by the MIT license. See the file "LICENSE" for
details.
Lua CJSON provides fast JSON parsing and encoding support for Lua.
Features:
- 10x to 20x quicker (or more) than the fastest pure Lua JSON modules.
- Full support for JSON with UTF-8, including decoding surrogate
pairs.
- Optionally supports common JSON extensions (NaN, Inf,..).
Caveats:
- UTF-16 and UTF-32 are not supported.
- Multiple OS threads within a single Lua state are not currently
supported.
To obtain the latest version of Lua CJSON visit:
http://www.kyne.com.au/~mark/software/lua-cjson.php
Feel free to email me if you have any patches, suggestions, or comments.
- Mark Pulford <mark@kyne.com.au>
Installing
==========
Build requirements:
- Lua (http://www.lua.org/)
Or:
- LuaJIT (http://www.luajit.org/)
The included Makefile should be reviewed and updated based on the
location of your Lua header and library directories. Then:
# make
# make install
OR
# cp cjson.so [your_module_directory]
Linux distributions using RPM should be able to build a package with
the following command:
# rpmbuild -tb lua-cjson-1.0.tar.gz
Lua CJSON API
=============
Synopsis
--------
require "cjson"
-- Or:
local cjson = require "cjson"
-- Translate Lua value to/from JSON
text = cjson.encode(value)
value = cjson.decode(text)
-- Get and/or Set CJSON configuration
setting = cjson.refuse_invalid_numbers([setting])
depth = cjson.encode_max_depth([depth])
convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
Encoding
--------
json_text = cjson.encode(value)
cjson.encode() will serialise the following types:
* number, string, table, boolean, lightuserdata (NULL) or nil
The remaining Lua types cannot be serialised:
* thread, userdata, lightuserdata (non-NULL), function
Numbers are encoded using the standard Lua number format.
ASCII 0 - 31, double-quote, forward-slash, black-slash and ASCII 127
are escaped when encoding strings. Other octets are passed
transparently. It is expected the application will perform UTF-8 error
checking if required.
If a Lua table only contains positive integer keys (>0) it is encoded
as an array, otherwise it will be encoded as an object.
A Lua table will only recognised as an array if all keys are type
"number", and are positive integers (>0). Otherwise CJSON will encode
the table as a JSON object.
CJSON will also recognise and handle sparse arrays. Missing entries
will be encoded as "null". Eg:
{ [3] = "data" }
becomes:
[ null, null, "data" ]
Note: standards compliant JSON must be encapsulated in either an
object ({}) or an array ([]). Hence you must pass a table to
cjson.encode() if you want to generate standards compliant JSON
output.
By default, errors will be raised for:
- Excessively sparse arrays (see below)
- More than 20 nested tables
- Invalid numbers (NaN, Infinity)
These defaults can be changed with:
- cjson.encode_sparse_array()
- cjson.encode_max_depth()
- cjson.refuse_invalid_numbers()
Example:
data_obj = { true, { foo = "bar" } }
data_json = cjson.encode(data_obj)
Decoding
--------
value = cjson.decode(json_text)
cjson.decode() will deserialise any UTF-8 JSON string into a Lua data
structure. It can return any of the types that cjson.encode()
supports.
UTF-16 and UTF-32 JSON strings are not supported.
CJSON only requires that NULL (\0) and double quote (\") are escaped
within strings. All other octets will be passed transparently. UTF-8
characters are not validated and should be checked elsewhere if
desired.
JSON "null" will be converted to a NULL lightuserdata value. This can
be compared with cjson.null for convenience.
By default, invalid numbers (NaN, Infinity, Hex) will be decoded
correctly.
Example:
data_json = '[ true, { "foo": "bar" } ]'
data_obj = cjson.decode(data_json)
Invalid numbers
---------------
setting = cjson.refuse_invalid_numbers([setting])
-- "setting" must be on of:
-- false, "encode", "decode", "both", true
CJSON considers numbers which are outside the JSON specification to be
"invalid". Eg:
- Infinity
- NaN
- Hexadecimal numbers
This setting can be configured separately for encoding and/or
decoding:
- Enabled: an error will be generated if an invalid number is found.
- Disabled (encoding): NaN and Infinity can be encoded.
- Disabled (decoding): All numbers supported by strtod(3) will be
parsed.
Sparse arrays
-------------
convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
-- "convert" must be a boolean. Default: false.
-- "ratio" must be a positive integer (>0). Default: 2
-- "safe" must be a positive integer (>0). Default: 10
CJSON detects excessively sparse arrays by comparing the number of
items in an array with the maximum index. An excessively sparse array
is defined as:
max_index > safe AND max_index > items * ratio
Eg:
{ [1000] = "excessively sparse array" }
Setting "ratio" to 0 disables checking for excessively sparse arrays.
When "convert" is enabled, CJSON will encode excessively sparse arrays
as JSON objects.
Nested tables
-------------
depth = cjson.encode_max_depth([depth])
-- "depth" must be a positive integer (>0).
By default, CJSON will reject data structure with more than 20 nested
tables.
This check is used to prevent a nested data structure from crashing
the application. Eg:
a = {}; b = { a }; a[1] = b
References
==========
- http://tools.ietf.org/html/rfc4627
- http://www.json.org/
|
