diff --git a/HelpSource/Classes/JSONlib.schelp b/HelpSource/Classes/JSONlib.schelp index 29f0784..24163c3 100644 --- a/HelpSource/Classes/JSONlib.schelp +++ b/HelpSource/Classes/JSONlib.schelp @@ -186,9 +186,9 @@ e[\myPoint].x METHOD:: convertToSC Encodes a given JSON string to a link::Classes/Event::, link::Classes/Dictionary:: or link::Classes/Array::. -argument:: string -JSON string one wants to parse. -Keep in mind that any code::":: needs to be escaped with code::\"::, so at least every key needs this. +argument:: json +JSON link::Classes/String:: or link::Classes/Symbol:: one wants to parse. +Keep in mind that when using a String any code::":: needs to be escaped with code::\":: (so at least every key needs this) and on a Symbol code::':: needs to be escaped with code::\'::. If you have copied a JSON from elsewhere either save it as a file and use link::#*parseFile:: or use the console of your browser by simply wrapping the JSON into backticks (e.g. code::`{"my": "json"}`::). The returned string will contain the all necessary string escapes for SuperCollider." argument:: customDecoder diff --git a/README.md b/README.md index a9b71b3..7e8aa43 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,76 @@ which this Quark implements, building on top of the existing implementation. There also exists a [json](https://github.com/supercollider-quarks/json) Quark which also adds a wrapper for [sccode.org](https://sccode.org) but lacks a recursive encoding of objects. The goal of `JSONlib` is to simply provide a full implementation of the JSON standard in sclang and nothing beyond it. +## Quickstart + +### Installation + +```supercollider +// install the quark +Quarks.install("https://github.com/musikinformatik/JSONlib.git"); + +// restart the interpreter so the new classes are available +thisProcess.recompile; + +// open documention +HelpBrowser.openHelpFor("Classes/JSONlib"); +``` + +### Basic usage + +#### Parse a JSON + +Let's say we have a JSON with an integer as a value + +```json +{ + "hello": 42 +} +``` + +which we want to parse in sclang. + +```supercollider +// use Symbol instead of String to get rid of escaping quotation marks +j = '{"hello": 42}'; + +// turn this into an Event +d = JSONlib.convertToSC(j); +// -> ( 'hello': 42 ) + +// an integer gets parsed as an integer +d[\hello].class +// -> Integer + +// compare to the built-in method of sclang +// it uses a Dictionary instead of an Event +d = j.parseJSON() +// -> Dictionary[ (hello -> 42) ] + +// but 42 is a string here +d["hello"].class +// -> String +``` + +#### Encode an Event as JSON + +```supercollider +// create an event +e = (\foo: "bar", \baz: (\nested: true)); + +e.asJSON +// -> { "baz": { "nested": true }, "foo": "bar" } + +// or use the class JSONlib +JSONlib.convertToJSON(e); +// -> { "baz": { "nested": true }, "foo": "bar" } +``` + +Advanced usage is described in the SCdoc documentation. + ## Development -Run tests via +Make sure to run the tests via ```supercollider TestJSONlib.run; diff --git a/Tests/TestJSONlib.sc b/Tests/TestJSONlib.sc index 3a84bf9..075012e 100644 --- a/Tests/TestJSONlib.sc +++ b/Tests/TestJSONlib.sc @@ -412,6 +412,16 @@ TestJSONlib : UnitTest { } + test_jsonSymbolAsString { + var j = '{"hello": 42}'; + var e = JSONlib.convertToSC(j); + this.assertEquals( + e[\hello], + 42, + "convertToSC needs to accept Symbols as well", + ); + } + // private implementation // util diff --git a/classes/JSONlib.sc b/classes/JSONlib.sc index 704cd7d..06db275 100644 --- a/classes/JSONlib.sc +++ b/classes/JSONlib.sc @@ -16,15 +16,19 @@ JSONlib { ^this.new(postWarnings, customEncoder: customEncoder).prConvertToJson(object) } - *convertToSC {|string, customDecoder=nil, useEvent=true, postWarnings=true| - if(string.isKindOf(String).not) { - Error("Can only parse a String to JSON but received %".format(string.class)).throw + *convertToSC {|json, customDecoder=nil, useEvent=true, postWarnings=true| + if(json.isKindOf(Symbol)) { + json = json.asString; + }; + + if(json.isKindOf(String).not) { + Error("Can only parse a String to JSON but received %".format(json.class)).throw }; ^this.new( postWarnings, customDecoder: customDecoder, useEvent: useEvent - ).prConvertToSC(string.parseJSON) + ).prConvertToSC(json.parseJSON) } *parseFile {|filePath, customDecoder=nil, useEvent=true, postWarnings=true|