webmcp

view libraries/json/json.autodoc.lua @ 560:75204c64cc5f

Use CRLF instead of LF for terminating raw header
author jbe
date Tue Jun 09 13:27:58 2020 +0200 (2020-06-09)
parents 851452af0c36
children
line source
2 --[[--
3 json.null
5 A special marker to be used to write a value of null to a JSON object or JSON array. The marker is only used for setting a value to null; when reading null values from a JSON object or JSON array via the index operator, via json.get(...), or via pairs(...) or ipairs(...), then the null values will always read as nil.
7 --]]--
8 -- implemented as lightuserdata pointing to
9 -- field "nullmark" of json_lightuserdata struct
10 -- in json.c
11 --//--
14 --[[--
15 obj = -- a new JSON object
16 json.object{
17 key1 = value1, -- key value pair to be set in JSON object
18 key2 = value2, -- another key value pair to be set in JSON object
19 ...
20 }
22 Converts a Lua table (or any other value with a __pairs metamethod) to a JSON object. The argument is never modified. May also be called without arguments to create an empty JSON object. All JSON objects support iteration using pairs(...). When accessing or iterating over JSON objects, null values will read as nil. To set a value to null, it needs to be set to the special value of json.null though. Setting a value to nil will delete the field.
24 --]]--
25 -- implemented as in json.c as
26 -- static int json_object(lua_State *L)
27 --//--
30 --[[--
31 ary = -- a new JSON array
32 json.array{
33 value1, -- first value to be set in JSON array
34 value2, -- second value to be set in JSON array
35 ...
36 }
38 Converts a Lua table (or any other value with __len and __index metamethods) to a JSON array. The argument is never modified. May also be called without arguments to create an empty JSON array. All JSON arrays support iteration using ipairs(...). When accessing or iterating over JSON arrays, null values will read as nil. To set a value to null, it needs to be set to the special value of json.null though. Setting a value to nil will delete the entry. The length operator (#) returns meaningful results if and only if the set of positive integer keys which have a value assigned (including the special value of null) is equal to the set of all numbers from 1 to some integer n (i.e. the array contains no gaps, but intermediate null values are allowed).
40 --]]--
41 -- implemented in json.c as
42 -- static int json_object(lua_State *L)
43 --//--
46 --[[--
47 value, -- parsed value/document, or nil in case of error
48 errmsg = -- error message if document could not be parsed
49 json.import(
50 str -- string to be parsed
51 )
53 Parses a JSON document. Returns a string, a number, a boolean, json.null, or a JSON object or JSON array as returned by json.object{...} or json.array{...} respectively. The special value json.null is only returned if the top-level value is null; null values within the document always read as nil (see json.null).
55 --]]--
56 -- implemented in json.c as
57 -- static int json_import(lua_State *L)
58 --//--
61 --[[--
62 value = -- value that has been read, or nil if path does not exist
63 json.get(
64 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
65 key1, -- first path element (e.g. a string key to descent into an object)
66 key2, -- second path element (e.g. an integer key to descent into an array)
67 ...,
68 last_key -- last path element
69 )
71 Reads a value from a JSON document by following a given path that may contain string keys (to descent into an object) or integer keys (to descent into an array). A JSON value of null is returned as nil. This function also works on plain Lua tables instead of JSON objects/arrays.
73 Examples:
74 json.get(json.import('{"a": {"b": 3}}'), "a", "b") == 3
75 json.get(json.import('{"a": {"b": 3}}'), "c", "d") == nil
76 json.get(json.import('{"n": null}'), "n") == nil
77 json.get({a = {b = 3}}, "a", "b") == 3
79 --]]--
80 -- implemented in json.c as
81 -- static int json_get(lua_State *L)
82 --//--
85 --[[--
86 type_str = -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
87 json.type(
88 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
89 key1, -- first path element (e.g. a string key to descent into an object)
90 key2, -- second path element (e.g. an integer key to descent into an array)
91 ...,
92 last_key -- last path element
93 )
95 Determines the type of a value in a JSON document by following a given path that may contain string keys (to descent into an object) or integer keys (to descent into an array). If the path but its last path element could be followed, then the string "nil" is returned. If the previous path elements could not be followed, then nil itself (no string) is returned. Otherwise the type of the value is returned, whereas the string "null" indicates a JSON null value. This function also works on plain Lua tables instead of JSON documents.
97 Examples:
98 json.type(json.import('{"a": {"b": 3}}'), "a", "b") == 3
99 json.type(json.import('{"a": {"b": null}}'), "a", "b") == "null"
100 json.type(json.import('{"a": {"b": null}}'), "a", "c") == "nil"
101 json.type(json.import('{"a": {"b": null}}'), "d", "c") == nil
103 --]]--
104 -- implemented in json.c as
105 -- static int json_type(lua_State *L)
106 --//--
109 --[[--
110 document = -- first argument is returned for convenience
111 json.set(
112 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
113 value, -- new value to be set within the document
114 key1, -- first path element (e.g. a string key to descent into an object)
115 key2, -- second path element (e.g. an integer key to descent into an array)
116 ...
117 last_key -- last path element
118 )
120 Sets a value in a JSON document by following a given path that may contain string keys (to descent into an object) or integer keys (to descent into an array). If the path does not exist (or contains objects where arrays are expected or vice versa), then the necessary intermediate JSON objects or JSON arrays are created. This function also works on plain Lua tables but will create JSON objects or arrays where necessary.
122 --]]--
123 -- implemented in json.c as
124 -- static int json_set(lua_State *L)
125 --//--
128 --[[--
129 str = -- encoded JSON document as string
130 json.export(
131 document, -- JSON value (object, array, string, number, boolean, null), or a Lua table
132 indentation -- optional indentation string for pretty printing, or true for two spaces
133 )
135 Encodes a JSON document. Both json.null and nil are accepted to encode the null value on top-level. Since the order of object keys is deterministic, this function may also be used to compare two JSON documents for equality: json.export(a) == json.export(b). If the indentation argument is nil or false, then pretty printing is disabled.
137 --]]--
138 -- implemented in json.c as
139 -- static int json_export(lua_State *L)
140 --//--

Impressum / About Us