Merge pull request #21 from musikinformatik/quickstart

add quickstart section

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

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;

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
 

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|