webmcp

changeset 194:654ddbcc49d0

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 0014a7c22013
children 31f775ea5e24
files Makefile framework/bin/autodoc.lua libraries/json/json.autodoc.lua libraries/json/json.c
line diff
     1.1 --- a/Makefile	Mon Aug 11 13:18:49 2014 +0200
     1.2 +++ b/Makefile	Mon Aug 11 17:38:12 2014 +0200
     1.3 @@ -18,12 +18,14 @@
     1.4  
     1.5  libraries::
     1.6  	cd libraries/extos; make
     1.7 +	cd libraries/json; make
     1.8  	cd libraries/mondelefant; make
     1.9  	cd libraries/multirand; make
    1.10  
    1.11  symlinks::
    1.12  	ln -s -f ../../libraries/atom/atom.lua framework/lib/
    1.13  	ln -s -f ../../libraries/extos/extos.so framework/lib/
    1.14 +	ln -s -f ../../libraries/json/json.so framework/lib/
    1.15  	ln -s -f ../../libraries/mondelefant/mondelefant.lua framework/lib/
    1.16  	ln -s -f ../../libraries/mondelefant/mondelefant_native.so framework/lib/
    1.17  	ln -s -f ../../libraries/mondelefant/mondelefant_atom_connector.lua framework/lib/
     2.1 --- a/framework/bin/autodoc.lua	Mon Aug 11 13:18:49 2014 +0200
     2.2 +++ b/framework/bin/autodoc.lua	Mon Aug 11 17:38:12 2014 +0200
     2.3 @@ -75,9 +75,9 @@
     2.4          end
     2.5          func_call = string.gsub(
     2.6            func_call,
     2.7 -          "^([^({]*)[({].*[,;].*[,;].*[,;].*[)}]$",
     2.8 -          function(base)
     2.9 -            return base .. "{ ... }"
    2.10 +          "^([^({]*)([({]).*[,;].*[,;].*[,;].*([)}])$",
    2.11 +          function(base, open, close)
    2.12 +            return base .. open .. " ... " .. close
    2.13            end
    2.14          )
    2.15          if entries[func_call] then
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/libraries/json/json.autodoc.lua	Mon Aug 11 17:38:12 2014 +0200
     3.3 @@ -0,0 +1,139 @@
     3.4 +
     3.5 +--[[--
     3.6 +json.null
     3.7 +
     3.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.
     3.9 +
    3.10 +--]]--
    3.11 +-- implemented as lightuserdata in json.c
    3.12 +-- pointing to field "nullmark" of json_lightuserdata struct
    3.13 +--//--
    3.14 +
    3.15 +
    3.16 +--[[--
    3.17 +obj =             -- a new JSON object
    3.18 +json.object{
    3.19 +  key1 = value1,  -- key value pair to be set in JSON object
    3.20 +  key2 = value2,  -- another key value pair to be set in JSON object
    3.21 +  ...
    3.22 +}
    3.23 +
    3.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(...).
    3.25 +
    3.26 +--]]--
    3.27 +-- implemented as in json.c as
    3.28 +-- static int json_object(lua_State *L)
    3.29 +--//--
    3.30 +
    3.31 +
    3.32 +--[[--
    3.33 +ary =        -- a new JSON array
    3.34 +json.array{
    3.35 +  value1,    -- first value to be set in JSON array
    3.36 +  value2,    -- second value to be set in JSON array
    3.37 +  ...
    3.38 +}
    3.39 +
    3.40 +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(...).
    3.41 +
    3.42 +--]]--
    3.43 +-- implemented in json.c as
    3.44 +-- static int json_object(lua_State *L)
    3.45 +--//--
    3.46 +
    3.47 +
    3.48 +--[[--
    3.49 +parsed_document,           -- parsed value, json.null for null values, or nil in case of error
    3.50 +errmsg =                   -- error message if document could not be parsed
    3.51 +json.import(
    3.52 +  json_document_as_string  -- string to be parsed
    3.53 +)
    3.54 +
    3.55 +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)
    3.56 +
    3.57 +--]]--
    3.58 +-- implemented in json.c as
    3.59 +-- static int json_import(lua_State *L)
    3.60 +--//--
    3.61 +
    3.62 +
    3.63 +--[[--
    3.64 +value =      -- value that has been read, or nil if path does not exist
    3.65 +json.get(
    3.66 +  document,  -- JSON value (usually object or array)
    3.67 +  key1,      -- first path element (e.g. a string key to descent into an object)
    3.68 +  key2,      -- second path element (e.g. an integer key to descent into an array)
    3.69 +  ...,
    3.70 +  last_key   -- last path element
    3.71 +)
    3.72 +
    3.73 +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.
    3.74 +
    3.75 +Examples:
    3.76 +json.get(json.import('{"a":{"b":3}}'), "a", "b") == 3
    3.77 +json.get(json.import('{"a":{"b":3}}'), "c", "d") == nil
    3.78 +json.get(json.import('{"n":null}'), "n") == nil
    3.79 +
    3.80 +--]]--
    3.81 +-- implemented in json.c as
    3.82 +-- static int json_get(lua_State *L)
    3.83 +--//--
    3.84 +
    3.85 +
    3.86 +--[[--
    3.87 +type_string_or_nil  -- "object", "array", "string", "number", "boolean", "null", string "nil", or nil
    3.88 +json.get(
    3.89 +  document,         -- a JSON value (usually object or array)
    3.90 +  key1,             -- first path element (e.g. a string key to descent into an object)
    3.91 +  key2,             -- second path element (e.g. an integer key to descent into an array)
    3.92 +  ...,
    3.93 +  last_key          -- last path element
    3.94 +)
    3.95 +
    3.96 +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.
    3.97 +
    3.98 +Examples:
    3.99 +json.type(json.import('{"a":{"b":3}}'), "a", "b") == 3
   3.100 +json.type(json.import('{"a":{"b":null}}'), "a", "b") == "null"
   3.101 +json.type(json.import('{"a":{"b":null}}'), "a", "c") == "nil"
   3.102 +json.type(json.import('{"a":{"b":null}}'), "d", "c") == nil
   3.103 +
   3.104 +--]]--
   3.105 +-- implemented in json.c as
   3.106 +-- static int json_type(lua_State *L)
   3.107 +--//--
   3.108 +
   3.109 +
   3.110 +--[[--
   3.111 +document =
   3.112 +json.set(
   3.113 +  document,
   3.114 +  value,
   3.115 +  key1,      -- first path element (e.g. a string key to descent into an object)
   3.116 +  key2,      -- second path element (e.g. an integer key to descent into an array)
   3.117 +  ...
   3.118 +  last_key   -- last path element
   3.119 +)
   3.120 +
   3.121 +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.
   3.122 +
   3.123 +--]]--
   3.124 +-- implemented in json.c as
   3.125 +-- static int json_set(lua_State *L)
   3.126 +--//--
   3.127 +
   3.128 +
   3.129 +--[[--
   3.130 +encoded_document =  -- encoded JSON document as string
   3.131 +json.export(
   3.132 +  document,         -- a JSON value (usually object or array)
   3.133 +  indentation       -- indentation string to use for pretty printing, or true for two spaces
   3.134 +)
   3.135 +
   3.136 +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.
   3.137 +
   3.138 +--]]--
   3.139 +-- implemented in json.c as
   3.140 +-- static int json_export(lua_State *L)
   3.141 +--//--
   3.142 +
     4.1 --- a/libraries/json/json.c	Mon Aug 11 13:18:49 2014 +0200
     4.2 +++ b/libraries/json/json.c	Mon Aug 11 17:38:12 2014 +0200
     4.3 @@ -551,16 +551,8 @@
     4.4    } else if (!strncmp(str+pos, "null", 4)) {
     4.5      // consume 4 input characters for "null":
     4.6      pos += 4;
     4.7 -    // different behavor for top-level and sub-levels:
     4.8 -    if (level) {
     4.9 -      // if sub-level,
    4.10 -      // push special null-marker onto stack:
    4.11 -      json_pushnullmark(L);
    4.12 -    } else {
    4.13 -      // if top-level,
    4.14 -      // push nil onto stack:
    4.15 -      lua_pushnil(L);
    4.16 -    }
    4.17 +    // push special null-marker onto stack:
    4.18 +    json_pushnullmark(L);
    4.19    } else {
    4.20      // all other cases are a syntax error:
    4.21      goto json_import_syntax_error;

Impressum / About Us