From bf658981b0db6e9223e94194a568221d048bfd3a Mon Sep 17 00:00:00 2001 From: Damien Cassou Date: Mon, 15 Jun 2015 18:33:08 +0200 Subject: [PATCH] Start working on NeoJSON --- NeoJSON/NeoJSON.pier | 82 ++++++++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 29 deletions(-) diff --git a/NeoJSON/NeoJSON.pier b/NeoJSON/NeoJSON.pier index d3ce9b6..1e9affa 100644 --- a/NeoJSON/NeoJSON.pier +++ b/NeoJSON/NeoJSON.pier @@ -2,7 +2,7 @@ @cha:JSON JSON (JavaScript Object Notation) is a popular data-interchange format. NeoJSON is an elegant and efficient standalone Smalltalk framework to read and write -JSON converting to or from Smalltalk objects developed and actively maintained by Sven Van Caekenberghe. +JSON converting to and from Smalltalk objects. The framework is developed and actively maintained by Sven Van Caekenberghe. !!An introduction to JSON @@ -10,7 +10,7 @@ JSON is a lightweight text-based open standard designed for human-readable data representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for many languages. -Here are some relevant links: *http://www.json.org/*, *http://en.wikipedia.org/wiki/Json* and *http://www.ietf.org/rfc/rfc4627.txt?number=4627*. +@@note References: *http://www.json.org/*, *http://en.wikipedia.org/wiki/Json* and *http://www.ietf.org/rfc/rfc4627.txt?number=4627*. There are only a couple of primitive types in JSON: @@ -28,35 +28,44 @@ That is really all there is to it. No options or additions are defined in the st !! NeoJSON -The NeoJSON framework contains a reader (==NeoJSONReader==) and a writer (==NeoJSONWriter==) to parse respectively generate JSON to or from Pharo objects. The -goals of this project are: +To load NeoJSON, evaluate the following: --to be standalone (have no dependencies and have little requirements) --to be small, elegant and understandable --to be efficient (both in time and space) --to be flexible and non-intrusive +[[[language=smalltalk +Gofer it + smalltalkhubUser: 'SvenVanCaekenberghe' project: 'Neo'; + configurationOf: 'NeoJSON'; + loadStable. +]]] + + +The NeoJSON framework contains a reader (==NeoJSONReader==) and a writer (==NeoJSONWriter==) to parse, respectively generate, JSON to and from Pharo objects. The goals of this framework are: -Compared to other Smalltalk JSON frameworks, NeoJSON has +-to be standalone (have no dependencies and little requirements); +-to be small, elegant and understandable; +-to be efficient (both in time and space); +-to be flexible and non-intrusive. --less dependencies and little requirements --can be more efficient (be faster and use less memory) --allows for the use of schemas and mappings +Compared to other Smalltalk JSON frameworks, NeoJSON + +-has less dependencies and little requirements; +-can be more efficient (be faster and use less memory); +-allows for the use of schemas and mappings. !!Primitives Obviously, the primitive types are mapped to corresponding Pharo classes. While reading: -- numbers become Integers or Floats -- strings become Strings -- booleans become Booleans -- ==null== become ==nil== +- JSON numbers become instances of ==Integer== or ==Float== +- JSON strings become instances of ==String== +- JSON booleans become instances of ==Boolean== +- JSON ==null== becomes ==nil== -While writing +While writing: -- Numbers are converted to floats, except for Integers that become integers -- Strings and subclasses become strings -- Booleans become booleans -- ==nil== becomes ==null== +- Pharo numbers are converted to floats, except for instances of ==Integer== that become JSON integers; +- Pharo strings become JSON strings; +- Pharo booleans become JSON booleans; +- Pharo ==nil== becomes JSON ==null==. !! Generic Mode @@ -67,21 +76,34 @@ NeoJSON can operate in a generic mode that requires no further configuration. While reading: -- maps become instances of mapClass, ==Dictionary== by default --lists become instance of listClass, ==Array== by default +-JSON maps become instances of mapClass, ==Dictionary== by default; +-JSON lists become instances of listClass, ==Array== by default. -These are some examples reading in generic mode: +This example creates a Pharo dictionary (with ==x== and ==y== keys): -[[[NeoJSONReader fromString: ' [ 1,2,3 ] '. +[[[language=smalltalk +NeoJSONReader fromString: ' { "x" : 1, "y" : 2 } '. +]]] -NeoJSONReader fromString: ' [ 3.14159, true, false, null, "string" ] '. +The following example creates a Pharo array from a JSON expression: -NeoJSONReader fromString: ' { "x" : 1, "y" : 2 } '.]]] +[[[language=smalltalk +NeoJSONReader fromString: ' [ 1,2,3 ] '. +]]] + +This expression can be decomposed to better control the reading process: +[[[language=smalltalk +(NeoJSONReader on: ' [ 1,2,3 ] ' readStream) + listClass: OrderedCollection; + next. +]]] -The reader can be customized to use a different mapClass or listClass. There is also an option to convert all map keys to symbols, which is off by default. +The above expression is equivalent to the previous one except that an ordered collection will be used in place of an array. -SD: example of how to specify options +There is also an option to convert all map keys to symbols, which is off by default. + +@@authorToDo DC: example of how to specify options @@ -253,3 +275,5 @@ can use them both using a quick and dirty explore style. Here are some examples: NeoJSON is a powerful library to convert objects. Now Sven developed STON (Smalltalk object notation) which is closer to Pharo syntax and handles cycles and references between serialized objects. + +% LocalWords: Caekenberghe