webmcp

annotate libraries/json/json.autodoc.lua @ 466:2751b6b81c23

find changesets by author, revision, files, or words in the commit message
Minor efficiency enhancement in <db_object>:try_save() method
author jbe
date Mon Nov 07 19:32:51 2016 +0100 (2016-11-07)
parents 851452af0c36
children
rev   line source
jbe@194 1
jbe@194 2 --[[--
jbe@194 3 json.null
jbe@194 4
jbe@199 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.
jbe@194 6
jbe@194 7 --]]--
jbe@199 8 -- implemented as lightuserdata pointing to
jbe@199 9 -- field "nullmark" of json_lightuserdata struct
jbe@199 10 -- in json.c
jbe@194 11 --//--
jbe@194 12
jbe@194 13
jbe@194 14 --[[--
jbe@194 15 obj = -- a new JSON object
jbe@194 16 json.object{
jbe@194 17 key1 = value1, -- key value pair to be set in JSON object
jbe@194 18 key2 = value2, -- another key value pair to be set in JSON object
jbe@194 19 ...
jbe@194 20 }
jbe@194 21
jbe@199 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.
jbe@194 23
jbe@194 24 --]]--
jbe@194 25 -- implemented as in json.c as
jbe@194 26 -- static int json_object(lua_State *L)
jbe@194 27 --//--
jbe@194 28
jbe@194 29
jbe@194 30 --[[--
jbe@194 31 ary = -- a new JSON array
jbe@194 32 json.array{
jbe@194 33 value1, -- first value to be set in JSON array
jbe@194 34 value2, -- second value to be set in JSON array
jbe@194 35 ...
jbe@194 36 }
jbe@194 37
jbe@284 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).
jbe@194 39
jbe@194 40 --]]--
jbe@194 41 -- implemented in json.c as
jbe@194 42 -- static int json_object(lua_State *L)
jbe@194 43 --//--
jbe@194 44
jbe@194 45
jbe@194 46 --[[--
jbe@199 47 value, -- parsed value/document, or nil in case of error
jbe@199 48 errmsg = -- error message if document could not be parsed
jbe@194 49 json.import(
jbe@199 50 str -- string to be parsed
jbe@194 51 )
jbe@194 52
jbe@199 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).
jbe@194 54
jbe@194 55 --]]--
jbe@194 56 -- implemented in json.c as
jbe@194 57 -- static int json_import(lua_State *L)
jbe@194 58 --//--
jbe@194 59
jbe@194 60
jbe@194 61 --[[--
jbe@194 62 value = -- value that has been read, or nil if path does not exist
jbe@194 63 json.get(
jbe@199 64 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
jbe@194 65 key1, -- first path element (e.g. a string key to descent into an object)
jbe@194 66 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 67 ...,
jbe@194 68 last_key -- last path element
jbe@194 69 )
jbe@194 70
jbe@199 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.
jbe@194 72
jbe@194 73 Examples:
jbe@199 74 json.get(json.import('{"a": {"b": 3}}'), "a", "b") == 3
jbe@199 75 json.get(json.import('{"a": {"b": 3}}'), "c", "d") == nil
jbe@199 76 json.get(json.import('{"n": null}'), "n") == nil
jbe@199 77 json.get({a = {b = 3}}, "a", "b") == 3
jbe@194 78
jbe@194 79 --]]--
jbe@194 80 -- implemented in json.c as
jbe@194 81 -- static int json_get(lua_State *L)
jbe@194 82 --//--
jbe@194 83
jbe@194 84
jbe@194 85 --[[--
jbe@199 86 type_str = -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
jbe@195 87 json.type(
jbe@199 88 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
jbe@199 89 key1, -- first path element (e.g. a string key to descent into an object)
jbe@199 90 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 91 ...,
jbe@199 92 last_key -- last path element
jbe@194 93 )
jbe@194 94
jbe@199 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.
jbe@194 96
jbe@194 97 Examples:
jbe@199 98 json.type(json.import('{"a": {"b": 3}}'), "a", "b") == 3
jbe@199 99 json.type(json.import('{"a": {"b": null}}'), "a", "b") == "null"
jbe@199 100 json.type(json.import('{"a": {"b": null}}'), "a", "c") == "nil"
jbe@199 101 json.type(json.import('{"a": {"b": null}}'), "d", "c") == nil
jbe@194 102
jbe@194 103 --]]--
jbe@194 104 -- implemented in json.c as
jbe@194 105 -- static int json_type(lua_State *L)
jbe@194 106 --//--
jbe@194 107
jbe@194 108
jbe@194 109 --[[--
jbe@199 110 document = -- first argument is returned for convenience
jbe@194 111 json.set(
jbe@199 112 document, -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
jbe@199 113 value, -- new value to be set within the document
jbe@194 114 key1, -- first path element (e.g. a string key to descent into an object)
jbe@194 115 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 116 ...
jbe@194 117 last_key -- last path element
jbe@194 118 )
jbe@194 119
jbe@194 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.
jbe@194 121
jbe@194 122 --]]--
jbe@194 123 -- implemented in json.c as
jbe@194 124 -- static int json_set(lua_State *L)
jbe@194 125 --//--
jbe@194 126
jbe@194 127
jbe@194 128 --[[--
jbe@199 129 str = -- encoded JSON document as string
jbe@194 130 json.export(
jbe@199 131 document, -- JSON value (object, array, string, number, boolean, null), or a Lua table
jbe@199 132 indentation -- optional indentation string for pretty printing, or true for two spaces
jbe@194 133 )
jbe@194 134
jbe@199 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.
jbe@194 136
jbe@194 137 --]]--
jbe@194 138 -- implemented in json.c as
jbe@194 139 -- static int json_export(lua_State *L)
jbe@194 140 --//--
jbe@194 141

Impressum / About Us