diff options
author | Thibault Charbonnier <thibaultcha@me.com> | 2016-02-29 21:39:26 -0800 |
---|---|---|
committer | Yichun Zhang (agentzh) <agentzh@gmail.com> | 2016-03-14 14:20:27 -0700 |
commit | e1ebda146f63276093970f1bec36e51f952b3dba (patch) | |
tree | 7cfd2c1162fa0655984e9b2e011d96094ca17a63 | |
parent | 7a9c25ee69f38974e99322971eace37ba1753074 (diff) | |
download | lua-cjson-e1ebda146f63276093970f1bec36e51f952b3dba.tar.gz lua-cjson-e1ebda146f63276093970f1bec36e51f952b3dba.tar.bz2 lua-cjson-e1ebda146f63276093970f1bec36e51f952b3dba.zip |
docs: add a README with fork infos
-rw-r--r-- | README.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..7282a4d --- /dev/null +++ b/README.md | |||
@@ -0,0 +1,124 @@ | |||
1 | Name | ||
2 | ==== | ||
3 | |||
4 | lua-cjson - Fast JSON encoding/parsing | ||
5 | |||
6 | Table of Contents | ||
7 | ================= | ||
8 | |||
9 | * [Name](#name) | ||
10 | * [Description](#description) | ||
11 | * [Additions to mpx/lua](#additions) | ||
12 | * [encode_empty_table_as_object](#encode_empty_table_as_object) | ||
13 | * [empty_array](#empty_array) | ||
14 | * [empty_array_mt](#empty_array_mt) | ||
15 | * [encode_number_precision](#encode_number_precision) | ||
16 | |||
17 | Description | ||
18 | =========== | ||
19 | |||
20 | This fork of [mpx/lua-cjson](https://github.com/mpx/lua-cjson) is included in | ||
21 | the [OpenResty](https://openresty.org/) bundle and includes a few bugfixes and | ||
22 | improvements, especially to facilitate the encoding of empty tables as JSON Arrays. | ||
23 | |||
24 | Please refer to the [lua-cjson documentation](http://www.kyne.com.au/~mark/software/lua-cjson.php) | ||
25 | for standard usage, this README only provides informations regarding this fork's additions. | ||
26 | |||
27 | See [`mpx/master..openresty/master`](https://github.com/mpx/lua-cjson/compare/master...openresty:master) | ||
28 | for the complete history of changes. | ||
29 | |||
30 | [Back to TOC](#table-of-contents) | ||
31 | |||
32 | Additions | ||
33 | ========= | ||
34 | |||
35 | encode_empty_table_as_object | ||
36 | ---------------------------- | ||
37 | **syntax:** `cjson.encode_empty_table_as_object(true|false|"on"|"off")` | ||
38 | |||
39 | Change the default behavior when encoding an empty Lua table. | ||
40 | |||
41 | By default, empty Lua tables are encoded as empty JSON Objects (`{}`). If this is set to false, | ||
42 | empty Lua tables will be encoded as empty JSON Arrays instead (`[]`). | ||
43 | |||
44 | This method either accepts a boolean or a string (`"on"`, `"off"`). | ||
45 | |||
46 | [Back to TOC](#table-of-contents) | ||
47 | |||
48 | empty_array | ||
49 | ----------- | ||
50 | **syntax:** `cjson.empty_array` | ||
51 | |||
52 | A lightuserdata, similar to `cjson.null`, which will be encoded as an empty JSON Array by | ||
53 | `cjson.encode()`. | ||
54 | |||
55 | For example, since `encode_empty_table_as_object` is `true` by default: | ||
56 | |||
57 | ```lua | ||
58 | local cjson = require "cjson" | ||
59 | |||
60 | local json = cjson.encode({ | ||
61 | foo = "bar", | ||
62 | some_object = {}, | ||
63 | some_array = cjson.empty_array | ||
64 | }) | ||
65 | ``` | ||
66 | |||
67 | This will generate: | ||
68 | |||
69 | ```json | ||
70 | { | ||
71 | "foo": "bar", | ||
72 | "some_object": {}, | ||
73 | "some_array": [] | ||
74 | } | ||
75 | ``` | ||
76 | |||
77 | [Back to TOC](#table-of-contents) | ||
78 | |||
79 | empty_array_mt | ||
80 | -------------- | ||
81 | **syntax:** `setmetatable({}, cjson.empty_array_mt)` | ||
82 | |||
83 | A metatable which can "tag" a table as a JSON Array in case it is empty (that is, if the | ||
84 | table has no elements, `cjson.encode()` will encode it as an empty JSON Array). | ||
85 | |||
86 | Instead of: | ||
87 | |||
88 | ```lua | ||
89 | local function serialize(arr) | ||
90 | if #arr < 1 then | ||
91 | arr = cjson.empty_array | ||
92 | end | ||
93 | |||
94 | return cjson.encode({some_array = arr}) | ||
95 | end | ||
96 | ``` | ||
97 | |||
98 | This is more concise: | ||
99 | |||
100 | ```lua | ||
101 | local function serialize(arr) | ||
102 | setmetatable(arr, cjson.empty_array_mt) | ||
103 | |||
104 | return cjson.encode({some_array = arr}) | ||
105 | end | ||
106 | ``` | ||
107 | |||
108 | Both will generate: | ||
109 | |||
110 | ```json | ||
111 | { | ||
112 | "some_array": [] | ||
113 | } | ||
114 | ``` | ||
115 | |||
116 | [Back to TOC](#table-of-contents) | ||
117 | |||
118 | encode_number_precision | ||
119 | ----------------------- | ||
120 | **syntax:** `cjson.encode_number_precision(precision)` | ||
121 | |||
122 | This fork allows encoding of numbers with a `precision` up to 16 decimals (vs. 14 in mpx/lua-cjson). | ||
123 | |||
124 | [Back to TOC](#table-of-contents) | ||