1.1 --- a/libraries/json/json.autodoc.lua	Mon Aug 11 22:57:23 2014 +0200
     1.2 +++ b/libraries/json/json.autodoc.lua	Tue Aug 12 01:01:54 2014 +0200
     1.3 @@ -2,11 +2,12 @@
     1.4  --[[--
     1.5  json.null
     1.6  
     1.7 -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.
     1.8 +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.
     1.9  
    1.10  --]]--
    1.11 --- implemented as lightuserdata in json.c
    1.12 --- pointing to field "nullmark" of json_lightuserdata struct
    1.13 +-- implemented as lightuserdata pointing to
    1.14 +-- field "nullmark" of json_lightuserdata struct
    1.15 +-- in json.c
    1.16  --//--
    1.17  
    1.18  
    1.19 @@ -18,7 +19,7 @@
    1.20    ...
    1.21  }
    1.22  
    1.23 -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(...).
    1.24 +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.
    1.25  
    1.26  --]]--
    1.27  -- implemented as in json.c as
    1.28 @@ -34,7 +35,7 @@
    1.29    ...
    1.30  }
    1.31  
    1.32 -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(...).
    1.33 +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(...). 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).
    1.34  
    1.35  --]]--
    1.36  -- implemented in json.c as
    1.37 @@ -43,13 +44,13 @@
    1.38  
    1.39  
    1.40  --[[--
    1.41 -parsed_document,           -- parsed value, json.null for null values, or nil in case of error
    1.42 -errmsg =                   -- error message if document could not be parsed
    1.43 +value,        -- parsed value/document, or nil in case of error
    1.44 +errmsg =      -- error message if document could not be parsed
    1.45  json.import(
    1.46 -  json_document_as_string  -- string to be parsed
    1.47 +  str         -- string to be parsed
    1.48  )
    1.49  
    1.50 -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)
    1.51 +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).
    1.52  
    1.53  --]]--
    1.54  -- implemented in json.c as
    1.55 @@ -60,19 +61,20 @@
    1.56  --[[--
    1.57  value =      -- value that has been read, or nil if path does not exist
    1.58  json.get(
    1.59 -  document,  -- JSON value (usually object or array)
    1.60 +  document,  -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
    1.61    key1,      -- first path element (e.g. a string key to descent into an object)
    1.62    key2,      -- second path element (e.g. an integer key to descent into an array)
    1.63    ...,
    1.64    last_key   -- last path element
    1.65  )
    1.66  
    1.67 -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.
    1.68 +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.
    1.69  
    1.70  Examples:
    1.71 -json.get(json.import('{"a":{"b":3}}'), "a", "b") == 3
    1.72 -json.get(json.import('{"a":{"b":3}}'), "c", "d") == nil
    1.73 -json.get(json.import('{"n":null}'), "n") == nil
    1.74 +json.get(json.import('{"a": {"b": 3}}'), "a", "b") == 3
    1.75 +json.get(json.import('{"a": {"b": 3}}'), "c", "d") == nil
    1.76 +json.get(json.import('{"n": null}'), "n") == nil
    1.77 +json.get({a = {b = 3}}, "a", "b") == 3
    1.78  
    1.79  --]]--
    1.80  -- implemented in json.c as
    1.81 @@ -81,22 +83,22 @@
    1.82  
    1.83  
    1.84  --[[--
    1.85 -type_string_or_nil =  -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
    1.86 +type_str =   -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
    1.87  json.type(
    1.88 -  document,           -- a JSON value (usually object or array)
    1.89 -  key1,               -- first path element (e.g. a string key to descent into an object)
    1.90 -  key2,               -- second path element (e.g. an integer key to descent into an array)
    1.91 +  document,  -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
    1.92 +  key1,      -- first path element (e.g. a string key to descent into an object)
    1.93 +  key2,      -- second path element (e.g. an integer key to descent into an array)
    1.94    ...,
    1.95 -  last_key            -- last path element
    1.96 +  last_key   -- last path element
    1.97  )
    1.98  
    1.99 -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.
   1.100 +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.
   1.101  
   1.102  Examples:
   1.103 -json.type(json.import('{"a":{"b":3}}'), "a", "b") == 3
   1.104 -json.type(json.import('{"a":{"b":null}}'), "a", "b") == "null"
   1.105 -json.type(json.import('{"a":{"b":null}}'), "a", "c") == "nil"
   1.106 -json.type(json.import('{"a":{"b":null}}'), "d", "c") == nil
   1.107 +json.type(json.import('{"a": {"b": 3}}'), "a", "b") == 3
   1.108 +json.type(json.import('{"a": {"b": null}}'), "a", "b") == "null"
   1.109 +json.type(json.import('{"a": {"b": null}}'), "a", "c") == "nil"
   1.110 +json.type(json.import('{"a": {"b": null}}'), "d", "c") == nil
   1.111  
   1.112  --]]--
   1.113  -- implemented in json.c as
   1.114 @@ -105,10 +107,10 @@
   1.115  
   1.116  
   1.117  --[[--
   1.118 -document =
   1.119 +document =   -- first argument is returned for convenience
   1.120  json.set(
   1.121 -  document,
   1.122 -  value,
   1.123 +  document,  -- JSON value as returned by json.import(...), json.object{...}, etc., or a Lua table
   1.124 +  value,     -- new value to be set within the document
   1.125    key1,      -- first path element (e.g. a string key to descent into an object)
   1.126    key2,      -- second path element (e.g. an integer key to descent into an array)
   1.127    ...
   1.128 @@ -124,13 +126,13 @@
   1.129  
   1.130  
   1.131  --[[--
   1.132 -encoded_document =  -- encoded JSON document as string
   1.133 +str =          -- encoded JSON document as string
   1.134  json.export(
   1.135 -  document,         -- a JSON value (usually object or array)
   1.136 -  indentation       -- indentation string to use for pretty printing, or true for two spaces
   1.137 +  document,    -- JSON value (object, array, string, number, boolean, null), or a Lua table
   1.138 +  indentation  -- optional indentation string for pretty printing, or true for two spaces
   1.139  )
   1.140  
   1.141 -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.
   1.142 +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.
   1.143  
   1.144  --]]--
   1.145  -- implemented in json.c as

     2.1 --- a/libraries/json/json.c	Mon Aug 11 22:57:23 2014 +0200
     2.2 +++ b/libraries/json/json.c	Tue Aug 12 01:01:54 2014 +0200
     2.3 @@ -710,9 +710,10 @@
     2.4  static int json_set(lua_State *L) {
     2.5    int stacktop;  // stack index of top of stack (after shifting)
     2.6    int idx;       // stack index of current argument to process
     2.7 -  // require at least two arguments:
     2.8 +  // require at least three arguments:
     2.9    luaL_checkany(L, 1);
    2.10    luaL_checkany(L, 2);
    2.11 +  luaL_checkany(L, 3);
    2.12    // insert objectmt into stack at position 1 (shifting the arguments):
    2.13    json_regfetch(L, objectmt);
    2.14    lua_insert(L, 1);