JSONEncoder

This library can be used to encode Squirrel data structures into JSON.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

Note For agent usage, see also the native imp API method http.jsonencode(), but bear in mind that, unlike this library, the API method does not handle classes and instances.

To add this library to your project, add

#require "JSONEncoder.class.nut:2.0.0"

to the top of your agent and/or device code.

Usage

JSONEncoder has no constructor and one public function, encode().

encode(data)

The encode() method takes one required parameter: the data to be encoded. It returns a JSON string version of that data.

Basic Example

data <- { "one": 1 };
jsonString <- JSONEncoder.encode(data);

server.log(typeof jsonString);
// Displays 'string'

server.log(jsonString);
// Displays '{"one":1}'

Serialization Details

Unicode Strings

The class’ current implementation suggests that Squirrel is compiled with single-byte strings (as is the case with the Electric Imp Platform) and correctly handles UTF-8 characters.

Class Serialization

When serializing classes, functions are ignored and only properties are exposed.

Instance Serialization

When serializing instances, functions are ignored and only properties are exposed. If the instance implements the _nexti() metamethod, it can define a custom serialization behavior. Another way for defining custom representation in JSON is to implement a _serialize() method in your class.

Custom Serialization with _serialize() Method

Instances can contain a _serialize() method that is called during the encoding to get the representation of an instance as (for example) a table or an array. See the extended example below.

Serializing As-is

In some cases it may be useful to provide a ‘raw’ representation of an instance to the JSON encoder. In order to do so, an instance can define a _serializeRaw() method returning a string value. This value is then inserted into the resulting JSON output without further processing or escaping.

class A {
  function _serializeRaw() {
    // Very long integer
    return "12345678901234567890";
  }
};

value <- JSONEncoder.encode( [ A() ] );
server.log(typeof value);
// Displays 'string'

server.log(value);
// Displays '[12345678901234567890]'

Note While this method may be useful in certain cases, it has the potential to produce a non-valid JSON output.

Extended Example

class A {
  _field = 123;

  // Returns instance representation as table
  function _serialize() {
    return {
      field = this._field
    }
  }
}

t <- {
  a = 123,
  b = [1, 2, 3, 4],
  c = A,
  d = 5.125,
  e = A(),
  f = null,
  g = true,
  h = "Some\nùnicode\rstring ø∆ø"
};

server.log(JSONEncoder.encode(t));
// Displays '{"a":123,"c":{"_field":123},"b":[1,2,3,4],"e":{"field":123},"d":5.125,"g":true,"f":null,"h":"Some\nùnicode\rstring ø∆ø"}'
// Note: this output is a JSON string

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release
2.0.0	GitHub	Added workaround for Blob.tostring() returning null not ""

License

This library is licensed under MIT License.