update to version 2.5 #2
@ -1,7 +1,7 @@
|
||||
--- This file is part of LuaDist project
|
||||
|
||||
name = "dkjson"
|
||||
version = "2.4"
|
||||
version = "2.5"
|
||||
|
||||
desc = "dkjson is a module for encoding and decoding JSON data. It supports UTF-8."
|
||||
author = "David Kolf"
|
||||
|
||||
30
dkjson-2.5-2.rockspec
Normal file
30
dkjson-2.5-2.rockspec
Normal file
@ -0,0 +1,30 @@
|
||||
package = "dkjson"
|
||||
version = "2.5-2"
|
||||
source = {
|
||||
url = "http://dkolf.de/src/dkjson-lua.fsl/tarball/dkjson-2.5.tar.gz?uuid=release_2_5",
|
||||
file = "dkjson-2.5.tar.gz"
|
||||
}
|
||||
description = {
|
||||
summary = "David Kolf's JSON module for Lua",
|
||||
detailed = [[
|
||||
dkjson is a module for encoding and decoding JSON data. It supports UTF-8.
|
||||
|
||||
JSON (JavaScript Object Notation) is a format for serializing data based
|
||||
on the syntax for JavaScript data structures.
|
||||
|
||||
dkjson is written in Lua without any dependencies, but
|
||||
when LPeg is available dkjson uses it to speed up decoding.
|
||||
]],
|
||||
homepage = "http://dkolf.de/src/dkjson-lua.fsl/",
|
||||
license = "MIT/X11"
|
||||
}
|
||||
dependencies = {
|
||||
"lua >= 5.1, < 5.4"
|
||||
}
|
||||
build = {
|
||||
type = "builtin",
|
||||
modules = {
|
||||
dkjson = "dkjson.lua"
|
||||
}
|
||||
}
|
||||
|
||||
265
dkjson.lua
265
dkjson.lua
@ -1,178 +1,23 @@
|
||||
-- Module options:
|
||||
local always_try_using_lpeg = true
|
||||
local register_global_module_table = false
|
||||
local global_module_name = 'json'
|
||||
-- Module options:
|
||||
local always_try_using_lpeg = true
|
||||
local register_global_module_table = false
|
||||
local global_module_name = 'json'
|
||||
|
||||
--[==[
|
||||
--[==[
|
||||
|
||||
David Kolf's JSON module for Lua 5.1/5.2
|
||||
========================================
|
||||
|
||||
*Version 2.4*
|
||||
Version 2.5
|
||||
|
||||
In the default configuration this module writes no global values, not even
|
||||
the module table. Import it using
|
||||
|
||||
json = require ("dkjson")
|
||||
|
||||
In environments where `require` or a similiar function are not available
|
||||
and you cannot receive the return value of the module, you can set the
|
||||
option `register_global_module_table` to `true`. The module table will
|
||||
then be saved in the global variable with the name given by the option
|
||||
`global_module_name`.
|
||||
|
||||
Exported functions and values:
|
||||
|
||||
`json.encode (object [, state])`
|
||||
--------------------------------
|
||||
|
||||
Create a string representing the object. `Object` can be a table,
|
||||
a string, a number, a boolean, `nil`, `json.null` or any object with
|
||||
a function `__tojson` in its metatable. A table can only use strings
|
||||
and numbers as keys and its values have to be valid objects as
|
||||
well. It raises an error for any invalid data types or reference
|
||||
cycles.
|
||||
|
||||
`state` is an optional table with the following fields:
|
||||
|
||||
- `indent`
|
||||
When `indent` (a boolean) is set, the created string will contain
|
||||
newlines and indentations. Otherwise it will be one long line.
|
||||
- `keyorder`
|
||||
`keyorder` is an array to specify the ordering of keys in the
|
||||
encoded output. If an object has keys which are not in this array
|
||||
they are written after the sorted keys.
|
||||
- `level`
|
||||
This is the initial level of indentation used when `indent` is
|
||||
set. For each level two spaces are added. When absent it is set
|
||||
to 0.
|
||||
- `buffer`
|
||||
`buffer` is an array to store the strings for the result so they
|
||||
can be concatenated at once. When it isn't given, the encode
|
||||
function will create it temporary and will return the
|
||||
concatenated result.
|
||||
- `bufferlen`
|
||||
When `bufferlen` is set, it has to be the index of the last
|
||||
element of `buffer`.
|
||||
- `tables`
|
||||
`tables` is a set to detect reference cycles. It is created
|
||||
temporary when absent. Every table that is currently processed
|
||||
is used as key, the value is `true`.
|
||||
|
||||
When `state.buffer` was set, the return value will be `true` on
|
||||
success. Without `state.buffer` the return value will be a string.
|
||||
|
||||
`json.decode (string [, position [, null]])`
|
||||
--------------------------------------------
|
||||
|
||||
Decode `string` starting at `position` or at 1 if `position` was
|
||||
omitted.
|
||||
|
||||
`null` is an optional value to be returned for null values. The
|
||||
default is `nil`, but you could set it to `json.null` or any other
|
||||
value.
|
||||
|
||||
The return values are the object or `nil`, the position of the next
|
||||
character that doesn't belong to the object, and in case of errors
|
||||
an error message.
|
||||
|
||||
Two metatables are created. Every array or object that is decoded gets
|
||||
a metatable with the `__jsontype` field set to either `array` or
|
||||
`object`. If you want to provide your own metatables use the syntax
|
||||
|
||||
json.decode (string, position, null, objectmeta, arraymeta)
|
||||
|
||||
To prevent the assigning of metatables pass `nil`:
|
||||
|
||||
json.decode (string, position, null, nil)
|
||||
|
||||
`<metatable>.__jsonorder`
|
||||
-------------------------
|
||||
|
||||
`__jsonorder` can overwrite the `keyorder` for a specific table.
|
||||
|
||||
`<metatable>.__jsontype`
|
||||
------------------------
|
||||
|
||||
`__jsontype` can be either `"array"` or `"object"`. This value is only
|
||||
checked for empty tables. (The default for empty tables is `"array"`).
|
||||
|
||||
`<metatable>.__tojson (self, state)`
|
||||
------------------------------------
|
||||
|
||||
You can provide your own `__tojson` function in a metatable. In this
|
||||
function you can either add directly to the buffer and return true,
|
||||
or you can return a string. On errors nil and a message should be
|
||||
returned.
|
||||
|
||||
`json.null`
|
||||
-----------
|
||||
|
||||
You can use this value for setting explicit `null` values.
|
||||
|
||||
`json.version`
|
||||
--------------
|
||||
|
||||
Set to `"dkjson 2.4"`.
|
||||
|
||||
`json.quotestring (string)`
|
||||
---------------------------
|
||||
|
||||
Quote a UTF-8 string and escape critical characters using JSON
|
||||
escape sequences. This function is only necessary when you build
|
||||
your own `__tojson` functions.
|
||||
|
||||
`json.addnewline (state)`
|
||||
-------------------------
|
||||
|
||||
When `state.indent` is set, add a newline to `state.buffer` and spaces
|
||||
according to `state.level`.
|
||||
|
||||
LPeg support
|
||||
------------
|
||||
|
||||
When the local configuration variable `always_try_using_lpeg` is set,
|
||||
this module tries to load LPeg to replace the `decode` function. The
|
||||
speed increase is significant. You can get the LPeg module at
|
||||
<http://www.inf.puc-rio.br/~roberto/lpeg/>.
|
||||
When LPeg couldn't be loaded, the pure Lua functions stay active.
|
||||
|
||||
In case you don't want this module to require LPeg on its own,
|
||||
disable the option `always_try_using_lpeg` in the options section at
|
||||
the top of the module.
|
||||
|
||||
In this case you can later load LPeg support using
|
||||
|
||||
### `json.use_lpeg ()`
|
||||
|
||||
Require the LPeg module and replace the functions `quotestring` and
|
||||
and `decode` with functions that use LPeg patterns.
|
||||
This function returns the module table, so you can load the module
|
||||
using:
|
||||
|
||||
json = require "dkjson".use_lpeg()
|
||||
|
||||
Alternatively you can use `pcall` so the JSON module still works when
|
||||
LPeg isn't found.
|
||||
|
||||
json = require "dkjson"
|
||||
pcall (json.use_lpeg)
|
||||
|
||||
### `json.using_lpeg`
|
||||
|
||||
This variable is set to `true` when LPeg was loaded successfully.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
Contact
|
||||
-------
|
||||
For the documentation see the corresponding readme.txt or visit
|
||||
<http://dkolf.de/src/dkjson-lua.fsl/>.
|
||||
|
||||
You can contact the author by sending an e-mail to 'david' at the
|
||||
domain 'dkolf.de'.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
*Copyright (C) 2010-2013 David Heiko Kolf*
|
||||
Copyright (C) 2010-2014 David Heiko Kolf
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
@ -194,13 +39,7 @@ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
<!-- This documentation can be parsed using Markdown to generate HTML.
|
||||
The source code is enclosed in a HTML comment so it won't be displayed
|
||||
by browsers, but it should be removed from the final HTML file as
|
||||
it isn't a valid HTML comment (and wastes space).
|
||||
-->
|
||||
|
||||
<!--]==]
|
||||
--]==]
|
||||
|
||||
-- global dependencies:
|
||||
local pairs, type, tostring, tonumber, getmetatable, setmetatable, rawset =
|
||||
@ -213,7 +52,7 @@ local strrep, gsub, strsub, strbyte, strchar, strfind, strlen, strformat =
|
||||
local strmatch = string.match
|
||||
local concat = table.concat
|
||||
|
||||
local json = { version = "dkjson 2.4" }
|
||||
local json = { version = "dkjson 2.5" }
|
||||
|
||||
if register_global_module_table then
|
||||
_G[global_module_name] = json
|
||||
@ -368,7 +207,7 @@ end
|
||||
|
||||
local encode2 -- forward declaration
|
||||
|
||||
local function addpair (key, value, prev, indent, level, buffer, buflen, tables, globalorder)
|
||||
local function addpair (key, value, prev, indent, level, buffer, buflen, tables, globalorder, state)
|
||||
local kt = type (key)
|
||||
if kt ~= 'string' and kt ~= 'number' then
|
||||
return nil, "type '" .. kt .. "' is not supported as a key by JSON."
|
||||
@ -382,31 +221,50 @@ local function addpair (key, value, prev, indent, level, buffer, buflen, tables,
|
||||
end
|
||||
buffer[buflen+1] = quotestring (key)
|
||||
buffer[buflen+2] = ":"
|
||||
return encode2 (value, indent, level, buffer, buflen + 2, tables, globalorder)
|
||||
return encode2 (value, indent, level, buffer, buflen + 2, tables, globalorder, state)
|
||||
end
|
||||
|
||||
encode2 = function (value, indent, level, buffer, buflen, tables, globalorder)
|
||||
local function appendcustom(res, buffer, state)
|
||||
local buflen = state.bufferlen
|
||||
if type (res) == 'string' then
|
||||
buflen = buflen + 1
|
||||
buffer[buflen] = res
|
||||
end
|
||||
return buflen
|
||||
end
|
||||
|
||||
local function exception(reason, value, state, buffer, buflen, defaultmessage)
|
||||
defaultmessage = defaultmessage or reason
|
||||
local handler = state.exception
|
||||
if not handler then
|
||||
return nil, defaultmessage
|
||||
else
|
||||
state.bufferlen = buflen
|
||||
local ret, msg = handler (reason, value, state, defaultmessage)
|
||||
if not ret then return nil, msg or defaultmessage end
|
||||
return appendcustom(ret, buffer, state)
|
||||
end
|
||||
end
|
||||
|
||||
function json.encodeexception(reason, value, state, defaultmessage)
|
||||
return quotestring("<" .. defaultmessage .. ">")
|
||||
end
|
||||
|
||||
encode2 = function (value, indent, level, buffer, buflen, tables, globalorder, state)
|
||||
local valtype = type (value)
|
||||
local valmeta = getmetatable (value)
|
||||
valmeta = type (valmeta) == 'table' and valmeta -- only tables
|
||||
local valtojson = valmeta and valmeta.__tojson
|
||||
if valtojson then
|
||||
if tables[value] then
|
||||
return nil, "reference cycle"
|
||||
return exception('reference cycle', value, state, buffer, buflen)
|
||||
end
|
||||
tables[value] = true
|
||||
local state = {
|
||||
indent = indent, level = level, buffer = buffer,
|
||||
bufferlen = buflen, tables = tables, keyorder = globalorder
|
||||
}
|
||||
state.bufferlen = buflen
|
||||
local ret, msg = valtojson (value, state)
|
||||
if not ret then return nil, msg end
|
||||
if not ret then return exception('custom encoder failed', value, state, buffer, buflen, msg) end
|
||||
tables[value] = nil
|
||||
buflen = state.bufferlen
|
||||
if type (ret) == 'string' then
|
||||
buflen = buflen + 1
|
||||
buffer[buflen] = ret
|
||||
end
|
||||
buflen = appendcustom(ret, buffer, state)
|
||||
elseif value == nil then
|
||||
buflen = buflen + 1
|
||||
buffer[buflen] = "null"
|
||||
@ -428,7 +286,7 @@ encode2 = function (value, indent, level, buffer, buflen, tables, globalorder)
|
||||
buffer[buflen] = quotestring (value)
|
||||
elseif valtype == 'table' then
|
||||
if tables[value] then
|
||||
return nil, "reference cycle"
|
||||
return exception('reference cycle', value, state, buffer, buflen)
|
||||
end
|
||||
tables[value] = true
|
||||
level = level + 1
|
||||
@ -441,7 +299,7 @@ encode2 = function (value, indent, level, buffer, buflen, tables, globalorder)
|
||||
buflen = buflen + 1
|
||||
buffer[buflen] = "["
|
||||
for i = 1, n do
|
||||
buflen, msg = encode2 (value[i], indent, level, buffer, buflen, tables, globalorder)
|
||||
buflen, msg = encode2 (value[i], indent, level, buffer, buflen, tables, globalorder, state)
|
||||
if not buflen then return nil, msg end
|
||||
if i < n then
|
||||
buflen = buflen + 1
|
||||
@ -463,20 +321,20 @@ encode2 = function (value, indent, level, buffer, buflen, tables, globalorder)
|
||||
local v = value[k]
|
||||
if v then
|
||||
used[k] = true
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder)
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder, state)
|
||||
prev = true -- add a seperator before the next element
|
||||
end
|
||||
end
|
||||
for k,v in pairs (value) do
|
||||
if not used[k] then
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder)
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder, state)
|
||||
if not buflen then return nil, msg end
|
||||
prev = true -- add a seperator before the next element
|
||||
end
|
||||
end
|
||||
else -- unordered
|
||||
for k,v in pairs (value) do
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder)
|
||||
buflen, msg = addpair (k, v, prev, indent, level, buffer, buflen, tables, globalorder, state)
|
||||
if not buflen then return nil, msg end
|
||||
prev = true -- add a seperator before the next element
|
||||
end
|
||||
@ -489,7 +347,8 @@ encode2 = function (value, indent, level, buffer, buflen, tables, globalorder)
|
||||
end
|
||||
tables[value] = nil
|
||||
else
|
||||
return nil, "type '" .. valtype .. "' is not supported by JSON."
|
||||
return exception ('unsupported type', value, state, buffer, buflen,
|
||||
"type '" .. valtype .. "' is not supported by JSON.")
|
||||
end
|
||||
return buflen
|
||||
end
|
||||
@ -498,15 +357,18 @@ function json.encode (value, state)
|
||||
state = state or {}
|
||||
local oldbuffer = state.buffer
|
||||
local buffer = oldbuffer or {}
|
||||
state.buffer = buffer
|
||||
updatedecpoint()
|
||||
local ret, msg = encode2 (value, state.indent, state.level or 0,
|
||||
buffer, state.bufferlen or 0, state.tables or {}, state.keyorder)
|
||||
buffer, state.bufferlen or 0, state.tables or {}, state.keyorder, state)
|
||||
if not ret then
|
||||
error (msg, 2)
|
||||
elseif oldbuffer then
|
||||
elseif oldbuffer == buffer then
|
||||
state.bufferlen = ret
|
||||
return true
|
||||
else
|
||||
state.bufferlen = nil
|
||||
state.buffer = nil
|
||||
return concat (buffer)
|
||||
end
|
||||
end
|
||||
@ -534,9 +396,17 @@ local function scanwhite (str, pos)
|
||||
while true do
|
||||
pos = strfind (str, "%S", pos)
|
||||
if not pos then return nil end
|
||||
if strsub (str, pos, pos + 2) == "\239\187\191" then
|
||||
local sub2 = strsub (str, pos, pos + 1)
|
||||
if sub2 == "\239\187" and strsub (str, pos + 2, pos + 2) == "\191" then
|
||||
-- UTF-8 Byte Order Mark
|
||||
pos = pos + 3
|
||||
elseif sub2 == "//" then
|
||||
pos = strfind (str, "[\n\r]", pos + 2)
|
||||
if not pos then return nil end
|
||||
elseif sub2 == "/*" then
|
||||
pos = strfind (str, "*/", pos + 2)
|
||||
if not pos then return nil end
|
||||
pos = pos + 2
|
||||
else
|
||||
return pos
|
||||
end
|
||||
@ -749,7 +619,9 @@ function json.use_lpeg ()
|
||||
return g.Cmt (g.Cc (msg) * g.Carg (2), ErrorCall)
|
||||
end
|
||||
|
||||
local Space = (S" \n\r\t" + P"\239\187\191")^0
|
||||
local SingleLineComment = P"//" * (1 - S"\n\r")^0
|
||||
local MultiLineComment = P"/*" * (1 - P"*/")^0 * P"*/"
|
||||
local Space = (S" \n\r\t" + P"\239\187\191" + SingleLineComment + MultiLineComment)^0
|
||||
|
||||
local PlainChar = 1 - S"\"\\\n\r"
|
||||
local EscapeSequence = (P"\\" * g.C (S"\"\\/bfnrt" + Err "unsupported escape sequence")) / escapechars
|
||||
@ -840,4 +712,3 @@ end
|
||||
|
||||
return json
|
||||
|
||||
-->
|
||||
|
||||
141
jsontest.lua
141
jsontest.lua
@ -12,6 +12,7 @@ local test_module, opt = ... -- command line argument
|
||||
--local test_module = 'nm-json'
|
||||
--local test_module = 'sb-json'
|
||||
--local test_module = 'th-json'
|
||||
test_module = test_module or 'dkjson'
|
||||
|
||||
--local opt = "esc" -- Test which characters in the BMP get escaped and whether this is correct
|
||||
--local opt = "esc_full" -- Full range from 0 to 0x10ffff
|
||||
@ -209,6 +210,122 @@ else
|
||||
print("In locale 0.5 isn't converted into valid JSON:", x)
|
||||
end
|
||||
end)
|
||||
|
||||
-- special tests for dkjson:
|
||||
if test_module == 'dkjson' then
|
||||
do -- encode a function
|
||||
local why, value, exstate
|
||||
local state = {
|
||||
exception = function (w, v, s)
|
||||
why, value, exstate = w, v, s
|
||||
return "\"demo\""
|
||||
end
|
||||
}
|
||||
local encfunction = function () end
|
||||
r, x = pcall(dkencode, { encfunction }, state )
|
||||
if not r then
|
||||
print("encoding a function with exception handler raises an error:", x)
|
||||
else
|
||||
if x ~= "[\"demo\"]" then
|
||||
print("expected to see output of exception handler for type exception, but got", x)
|
||||
end
|
||||
if why ~= "unsupported type" then
|
||||
print("expected exception reason to be 'unsupported type' for type exception")
|
||||
end
|
||||
if value ~= encfunction then
|
||||
print("expected to recieve value for type exception")
|
||||
end
|
||||
if exstate ~= state then
|
||||
print("expected to recieve state for type exception")
|
||||
end
|
||||
end
|
||||
|
||||
r, x = pcall(dkencode, { function () end }, {
|
||||
exception = function (w, v, s)
|
||||
return nil, "demo"
|
||||
end
|
||||
})
|
||||
if r or x ~= "demo" then
|
||||
print("expected custom error for type exception, but got:", r, x)
|
||||
end
|
||||
|
||||
r, x = pcall(dkencode, { function () end }, {
|
||||
exception = function (w, v, s)
|
||||
return nil
|
||||
end
|
||||
})
|
||||
if r or x ~= "type 'function' is not supported by JSON." then
|
||||
print("expected default error for type exception, but got:", r, x)
|
||||
end
|
||||
end
|
||||
|
||||
do -- encode a reference cycle
|
||||
local why, value, exstate
|
||||
local state = {
|
||||
exception = function (w, v, s)
|
||||
why, value, exstate = w, v, s
|
||||
return "\"demo\""
|
||||
end
|
||||
}
|
||||
local a = {}
|
||||
a[1] = a
|
||||
r, x = pcall(dkencode, a, state )
|
||||
if not r then
|
||||
print("encoding a reference cycle with exception handler raises an error:", x)
|
||||
else
|
||||
if x ~= "[\"demo\"]" then
|
||||
print("expected to see output of exception handler for reference cycle exception, but got", x)
|
||||
end
|
||||
if why ~= "reference cycle" then
|
||||
print("expected exception reason to be 'reference cycle' for reference cycle exception")
|
||||
end
|
||||
if value ~= a then
|
||||
print("expected to recieve value for reference cycle exception")
|
||||
end
|
||||
if exstate ~= state then
|
||||
print("expected to recieve state for reference cycle exception")
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
do -- example exception handler
|
||||
r = dkencode(function () end, { exception = require "dkjson".encodeexception })
|
||||
if r ~= [["<type 'function' is not supported by JSON.>"]] then
|
||||
print("expected the exception encoder to encode default error message, but got", r)
|
||||
end
|
||||
end
|
||||
|
||||
do -- test state buffer for custom __tojson function
|
||||
local origstate = {}
|
||||
local usedstate, usedbuffer, usedbufferlen
|
||||
dkencode({ setmetatable({}, {
|
||||
__tojson = function(self, state)
|
||||
usedstate = state
|
||||
usedbuffer = state.buffer
|
||||
usedbufferlen = state.bufferlen
|
||||
return true
|
||||
end
|
||||
}) }, origstate)
|
||||
if usedstate ~= origstate then print("expected tojson-function to recieve the original state") end
|
||||
if type(usedbuffer) ~= 'table' or #usedbuffer < 1 then print("expected buffer in tojson-function to be an array") end
|
||||
if usedbufferlen ~= 1 then print("expected bufferlen in tojson-function to be 1, but got "..tostring(usedbufferlen)) end
|
||||
end
|
||||
|
||||
do -- do not keep buffer and bufferlen when they were not present initially
|
||||
local origstate = {}
|
||||
dkencode(setmetatable({}, {__tojson = function() return true end}), origstate)
|
||||
if origstate.buffer ~= nil then print("expected buffer to be reset to nil") end
|
||||
if origstate.bufferlen ~= nil then print("expected bufferlen to be reset to nil") end
|
||||
end
|
||||
|
||||
do -- keep buffer and update bufferlen when they were present initially
|
||||
local origbuffer = {}
|
||||
local origstate = { buffer = origbuffer }
|
||||
dkencode(true, origstate)
|
||||
if origstate.buffer ~= origbuffer then print("expected original buffer to remain") end
|
||||
if origstate.bufferlen ~= 1 then print("expected bufferlen to be updated") end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
if not decode then
|
||||
@ -318,6 +435,30 @@ else
|
||||
if p ~= 4 or type(m) ~= 'string' or not m:find("at line 2, column 2$") then
|
||||
print (("Invalid location: position=%d, message=%q"):format(p,m))
|
||||
end
|
||||
|
||||
do -- single line comments
|
||||
local x, p, m = dkdecode [[
|
||||
{"test://" // comment // --?
|
||||
: [ // continues
|
||||
0] //
|
||||
}
|
||||
]]
|
||||
if type(x) ~= 'table' or type(x["test://"]) ~= 'table' or x["test://"][1] ~= 0 then
|
||||
print("could not decode a string with single line comments: "..tostring(m))
|
||||
end
|
||||
end
|
||||
|
||||
do -- multi line comments
|
||||
local x, p, m = dkdecode [[
|
||||
{"test:/*"/**//*
|
||||
hi! this is a comment
|
||||
*/ : [/** / **/ 0]
|
||||
}
|
||||
]]
|
||||
if type(x) ~= 'table' or type(x["test:/*"]) ~= 'table' or x["test:/*"][1] ~= 0 then
|
||||
print("could not decode a string with multi line comments: "..tostring(m))
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
211
readme.txt
Normal file
211
readme.txt
Normal file
@ -0,0 +1,211 @@
|
||||
David Kolf's JSON module for Lua 5.1/5.2
|
||||
========================================
|
||||
|
||||
*Version 2.5*
|
||||
|
||||
In the default configuration this module writes no global values, not even
|
||||
the module table. Import it using
|
||||
|
||||
json = require ("dkjson")
|
||||
|
||||
In environments where `require` or a similiar function are not available
|
||||
and you cannot receive the return value of the module, you can set the
|
||||
option `register_global_module_table` to `true`. The module table will
|
||||
then be saved in the global variable with the name given by the option
|
||||
`global_module_name`.
|
||||
|
||||
Exported functions and values:
|
||||
|
||||
`json.encode (object [, state])`
|
||||
--------------------------------
|
||||
|
||||
Create a string representing the object. `Object` can be a table,
|
||||
a string, a number, a boolean, `nil`, `json.null` or any object with
|
||||
a function `__tojson` in its metatable. A table can only use strings
|
||||
and numbers as keys and its values have to be valid objects as
|
||||
well. It raises an error for any invalid data types or reference
|
||||
cycles.
|
||||
|
||||
`state` is an optional table with the following fields:
|
||||
|
||||
- `indent`
|
||||
When `indent` (a boolean) is set, the created string will contain
|
||||
newlines and indentations. Otherwise it will be one long line.
|
||||
- `keyorder`
|
||||
`keyorder` is an array to specify the ordering of keys in the
|
||||
encoded output. If an object has keys which are not in this array
|
||||
they are written after the sorted keys.
|
||||
- `level`
|
||||
This is the initial level of indentation used when `indent` is
|
||||
set. For each level two spaces are added. When absent it is set
|
||||
to 0.
|
||||
- `buffer`
|
||||
`buffer` is an array to store the strings for the result so they
|
||||
can be concatenated at once. When it isn't given, the encode
|
||||
function will create it temporary and will return the
|
||||
concatenated result.
|
||||
- `bufferlen`
|
||||
When `bufferlen` is set, it has to be the index of the last
|
||||
element of `buffer`.
|
||||
- `tables`
|
||||
`tables` is a set to detect reference cycles. It is created
|
||||
temporary when absent. Every table that is currently processed
|
||||
is used as key, the value is `true`.
|
||||
- `exception`
|
||||
When `exception` is given, it will be called whenever the encoder
|
||||
cannot encode a given value.
|
||||
The parameters are `reason`, `value`, `state` and `defaultmessage`.
|
||||
`reason` is either `"reference cycle"`, `"custom encoder failed"` or
|
||||
`"unsupported type"`. `value` is the original value that caused the
|
||||
exception, `state` is this state table, `defaultmessage` is the message
|
||||
of the error that would usually be raised.
|
||||
You can either return `true` and add directly to the buffer or you can
|
||||
return the string directly. To keep raising an error return `nil` and
|
||||
the desired error message.
|
||||
An example implementation for an exception function is given in
|
||||
`json.encodeexception`.
|
||||
|
||||
When `state.buffer` was set, the return value will be `true` on
|
||||
success. Without `state.buffer` the return value will be a string.
|
||||
|
||||
`json.decode (string [, position [, null]])`
|
||||
--------------------------------------------
|
||||
|
||||
Decode `string` starting at `position` or at 1 if `position` was
|
||||
omitted.
|
||||
|
||||
`null` is an optional value to be returned for null values. The
|
||||
default is `nil`, but you could set it to `json.null` or any other
|
||||
value.
|
||||
|
||||
The return values are the object or `nil`, the position of the next
|
||||
character that doesn't belong to the object, and in case of errors
|
||||
an error message.
|
||||
|
||||
Two metatables are created. Every array or object that is decoded gets
|
||||
a metatable with the `__jsontype` field set to either `array` or
|
||||
`object`. If you want to provide your own metatables use the syntax
|
||||
|
||||
json.decode (string, position, null, objectmeta, arraymeta)
|
||||
|
||||
To prevent the assigning of metatables pass `nil`:
|
||||
|
||||
json.decode (string, position, null, nil)
|
||||
|
||||
`<metatable>.__jsonorder`
|
||||
-------------------------
|
||||
|
||||
`__jsonorder` can overwrite the `keyorder` for a specific table.
|
||||
|
||||
`<metatable>.__jsontype`
|
||||
------------------------
|
||||
|
||||
`__jsontype` can be either `"array"` or `"object"`. This value is only
|
||||
checked for empty tables. (The default for empty tables is `"array"`).
|
||||
|
||||
`<metatable>.__tojson (self, state)`
|
||||
------------------------------------
|
||||
|
||||
You can provide your own `__tojson` function in a metatable. In this
|
||||
function you can either add directly to the buffer and return true,
|
||||
or you can return a string. On errors nil and a message should be
|
||||
returned.
|
||||
|
||||
`json.null`
|
||||
-----------
|
||||
|
||||
You can use this value for setting explicit `null` values.
|
||||
|
||||
`json.version`
|
||||
--------------
|
||||
|
||||
Set to `"dkjson 2.5"`.
|
||||
|
||||
`json.quotestring (string)`
|
||||
---------------------------
|
||||
|
||||
Quote a UTF-8 string and escape critical characters using JSON
|
||||
escape sequences. This function is only necessary when you build
|
||||
your own `__tojson` functions.
|
||||
|
||||
`json.addnewline (state)`
|
||||
-------------------------
|
||||
|
||||
When `state.indent` is set, add a newline to `state.buffer` and spaces
|
||||
according to `state.level`.
|
||||
|
||||
`json.encodeexception (reason, value, state, defaultmessage)`
|
||||
-------------------------------------------------------------
|
||||
|
||||
This function can be used as value to the `exception` option. Instead of
|
||||
raising an error this function encodes the error message as a string. This
|
||||
can help to debug malformed input data.
|
||||
|
||||
x = json.encode(value, { exception = json.encodeexception })
|
||||
|
||||
LPeg support
|
||||
------------
|
||||
|
||||
When the local configuration variable `always_try_using_lpeg` is set,
|
||||
this module tries to load LPeg to replace the `decode` function. The
|
||||
speed increase is significant. You can get the LPeg module at
|
||||
<http://www.inf.puc-rio.br/~roberto/lpeg/>.
|
||||
When LPeg couldn't be loaded, the pure Lua functions stay active.
|
||||
|
||||
In case you don't want this module to require LPeg on its own,
|
||||
disable the option `always_try_using_lpeg` in the options section at
|
||||
the top of the module.
|
||||
|
||||
In this case you can later load LPeg support using
|
||||
|
||||
### `json.use_lpeg ()`
|
||||
|
||||
Require the LPeg module and replace the functions `quotestring` and
|
||||
and `decode` with functions that use LPeg patterns.
|
||||
This function returns the module table, so you can load the module
|
||||
using:
|
||||
|
||||
json = require "dkjson".use_lpeg()
|
||||
|
||||
Alternatively you can use `pcall` so the JSON module still works when
|
||||
LPeg isn't found.
|
||||
|
||||
json = require "dkjson"
|
||||
pcall (json.use_lpeg)
|
||||
|
||||
### `json.using_lpeg`
|
||||
|
||||
This variable is set to `true` when LPeg was loaded successfully.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
Contact
|
||||
-------
|
||||
|
||||
You can contact the author by sending an e-mail to 'david' at the
|
||||
domain 'dkolf.de'.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
|
||||
*Copyright (C) 2010-2014 David Heiko Kolf*
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
|
||||
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
||||
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
@ -1,3 +1,11 @@
|
||||
Version 2.5 (2014-04-28)
|
||||
===========
|
||||
|
||||
Changes since version 2.4:
|
||||
|
||||
* Added customizable exception handling.
|
||||
* Decode input that contains JavaScript comments.
|
||||
|
||||
Version 2.4 (2013-09-28)
|
||||
===========
|
||||
|
||||
|
||||
Reference in New Issue
Block a user