Start working on NeoJSON

NeoJSON/NeoJSON.pier

@@ -2,15 +2,15 @@
 @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
 
 JSON is a lightweight text-based open standard designed for human-readable data interchange. It was derived from the JavaScript scripting language for 
 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