Class: JSONReader

• Inheritance
• Description
• Class protocol
  • API - decoding
  • API - encoding
  • instance creation
• Instance protocol
  • initialization
  • private
  • reading
• Examples

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--JSONReader

Package:

stx:goodies/communication

Category:

Net-Communication-JSON

Version:

rev: 1.34 date: 2019/08/17 22:21:14

user: cg

file: JSONReader.st directory: goodies/communication

module: stx stc-classLibrary: communication

Description:

I read data structures (currently build of OrderedCollection and Dictionary)
from and to JSON (Java Script Object Notation). 
Writing is done with the #toJSON: class-method (note: it will behave badly with circular data structures).
Reading via the #fromJSON: class-method.

Notice: 
    By default (and standard), 
    Date, Time and Timestamps are written as iso8601 strings,
    and read initially as strings (thus, they must be converted explicitely back if required).

    The non-standard (but supported by some browsers) format is 'new Date(...)' which is generated
    optionally, if the useISODateFormat flag is turned off in the JSONPrinter.
    However, we cannot read back this format.
    As per ECMA,
        JSON.stringify({'now': new Date()}) 
    should generate
        {''now'':''2013-10-21T13:28:06.419Z''}
    which is exactly what JSONPrinter now generates by default
        JSONPrinter encode:(Structure with: #now -> (Timestamp now)).

Another Note:
    Can now also encode arbitrary Smalltalk objects; however, the reader will always decode them 
    as dictionaries:
        JSONPrinter encode:(Point x:10 y:20).
        JSONReader decode:(JSONPrinter encode:(Point x:10 y:20)).

Final Notice:
    take a look at the other (alternative) JSON framework (Json),
    which can also be used to handle JSON data, and offers a more flexible
    object mapping mechanism to decode into real objects.

Author:
    Public Domain Code from Robin Redeker published in lists.gnu.org
    adapted to ST/X by Claus Gittinger

Class protocol:

 decode: stringOrStream

decode the JSON string (as received from JavaScript) to an object

 fromJSON: stringOrStream

decode the JSON string (as received from JavaScript) to an object.
Same as decode:
Added to make the decoder protocol-conform to other encoders.

 readFrom: stringOrStream

decode the JSON string (as received from JavaScript) to an object.
Same as decode:
Added to make the decoder protocol-conform to other encoders.

 encode: anObject

return a JSON string which represents the object (can be sent to JavaScript).
Same as toJSON:
Added to make this more protocol-conform to other encoders.

 toJSON: anObject

return a JSON string which represents the object (can be sent to JavaScript).
Same as encode:
Added to make this more protocol-conform to other encoders.

 toJSON: anObject on: aStream

append a JSON string which represents the object (can be sent to JavaScript)
to aStream.
Same as encode:
Added to make this more protocol-conform to other encoders.

usage example(s):

self toJSON:#('hello' 123 true (1 'two' 3.0)) on:Transcript.

 new

return an initialized instance

 on: aStream

Instance protocol:

 initialize

JSONPrinter encode:((10@20) corner:(100@200))

 makeSlotDecoderFor: typeInfoFormat

 typeInfoFormat: formatSymbolOrNil

specify the format of the type info to be store with the slots.
For now, the formats supported are:
nil (default): no type info (standard JSON)
#stx : encode as { '@type': , <classNameString> , 'value': <encoding> }
more formats may be implemented in the future.

 atEnd

 next

I'm returning the next non-whitespace character

 nextJSONArray

I decode JSON arrays from self and will return an Array for them.

 nextJSONDict

I decode JSON objects from self and will return a Dictionary containing all the key/value pairs.

 nextJSONNumber

I'm extracting a number in JSON format from self and return Integer or Float depending on the input.

 nextJSONString

I'm extracting a JSON string from self and return it as String.

 peek

I'm peeking for the next non-whitespace character and will drop all whitespace in front of it

 stream: aStream

 decode: stringOrStream

 nextJSONObject

I decode a json self to a value, which will be one of:
nil, true, false, OrderedCollection, Dictionary, String or Number
(I will return Integer or Float depending on the input).

Examples:

    |o1 s o2|
    o1 := #('hello' 123 nil true false (1 'two' 3.0) -4 -1.5).
    s := JSONPrinter toJSON:o1.   
    o2 := JSONReader fromJSON:s.   
    self assert:(o1 = o2).  

    |o1 s o2|
    o1 := InlineObject slotNames:#('foo' 'bar' 'baz') values:#(1 2 3).
    s := JSONPrinter toJSON:o1.  
    o2 := JSONReader fromJSON:s.    

    |o1 s o2|
    o1 := OrderedDictionary withKeys:#('foo' 'bar' 'baz') andValues:#(1 2 3).
    s := JSONPrinter toJSON:o1.  
    o2 := JSONReader fromJSON:s.   
    self assert:(o1 = o2).

    |o1 s o2|
    o1 := Dictionary withKeysAndValues:#('one' 1 'two' 2 'three' 3.0 'four' 'vier').
    s := JSONPrinter toJSON:o1.
    o2 := JSONReader fromJSON:s.   
    self assert:(o1 sameContentsAs: o2).

    |o1 s o2|
    o1 := Dictionary withKeysAndValues:#('one two three' 123).
    s := JSONPrinter toJSON:o1.
    o2 := JSONReader fromJSON:s.   
    self assert:(o1 sameContentsAs: o2).

    |o1 s o2|
    o1 := { Date today . Time now . Timestamp now }.
    s := JSONPrinter encode:o1.
    o2 := JSONReader decode:s.
    -- notice: data & times are decoded as strings

    |o1 s o2|
    o1 := { Point x:10 y:20 }.
    s := JSONPrinter new useISODateFormat:false; encode:o1.
    o2 := JSONReader decode:s.
    self assert:(o1 sameContentsAs: o2).

    |o1 s o2|
    o1 := { Date today . Time now . Timestamp now }.
    s := JSONPrinter new useISODateFormat:false; encode:o1.
    o2 := JSONReader decode:s -- fails as non-JSON