JSONlib

Extension

Description

Encode SuperCollider objects to the JSON format and decode them from the JSON format.

Quickstart

Encodinge = (\foo: "mapping"); e.asJSON; // -> { "foo": "mapping" } // or use the lib directly JSONlib.convertToJSON(e);

Decoding// escaping of quotes is necessary j = "{\"hello\": 42}"; JSONlib.convertToSC(j); // -> ( 'hello': 42 ) // to avoid the need for escaping strings, you can also use a symbol. // (note that you still need to escape ' if they are in your json) j = '{"hello": 42}'; JSONlib.convertToSC(j); // -> ( 'hello': 42 )

Also see *new and the examples.

What is JSON

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.¹

JSON is a common exchange format in the internet as Browsers provide a JavaScript runtime and JSON is the native exchange format for JavaScript objects. This led to wide adaption as it is a fixed standard with a variety of use cases. The network communication abilties of SuperCollider are restricted to OSC Communication which can only transfer Arrays but no nested dictionaries. But by using a JSON string we can transfer nested key-value pairs (see Transfer nested objects via OSC).

For more information consult https://www.json.org/

Yet another JSON parser?

But isn't there alreday a built in method called String: -parseJSON? Yes, but String: -parseJSON implementation

• lacks an encoder, so the conversion of e.g. a Dictionary to a JSON string representation
• does not respect the types of a JSON but instead uses the type of String for every value

An encoder simply needs to translate the SuperCollider data types to the set of JSON data types. As there are far more SuperCollider data types than JSON data types we rely on some implicit and explicit conversions. Consult the source code on what kind of implicit conversions are made. These defaults can be overwritten and extended by providing a customEncoder or customDecoder (see JSONlib: *new).

The type conversion issue is a bit more difficult as it is not possible for us to recover the original types from the JSON explicitly. Was "42" always a string or was it an Integer once that got converted by String: -parseJSON from an Integer to a String? - so we decided to use implicit assignment of an appropriate class (also known as type casting in other programming languages) if the string matches a JSON representation other than String. The only exception here is null, see below.

If you do not want to make use of the implicit casting simply use the built in String: -parseJSON.

Consider the JSON {"number": 42}j = "{\"number\": 42\}"; j.parseJSON["number"].class; // -> String JSONlib.convertToSC(j)[\number].class; // -> Integer

Representing null in SuperCollider

null is a special value in JSON which represents the intentional absence of any object value.² .

SuperColliders equivalent would be object nil, check Nil for more information. Yet it is not as easy as that because we can not store nil as a value in a Dictionary as this is the sclang syntax to delete a key-value pair within a dictionary because nil represents the return value for an empty slot and put(key, nil) is equivalent to removing the object at key.e = (\foo: nil, \bar: 42); // -> ( 'bar': 42 )

To overcome this constraint we wrap nil into a Ref (shortcut is using the backtick, so `nil) wherever we encounter a null value in the JSON string.e = (\foo: `nil, \bar: 42); // -> ( 'foo': `(nil), 'bar': 42 ) e[\foo]; // -> `(nil) // use .value to unpack the reference e[\foo].value // -> nil // you can also use .value on other data types e[\bar].value // generates a null value in our JSON e.asJSON // -> { "bar": 42, "foo": null }

The same applies if we decode null from JSON stringj = "{\"foo\": null, \"bar\": 42}"; e = JSONlib.convertToSC(j); // -> ( 'bar': 42, 'foo': `(nil) ) e[\foo].value; // -> nil

See https://github.com/musikinformatik/JSONlib/issues/7 and https://github.com/musikinformatik/JSONlib/issues/5 for discussion.

Class Methods

.new

.convertToSC

.parseFile

.convertToJSON

Instance Methods

.postWarnings

.customEncoder

.useEvent

.customDecoder

Examples

Convert an Event to a JSON string

Convert a Dictionary to a JSON string

Convert a JSON string to an Event

See *convertToSC on advice how to handle escaping of JSON strings.j = "{\"foo\": 42}"; // as event e = JSONlib.convertToSC(j); // -> ( 'foo': 42 ) // access values via symbols e[\foo]; // as dictionary d = JSONlib.convertToSC(j, useEvent: false); // -> Dictionary[ (foo -> 42) ] // access values via strings d["foo"]; // -> 42

Save to file

See File for further details.

Using null

See also Representing null in SuperCollider and Ref

Encoding// wrap nil in a Ref (using `) to keep it as a value in an event e = (\nothing: `nil); // -> ( 'nothing': `(nil) ) JSONlib.convertToJSON(e); // -> { "nothing": null } // using nil directly does NOT work, see e = (\nothing: nil); // -> ( )

Decoding

Consider the JSON {"nothing": null}j = "{\"nothing\": null}"; e = JSONlib.convertToSC(j); // -> ( 'nothing': `(nil) ) // accessing nothing returns only a ref e[\nothing]; // -> `(nil) // unwrap it via .value e[\nothing].value; // -> nil

Use custom en/decoders to store functions

Useful if you want to exchange functions and data via network (see below)// create event with function x = (\myFunc: {|x| x**2}, \data: 42); // encode it to JSON ( a = JSONlib.convertToJSON(x, customEncoder: {|x| if(x.class==Function, { "--func%".format(x.asCompileString).quote; }); }); ) // -> { "data": 42, "myFunc": --func{|x| x**2} } // decode JSON to SC with our custom decoder // which re-constructs the function ( b = JSONlib.convertToSC(a, customDecoder: {|x| if(x.class==String) { if(x.beginsWith("--func")) { x["--func".size()..].compile().(); } } }); ) // -> ( 'myFunc': a Function, 'data': 42 ) b[\myFunc].(4) // -> 16.0

Transfer nested objects via OSC

JSON allows to distribute and receive nested objects via OSC by distributing it as a String in an OSC message.// create event e = (\hello: (\foo: 42)); // create local listener which converts a JSON string to an SC object ( OSCdef(\myJSONparser, func: {|m| // received strings are symbols, so we need to cast them to strings "Received %".format(JSONlib.convertToSC(m[1].asString)).postln; }, path: "/myAddress", recvPort: 57120); ) // send nested event as JSON ( NetAddr(hostname: "127.0.0.1", port: 57120).sendMsg( "/myAddress", JSONlib.convertToJSON(e), ); ) // Received ( 'hello': ( 'foo': 42 ) ) // clear OSC listener OSCdef.clear;