nodemcu-firmware/docs/modules/sjson.md

# SJSON Module
| Since  | Origin / Contributor  | Maintainer  | Source  |
| :----- | :-------------------- | :---------- | :------ |
| 2017-02-01 | [Philip Gladstone](https://github.com/pjsg) | [Philip Gladstone](https://github.com/pjsg) | [sjson](../../app/modules/sjson.c) |

The JSON support module. Allows encoding and decoding to/from JSON.

Please note that nested tables can require a lot of memory to encode. To catch out-of-memory errors, use `pcall()`.

This code using the streaming json library [jsonsl](https://github.com/mnunberg/jsonsl) to do the parsing of the string.

This module can be used in two ways. The simpler way is to use it as a direct drop-in for cjson (you can just do `_G.cjson = sjson`). 
The more advanced approach is to use the streaming interface. This allows encoding and decoding of significantly larger objects.

The handling of json null is as follows:

- By default, the decoder represents null as sjson.NULL (which is a userdata object). This is the behavior of cjson.
- The encoder always converts any userdata object into null.
- Optionally, a single string can be specified in both the encoder and decoder. This string will be used in encoding/decoding to represent json null values. This string should not be used
anywhere else in your data structures. A suitable value might be `"\0"`.

When encoding a Lua object, if a function is found, then it is invoked (with no arguments) and the (single) returned value is encoded in the place of the function.

!!! note

    All examples below use in-memory JSON or content read from the SPIFFS file system. However, where a streaming implementation really shines is in fetching large JSON structures from the remote resources and extracting values on-the-fly. An elaborate streaming example can be found in the [`/lua_examples`](../../lua_examples/sjson-streaming.lua) folder.

## sjson.encoder()

This creates an encoder object that can convert a Lua object into a JSON encoded string.

####Syntax
`sjson.encoder(table [, opts])`

####Parameters
- `table` data to encode
- `opts` an optional table of options. The possible entries are:
   - `depth` the maximum encoding depth needed to encode the table. The default is 20 which should be enough for nearly all situations.
   - `null` the string value to treat as null.

####Returns
A `sjson.encoder` object.

## sjson.encoder:read

This gets a chunk of JSON encoded data.

####Syntax
`encoder:read([size])`

####Parameters
- `size` an optional value for the number of bytes to return. The default is 1024.

####Returns
A string of up to `size` bytes, or `nil` if the encoding is complete and all data has been returned.

#### Example
The following example prints out (in 64 byte chunks) a JSON encoded string containing the first 4k of every file in the file system. The total string
can be bigger than the total amount of memory on the NodeMCU.

```lua
function files() 
   result = {}
   for k,v in pairs(file.list()) do
     result[k] = function() return file.open(k):read(4096) end
   end
   return result
end

local encoder = sjson.encoder(files())

while true do
   data = encoder:read(64)
   if not data then
      break
   end
   print(data)
end
```

## sjson.encode()

Encode a Lua table to a JSON string. This is a convenience method provided for backwards compatibility with `cjson`.

####Syntax
`sjson.encode(table [, opts])`

####Parameters
- `table` data to encode
- `opts` an optional table of options. The possible entries are:
    - `depth` the maximum encoding depth needed to encode the table. The default is 20 which should be enough for nearly all situations.
    - `null` the string value to treat as null.

####Returns
JSON string

####Example
```lua
ok, json = pcall(sjson.encode, {key="value"})
if ok then
  print(json)
else
  print("failed to encode!")
end
```

## sjson.decoder()

This makes a decoder object that can parse a JSON encoded string into a Lua object. A metatable can be specified for all the newly created Lua tables. This allows
you to handle each value as it is inserted into each table (by implementing the `__newindex` method).

####Syntax
`sjson.decoder([opts])`

#### Parameters
- `opts` an optional table of options. The possible entries are:
    - `depth` the maximum encoding depth needed to encode the table. The default is 20 which should be enough for nearly all situations.
    - `null` the string value to treat as null.
    - `metatable` a table to use as the metatable for all the new tables in the returned object.

#### Returns
A `sjson.decoder` object

####Metatable

There are two principal methods that are invoked in the metatable (if it is present).

- `__newindex` this is the standard method invoked whenever a new table element is created.
- `checkpath` this is invoked (if defined) whenever a new table is created. It is invoked with two arguments:
    - `table` this is the newly created table
    - `path` this is a list of the keys from the root. 
    It must return `true` if this object is wanted in the result, or `false` otherwise.

For example, when decoding `{ "foo": [1, 2, []] }` the checkpath will be invoked as follows:

- `checkpath({}, {})` the `table` argument is the object that will correspond with the value of the JSON object.
- `checkpath({}, {"foo"})` the `table` argument is the object that will correspond with the value of the outer JSON array.
- `checkpath({}, {"foo", 3})` the `table` argument is the object that will correspond to the empty inner JSON array.

When the `checkpath` method is called, the metatable has already be associated with the new table. Thus the `checkpath` method can replace it
if desired. For example, if you are decoding `{ "foo": { "bar": [1,2,3,4], "cat": [5] } }` and, for some reason, you did not want to capture the
value of the `"bar"` key, then there are various ways to do this:

* In the `__newindex` metamethod, just check for the value of the key and skip the `rawset` if the key is `"bar"`. This only works if you want to skip all the 
`"bar"` keys.

* In the `checkpath` method, if the path is `["foo"]`, then return `false`.

* Use the following `checkpath`:  `checkpath=function(tab, path) tab['__json_path'] = path return true end` This will save the path in each constructed object. Now the `__newindex` method can perform more sophisticated filtering.

The reason for being able to filter is that it enables processing of very large JSON responses on a memory constrained platform. Many APIs return lots of information
which would exceed the memory budget of the platform. For example, `https://api.github.com/repos/nodemcu/nodemcu-firmware/contents` is over 13kB, and yet, if 
you only need the `download_url` keys, then the total size is around 600B. This can be handled with a simple `__newindex` method. 

## sjson.decoder:write

This provides more data to be parsed into the Lua object.

####Syntax
`decoder:write(string)`

####Parameters

- `string` the next piece of JSON encoded data

####Returns
The constructed Lua object or `nil` if the decode is not yet complete.

####Errors
If a parse error occurrs during this decode, then an error is thrown and the parse is aborted. The object cannot be used again.


## sjson.decoder:result

This gets the decoded Lua object, or raises an error if the decode is not yet complete. This can be called multiple times and will return the 
same object each time.

####Syntax
`decoder:result()`

####Errors
If the decode is not complete, then an error is thrown.

####Example
```
local decoder = sjson.decoder()

decoder:write("[10, 1")
decoder:write("1")
decoder:write(", \"foo\"]")

for k,v in pairs(decoder:result()) do
   print (k, v)
end
```

The next example demonstrates the use of the metatable argument. In this case it just prints out the operations, but it could suppress the assignment
altogether if desired.

```
local decoder = sjson.decoder({metatable=
        {__newindex=function(t,k,v) print("Setting '" .. k .. "' = '" .. tostring(v) .."'") 
                                    rawset(t,k,v) end}})

decoder:write('[1, 2, {"foo":"bar"}]')

```


## sjson.decode()

Decode a JSON string to a Lua table. This is a convenience method provided for backwards compatibility with `cjson`.

####Syntax
`sjson.decode(str[, opts])`

####Parameters
- `str` JSON string to decode
- `opts` an optional table of options. The possible entries are:
    - `depth` the maximum encoding depth needed to encode the table. The default is 20 which should be enough for nearly all situations.
    - `null` the string value to treat as null.
    - `metatable` a table to use as the metatable for all the new tables in the returned object. See the metatable section in the description of `sjson.decoder()` above.

####Returns
Lua table representation of the JSON data

####Errors
If the string is not valid JSON, then an error is thrown.

####Example
```lua
t = sjson.decode('{"key":"value"}')
for k,v in pairs(t) do print(k,v) end
```

##Constants

There is one constant, `sjson.NULL`, which is used in Lua structures to represent the presence of a JSON null.