webmcp

annotate libraries/json/json.autodoc.lua @ 194:654ddbcc49d0

find changesets by author, revision, files, or words in the commit message
Bugfix in autodoc.lua; Added documentation for JSON library; json.import(...) returns json.null for "null" on top-level
author jbe
date Mon Aug 11 17:38:12 2014 +0200 (2014-08-11)
parents
children 31f775ea5e24
rev   line source
jbe@194 1
jbe@194 2 --[[--
jbe@194 3 json.null
jbe@194 4
jbe@194 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@194 8 -- implemented as lightuserdata in json.c
jbe@194 9 -- pointing to field "nullmark" of json_lightuserdata struct
jbe@194 10 --//--
jbe@194 11
jbe@194 12
jbe@194 13 --[[--
jbe@194 14 obj = -- a new JSON object
jbe@194 15 json.object{
jbe@194 16 key1 = value1, -- key value pair to be set in JSON object
jbe@194 17 key2 = value2, -- another key value pair to be set in JSON object
jbe@194 18 ...
jbe@194 19 }
jbe@194 20
jbe@194 21 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(...).
jbe@194 22
jbe@194 23 --]]--
jbe@194 24 -- implemented as in json.c as
jbe@194 25 -- static int json_object(lua_State *L)
jbe@194 26 --//--
jbe@194 27
jbe@194 28
jbe@194 29 --[[--
jbe@194 30 ary = -- a new JSON array
jbe@194 31 json.array{
jbe@194 32 value1, -- first value to be set in JSON array
jbe@194 33 value2, -- second value to be set in JSON array
jbe@194 34 ...
jbe@194 35 }
jbe@194 36
jbe@194 37 Converts a Lua table (or any other value with an __ipairs metamethod) 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(...).
jbe@194 38
jbe@194 39 --]]--
jbe@194 40 -- implemented in json.c as
jbe@194 41 -- static int json_object(lua_State *L)
jbe@194 42 --//--
jbe@194 43
jbe@194 44
jbe@194 45 --[[--
jbe@194 46 parsed_document, -- parsed value, json.null for null values, or nil in case of error
jbe@194 47 errmsg = -- error message if document could not be parsed
jbe@194 48 json.import(
jbe@194 49 json_document_as_string -- string to be parsed
jbe@194 50 )
jbe@194 51
jbe@194 52 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 53
jbe@194 54 --]]--
jbe@194 55 -- implemented in json.c as
jbe@194 56 -- static int json_import(lua_State *L)
jbe@194 57 --//--
jbe@194 58
jbe@194 59
jbe@194 60 --[[--
jbe@194 61 value = -- value that has been read, or nil if path does not exist
jbe@194 62 json.get(
jbe@194 63 document, -- JSON value (usually object or array)
jbe@194 64 key1, -- first path element (e.g. a string key to descent into an object)
jbe@194 65 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 66 ...,
jbe@194 67 last_key -- last path element
jbe@194 68 )
jbe@194 69
jbe@194 70 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 documents.
jbe@194 71
jbe@194 72 Examples:
jbe@194 73 json.get(json.import('{"a":{"b":3}}'), "a", "b") == 3
jbe@194 74 json.get(json.import('{"a":{"b":3}}'), "c", "d") == nil
jbe@194 75 json.get(json.import('{"n":null}'), "n") == nil
jbe@194 76
jbe@194 77 --]]--
jbe@194 78 -- implemented in json.c as
jbe@194 79 -- static int json_get(lua_State *L)
jbe@194 80 --//--
jbe@194 81
jbe@194 82
jbe@194 83 --[[--
jbe@194 84 type_string_or_nil -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
jbe@194 85 json.get(
jbe@194 86 document, -- a JSON value (usually object or array)
jbe@194 87 key1, -- first path element (e.g. a string key to descent into an object)
jbe@194 88 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 89 ...,
jbe@194 90 last_key -- last path element
jbe@194 91 )
jbe@194 92
jbe@194 93 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 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 94
jbe@194 95 Examples:
jbe@194 96 json.type(json.import('{"a":{"b":3}}'), "a", "b") == 3
jbe@194 97 json.type(json.import('{"a":{"b":null}}'), "a", "b") == "null"
jbe@194 98 json.type(json.import('{"a":{"b":null}}'), "a", "c") == "nil"
jbe@194 99 json.type(json.import('{"a":{"b":null}}'), "d", "c") == nil
jbe@194 100
jbe@194 101 --]]--
jbe@194 102 -- implemented in json.c as
jbe@194 103 -- static int json_type(lua_State *L)
jbe@194 104 --//--
jbe@194 105
jbe@194 106
jbe@194 107 --[[--
jbe@194 108 document =
jbe@194 109 json.set(
jbe@194 110 document,
jbe@194 111 value,
jbe@194 112 key1, -- first path element (e.g. a string key to descent into an object)
jbe@194 113 key2, -- second path element (e.g. an integer key to descent into an array)
jbe@194 114 ...
jbe@194 115 last_key -- last path element
jbe@194 116 )
jbe@194 117
jbe@194 118 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 119
jbe@194 120 --]]--
jbe@194 121 -- implemented in json.c as
jbe@194 122 -- static int json_set(lua_State *L)
jbe@194 123 --//--
jbe@194 124
jbe@194 125
jbe@194 126 --[[--
jbe@194 127 encoded_document = -- encoded JSON document as string
jbe@194 128 json.export(
jbe@194 129 document, -- a JSON value (usually object or array)
jbe@194 130 indentation -- indentation string to use for pretty printing, or true for two spaces
jbe@194 131 )
jbe@194 132
jbe@194 133 Encodes a JSON document. Since the order of object keys is deterministic, this function may also be used to compare two JSON documents for (deep) equality: json.export(a) == json.export(b). If the indentation argument is nil or false, then pretty printing is disabled.
jbe@194 134
jbe@194 135 --]]--
jbe@194 136 -- implemented in json.c as
jbe@194 137 -- static int json_export(lua_State *L)
jbe@194 138 --//--
jbe@194 139

Impressum / About Us