STON

https://github.com/svenvc/ston
Admin
STON is a lightweight, human-readable data interchange format for class-based object-oriented...
Tokens:18,528
Snippets:63
Trust Score:9.2
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install STON using Metacello

Source: https://github.com/svenvc/ston/blob/master/README.md

Installs the STON library using the Metacello package manager. This involves specifying the baseline and repository for loading the package.

```Smalltalk
Metacello new
	baseline: 'Ston';
	repository: 'github://svenvc/ston/repository';
	load
```

--------------------------------

### STONJSON Example Usage

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STONJSON.class/README.md

Illustrative examples demonstrating how to use STONJSON for parsing and writing JSON data, including handling basic data types and dictionaries.

```Smalltalk
STONJSON toString: { 1. -1. Float pi. true. 'JSON' }.
STONJSON fromString: '[1,-1,3.141592653589793,true,"JSON"]'.

STONJSON toStringPretty: { #foo->1. #bar->2 } asDictionary.
STONJSON fromString: '{"foo":1,"bar":2,"sub":{"a":true,"b":false},"flags":[1,8,32]}'.
```

--------------------------------

### STON Example: HTTP Response (ZnResponse)

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Presents a complex STON example serializing a ZnResponse object from the Zinc HTTP Components framework, detailing headers, entity content, and status line.

```STON
ZnResponse {
  #headers : ZnHeaders {
    #headers : ZnMultiValueDictionary {
       'Date' : 'Fri, 04 May 2012 20:09:23 GMT',
       'Modification-Date' : 'Thu, 10 Feb 2011 08:32:30 GMT',
       'Content-Length' : '113',
       'Server' : 'Zinc HTTP Components 1.0',
       'Vary' : 'Accept-Encoding',
       'Connection' : 'close',
       'Content-Type' : 'text/html;charset=utf-8'
    }
  },
  #entity : ZnStringEntity {
    #contentType : ZnMimeType {
       #main : 'text',
       #sub : 'html',
       #parameters : {
           'charset' : 'utf-8'
       }
    },
    #contentLength : 113,
    #string : '<html>\n<head><title>Small</title></head>\n<body><h1>Small</h1><p>This is a small HTML document</p></body>\n</html>\n',
    #encoder : ZnUTF8Encoder { }
  },
  #statusLine : ZnStatusLine {
    #version : 'HTTP/1.1',
    #code : 200,
    #reason : 'OK'
  }
}
```

--------------------------------

### STON Example: TestDomainObject

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Demonstrates the STON serialization of a simple domain object, including various primitive types like strings, numbers, booleans, symbols, arrays, and byte arrays, along with class tags for specific types like DateAndTime.

```STON
TestDomainObject {
  #created : DateAndTime [ '2012-02-14T16:40:15+01:00' ],
  #modified : DateAndTime [ '2012-02-14T16:40:18+01:00' ],
  #integer : 39581,
  #float : 73.84789359463944,
  #description : 'This is a test',
  #color : #green,
  #tags : [
    #two,
    #beta,
    #medium
  ],
  #bytes : ByteArray [ 'afabfdf61d030f43eb67960c0ae9f39f' ],
  #boolean : false
}
```

--------------------------------

### STON Example: Rectangle Object

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Illustrates the STON representation of a Rectangle object, showing how geometric objects like Point can be serialized using class tags and nested structures.

```STON
Rectangle {
  #origin : Point [ -40, -15 ],
  #corner : Point [ 60, 35 ]
}
```

--------------------------------

### STON Example Object

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Demonstrates the structure of a STON object, including class tags, key-value associations for properties, lists, symbols, strings, and custom representations for common value objects like ByteArray, URL, and DateAndTime.

```STON
DoomUser {
	#name : 'John Doe',
	#password : ByteArray [ '5ebe2294ecd0e0f08eab7690d2a6ee69' ],
	#roles : [ #login, #admin ],
	#avatar : URL [ 'https://www.gravatar.com/avatar/f179b7f86ea5f35c32a6edf501f62bc7' ],
	#lastLogin : DateAndTime [ '2018-10-30T15:01:13.364516+01:00' ],
	#loginCount: 42 }
```

--------------------------------

### STONCStyleCommentsSkipStream Usage Example

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STONCStyleCommentsSkipStream.class/README.md

An example demonstrating how to instantiate and use STONCStyleCommentsSkipStream in Smalltalk. It shows creating an instance with a string containing a comment and reading its content up to the end.

```Smalltalk
(STONCStyleCommentsSkipStream on: 'abc/*comment*/def' readStream) upToEnd.
```

--------------------------------

### C-Style Comment Syntax

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STONCStyleCommentsSkipStream.class/README.md

Illustrates the common C-style comment syntax handled by STONCStyleCommentsSkipStream. This includes multiline comments enclosed in /* */ and single-line comments starting with //.

```C
/* a comment */
```

```C
// a comment
```

--------------------------------

### Load STON Configuration

Source: https://github.com/svenvc/ston/blob/master/repository/ConfigurationOfSton.package/ConfigurationOfSton.class/README.md

Loads the STON configuration using the Metacello system. This command initializes the STON project within a Smalltalk environment.

```Smalltalk
ConfigurationOfSton load.

```

--------------------------------

### STON Facade API: Parsing and Writing

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

The STON class acts as a facade for reading and writing STON data to streams or strings. It provides simple methods like `fromString:`, `fromStream:`, `toString:`, `toStringPretty:`, `put:onStream:`, and `put:onStreamPretty:` for common operations.

```Smalltalk
STON fromString: 'Rectangle { #origin : Point [ -40, -15 ], #corner : Point [ 60, 35 ] }'.

'/Users/sven/Desktop/foo.ston' asReference 
    fileStreamDo: [ :stream | STON fromStream: stream ].

STON toString: World bounds.

STON toStringPretty: World bounds.

'/Users/sven/Desktop/bounds.ston' asReference 
    fileStreamDo: [ :stream | 
        STON put: World bounds onStream: stream ].

'/Users/sven/Desktop/bounds.ston' asReference 
    fileStreamDo: [ :stream | 
        STON put: World bounds onStreamPretty: stream ].
```

--------------------------------

### STONTestKnownObject Instance Access

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Tests.package/STONTestKnownObject.class/README.md

Demonstrates how to access an instance of STONTestKnownObject using its unique identifier. This pattern is used for retrieving existing objects or potentially creating new ones based on the provided ID.

```APIDOC
STONTestKnownObject['bb71b026-180c-0d00-b40c-38700aee7555']

---

#fromId: (id)
  - Retrieves or creates an instance of STONTestKnownObject using its ID.
  - Parameters:
    - id: The unique identifier for the object.
  - Returns: An instance of STONTestKnownObject.
  - Behavior:
    - Checks its collection of known instances for a match.
    - If found, returns the existing instance.
    - If not found, creates a new instance using the ID and adds it to the collection.
```

--------------------------------

### STON: Object Representation and References

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Explains how STON represents objects, including optional class tags and representations as lists or maps. It also details the use of references ('@' followed by an integer) to handle shared objects and cycles within the data graph.

```STON
OrderedCollection [ Point [1, 2], @2, @2 ]
```

```STON
[ #foo, @1 ]
```

--------------------------------

### STON Syntax Definition

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

Defines the formal grammar and syntax rules for the STON (Smalltalk Object Notation) format, covering primitives, objects, collections, references, and literals.

```APIDOC
STON Syntax Grammar:

value ::= primitive-value | object-value | reference | nil
primitive-value ::= number | true | false | symbol | string
object-value ::= object | map | list
object ::= classname map | classname list
reference ::= '@' int-index-previous-object-value
map ::= '{}' | '{' members '}'
members ::= pair | pair ',' members
pair ::= string ':' value | symbol ':' value | number ':' value
list ::= '[]' | '[' elements ']'
elements ::= value | value ',' elements
string ::= "''" | "'" chars "'"
chars ::= char | char chars
char ::= <any-printable-ASCII-character-except-''"-or-\> | '\'' | '"' | '\\' | '\/' | '\b' | '\f' | '\n' | '\r' | '\t' | '\u' four-hex-digits
symbol ::= '#' chars-limited | '#' "'" chars-limited "'"
chars-limited ::= char-limited | char-limited chars-limited
char-limited ::= a-z | A-Z | 0-9 | '-' | '_' | '.' | '/'
classname ::= uppercase-alpha-char alphanumeric-char
number ::= int | int denominator | int denominator scale | int frac | int exp | int frac exp
int ::= digit | digit1-9 digits | '-' digit | '-' digit1-9 digits
digit ::= 0-9
digit1-9 ::= 1-9
digits ::= digit | digit digits
denominator ::= '/' digits
scale ::= 's' digits
frac ::= '.' digits
exp ::= 'e' digits | 'e+' digits | 'e-' digits | 'E' digits | 'E+' digits | 'E-' digits
```

--------------------------------

### STON Direct Reader/Writer Usage

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

For more control, you can use the STON reader and writer directly. The reader can be initialized with a stream and then used to parse the next object. The writer can be initialized with a stream and used to put objects onto it.

```Smalltalk
(STON reader on: 'Rectangle{#origin:Point[0,0],#corner:Point[1440,846]}' readStream)
    next.

String streamContents: [ :stream |
    (STON writer on: stream)
        nextPut: World bounds ].
```

--------------------------------

### STON Serialization/Deserialization Methods

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Classes can implement specific methods to integrate with the STON serialization framework. `stonOn:` is used for writing an object's state, `fromSton:` for reading state, `stonName` for aliasing class names, and `stonProcessSubObjects:` for handling forward references.

```Smalltalk
Object subclass: #MyClass
    instanceVariableNames: 'name age'
    classVariableNames: ''
    package: 'MyPackage'.

MyClass methodsFor: 'STON serialization' 
stonOn: stonWriter
    stonWriter nextPut: self name; nextPut: self age.

MyClass class methodsFor: 'STON deserialization'
fromSton:
    "Parses STON data to create a new instance."
    ^ self new.

stonName
    "Returns the external name for the class."
    ^ 'MyClassExternalName'.

stonProcessSubObjects:
    "Processes sub-objects or resolves forward references."
    "Implementation details here."
```

--------------------------------

### Add STON Dependency to Metacello Baseline

Source: https://github.com/svenvc/ston/blob/master/README.md

Configures a Metacello baseline to include the STON library, specifying its repository location. This is typically added to a project's baseline or configuration file.

```Smalltalk
spec 
   baseline: 'Ston' 
   with: [ spec repository: 'github://svenvc/ston/repository' ]
```

--------------------------------

### STON: Object Values (Lists and Maps)

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Illustrates STON's composite data structures: ordered lists enclosed in square brackets and unordered maps represented as key-value pairs within curly braces. Keys can be strings, symbols, or numbers.

```STON
[1, 2, 3]
```

```STON
{#a : 1, #b : 2}
```

```STON
Array [1, 2, 3]
```

```STON
Dictionary {#a : 1, #b : 2}
```

--------------------------------

### STON Association Syntax

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Describes STON associations as key/value pairs, serving as building blocks for maps. Both keys and values can be any valid STON value. The shorthand notation uses a colon ':' to separate the key and value, and is functionally equivalent to an object with class tag 'Association'.

```APIDOC
association = ston ":" ston
```

--------------------------------

### Customize STON Serialization for Missing Inst Vars

Source: https://github.com/svenvc/ston/wiki/Cookbook

When migrating between Pharo versions, missing instance variables can cause STON serialization to fail. This snippet shows how to customize STON behavior by implementing methods to skip specific instance variables or define custom serialization logic.

```Smalltalk
FileSystem class>>stonAllInstVarNames
  "Override to skip instance variables not present in the target image."
  ^ super stonAllInstVarNames reject: [:name | name = 'workingDirectory']
```

```Smalltalk
FileSystem>>stonOn: stonWriter
  "Custom serialization logic if #stonAllInstVarNames is not sufficient."
  stonWriter writeObject: self
    members: {#someVar . #anotherVar} "Only include relevant instance variables"
```

```Smalltalk
FileSystem>>fromSton:
  "Custom deserialization logic if needed."
```

--------------------------------

### STON Basic Serialization API

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

Provides core methods for serializing Smalltalk objects to STON strings and deserializing STON strings back into objects. These methods are part of a facade class for high-level STON operations.

```APIDOC
STON facade class API:

#toString: object
  - Serializes the given object into a STON formatted string.
  - Example:
    STON toString: DisplayScreen boundingBox.

#fromString: stonString
  - Deserializes a STON formatted string into a Smalltalk object.
  - Example:
    STON fromString: 'Rectangle{#origin:Point[0,0],#corner:Point[1920,1030]}'.

#toString: object
  - Serializes complex objects including collections and primitives.
  - Example:
    STON toString: { DateAndTime now. Float pi. 1 to: 10 by: 2. 3 days }.

#fromString: stonString
  - Deserializes complex STON strings representing collections and primitives.
  - Example:
    STON fromString: '[DateAndTime[''2016-03-15T13:57:59.462422+01:00''],3.141592653589793,Interval{#start:1,#stop:10,#step:2},Duration{#nanos:0,#seconds:259200}]'.
```

--------------------------------

### STON JSON Compatibility API

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

Allows for writing Smalltalk objects as JSON strings, leveraging STON's capabilities. Note that only Arrays and Dictionaries can be written as JSON.

```APIDOC
STON JSON output methods:

#toJsonString: object
  - Serializes the object into a JSON formatted string. Supports pretty printing via #toJsonStringPretty:.
  - Note: Only Arrays and Dictionaries are supported for JSON output.

#put: object asJsonOnStream: stream
  - Writes the object to the stream in JSON format. Supports pretty printing via #put: object asJsonOnStreamPretty: stream.
  - Note: Only Arrays and Dictionaries are supported for JSON output.
```

--------------------------------

### STon Grammar Definition

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

This section details the formal syntax rules for the STon data serialization format. It covers primitives, lists, associations, maps, objects, and references, defining the structure and valid characters for each component.

```APIDOC
ston = primitive | list | association | map | object | reference
primitive = number | string | symbol | boolean | nil
number = integer | fraction | scaled-decimal | float
integer = "0" | positive-integer | negative-integer
positive-integer = decimal-digit-non-zero decimal-digit *
negative-integer = "-" positive-integer
decimal-digit-non-zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
decimal-digit = "0" | decimal-digit-non-zero
fraction = nominator "/" denominator
nominator = positive-integer | negative-integer
denominator = positive-integer
scaled-decimal = nominator "/" denominator "s" scale
scale = positive-integer
float = integer [ float-fraction ] [ float-exponent ] 
float-fraction = "." decimal-digit *
float-exponent = float-ee [ float-ee-sign ] positive-integer
float-ee = "e" | "E"
float-ee-sign = "+" | "-"
string = "'" string-chars "'"
string-chars = [ string-char | string-escape ] *
string-char = < any Unicode char except "'" and "\" >
string-escape = fundamental-string-escape | named-string-escape | optional-string-escape | unicode-string-escape
fundamental-string-escape = "\\" | "'"
named-string-escape = "\b" | "\f" | "\n" | "\r" | "\t"
optional-string-escape = "\/" | "\""
unicode-string-escape = "\u" hex-digit hex-digit hex-digit hex-digit
hex-digit = decimal-digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"
symbol = simple-symbol | generic-symbol
simple-symbol = "#" simple-symbol-char
simple-symbol-char = uppercase-letter | lowercase-letter | decimal-digit | "-" | "_" | "." | "/"
lowercase-letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
uppercase-letter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
generic-symbol = "#" string
boolean = "true" | "false"
nil = "nil"
list-elements = ston | ston "," list-elements
list = "[]" | "[" list-elements "]"
association = ston ":" ston
map = "{}" | "{"
associations "}"
associations = association | association "," associations
object = class-tag object-representation
class-tag = uppercase-letter class-tag-char *
class-tag-char = uppercase-letter | lowercase-letter | decimal-digit | "_"
object-representation = list | map
reference = "@" positive-integer
```

--------------------------------

### STON Core Syntax Definitions

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Defines the fundamental syntax rules for the STON (Simple Text Oriented Notation) data serialization format, covering maps, objects, and references. These rules specify the structure and composition of these core data types within STON.

```APIDOC
STON Syntax Definitions:

Maps:
  An unordered collection of associations forming an associative lookup table.
  Syntax:
    associations = association | association "," associations
    map = "{" "}" | "{" associations "}"
  Notes:
    - Associations are separated by commas.
    - Maps can be empty.
    - Duplicate keys overwrite each other in the order they are read.

Objects:
  Consist of a class tag followed by a representation (list or map).
  Syntax:
    class-tag-char = uppercase-letter | lowercase-letter | decimal-digit | "_"
    class-tag = uppercase-letter class-tag-char *
    object-representation = list | map
    object = class-tag object-representation
  Notes:
    - Class tags start with an uppercase letter.
    - Objects are typically represented by a map of non-nil instance variables or a list for collection objects.

References:
  Used to represent shared structures and circular references within an object graph.
  Syntax:
    reference = "@" positive-integer
  Notes:
    - Objects are numbered sequentially from 1 in the order they are encountered during traversal.
    - Primitives are not counted as objects and cannot be targets of references.
    - Reference resolution may require a second pass over the graph.
```

--------------------------------

### STON FILE Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Files on disk are represented by a singleton list containing the full file path string. An uppercase tag is used to avoid implementation conflicts.

```STON
FILE [ '/tmp/data/foo.txt' ]
```

--------------------------------

### STON: Conventional Representations for Specific Types

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Details the custom STON representations for common Smalltalk classes to enhance compactness and readability. This includes formats for Time, Date, DateAndTime, Point, ByteArray, and Character.

```STON
Time [ '14:30:00' ]
```

```STON
Date [ '20231027' ]
```

```STON
DateAndTime [ '2023-10-27T14:30:00.123+01:00' ]
```

```STON
Point [ 10, 20 ]
```

```STON
ByteArray [ '01A3FF' ]
```

```STON
Character [ 'A' ]
```

--------------------------------

### STON Core Implementation Methods

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

These are the fundamental methods that STON uses internally for serialization and deserialization, working with STONWriter and STONReader classes. They allow for fine-grained control over the process.

```APIDOC
STON core implementation:

#stonOn: writer
  - Serializes the receiver object onto the given STONWriter.

#fromSton: reader
  - Materializes the receiver object from the given STONReader.

#reader
  - Returns the STONReader instance associated with the object or context.

#writer
  - Returns the STONWriter instance associated with the object or context.
```

--------------------------------

### STON Symbol Syntax

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Describes STON's support for symbols, which are unique identifiers within an object space. It covers simple symbols using a limited character set (letters, digits, -, _, ., /) prefixed with '#', and generic symbols which use a string literal prefixed with '#'.

```APIDOC
simple-symbol-char = uppercase-letter | lowercase-letter | decimal-digit | "-" | "_" | "." | "/"
simple-symbol = "#" simple-symbol-char
generic-symbol = "#" string
symbol = simple-symbol | generic-symbol
```

--------------------------------

### STON List Syntax

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Defines the syntax for STON lists, which are ordered sequences of values, analogous to indexable arrays. Lists are enclosed in square brackets and can be empty or contain comma-separated STON values. They are functionally equivalent to an object with class tag 'Array'.

```APIDOC
list-elements = ston | ston "," list-elements
list = "[]" | "[" list-elements "]"
```

--------------------------------

### STON Custom Collection Representations

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Details STON's conventions for custom representations of collection types, including ordered collections, sets, and dictionaries, to produce compact and readable output. It highlights how standard collections are represented and notes exceptions.

```APIDOC
STON Custom Collection Representations:

General Rule:
  Collections are typically represented by a list of their elements.
  Example:
    OrderedCollection [ #a, #b, #c ]
    Set [ #c, #a, #b ]

Map-like Collections:
  For collections with natural map representations, the map syntax is used.
  Example:
    OrderedDictionary { #a : 1, #b : 2, #c : 3 }

Special Cases (Array and Dictionary):
  These exact classes do not require a class tag as they directly represent list and map concepts.
  Example:
    [ #a, #b, #c ]
    { #a : 1, #b : 2, #c : 3 }

Exceptions and Other Types:
  Primitive collection subclasses like String, Symbol, and ByteArray have different representations.
  Other special types like Interval, RunArray, and Text revert to general object behavior using instance variables.
```

--------------------------------

### STON: Primitive Values

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

Defines the basic data types supported by STON, including numbers (integers and floats), strings enclosed in single quotes with escape mechanisms, symbols introduced by '#', and boolean constants 'true' and 'false'.

```STON
'Hello, \'STON\''
```

```STON
#mySymbol
```

```STON
12345
```

```STON
3.14159
```

```STON
true
```

```STON
false
```

--------------------------------

### STONWriter Customization Options

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STONWriter.class/README.md

STONWriter offers several customization options to control how objects are serialized into the Smalltalk Object Notation (STON) format. These options affect output formatting, character encoding, JSON compatibility, and reference handling.

```APIDOC
STONWriter:
  prettyPrint <Boolean> default is false
    if true, produce pretty printed output.

  newLine <String> default is String cr
    Specifies the sequence to use for End-Of-Line (EOL) characters.

  asciiOnly <Boolean> default is false
    if true, use \u escapes for all non-ASCII characters. Most common control characters are still escaped.

  jsonMode <Boolean> default is false
    if true, the following changes occur:
    - strings are delimited with double quotes
    - nil is encoded as null
    - symbols are treated as strings
    - only STON listClass and STON mapClass instances are allowed as composite objects.
    It is wise to also use either #error or #ignore as referencePolicy to avoid references.

  referencePolicy <#normal|#ignore|#error> default is #normal
    Controls how object references are handled:
    - #normal: Track and count object references to implement sharing and break cycles.
    - #error: Track object references and signal STONWriterError when a shared reference is encountered.
    - #ignore: Do not track object references, which might lead to infinite loops on cyclic structures.

  keepNewLines <Boolean> default is false
    if true, any newline sequence (CR, LF, or CRLF) inside strings or symbols will not be escaped but will be written as the newline EOF convention.

  Note on Escapes:
    In default STON mode, only the following named character escapes are used: \b, \t, \n, \f, \', and \\.
    In JSON mode, \' is replaced by \".
```

--------------------------------

### STON Instance Variable Control

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

Methods that control how instance variables are handled during STON serialization, allowing customization of naming, inclusion, and nil value handling.

```APIDOC
Instance variable serialization control:

#stonName
  - Defines the external name for a class or object in STON.

#stonAllInstVarNames
  - Returns a collection of instance variable names that should be written during serialization.

#stonContainSubObjects
  - A shortcut method to indicate whether the object contains sub-objects that need to be recursively serialized.

#stonShouldWriteNilInstVars
  - An option to skip writing instance variables that have nil values during serialization.
```

--------------------------------

### Data Structure BNF Grammar

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

This snippet defines the complete Backus-Naur Form (BNF) grammar for a custom data structure. It covers the syntax for primitive values (numbers, booleans, strings, symbols), complex structures like objects and lists, references to previous values, and detailed rules for number formats and string escaping.

```BNF
value
  ::= primitive-value
  |   object-value
  |   reference
  |   nil

primitive-value
  ::= number
  |   true
  |   false
  |   symbol
  |   string

object-value
  ::= object
  |   map

object
  ::= classname map
  |   classname list

reference
  ::= @ int-index-previous-object-value

map
  ::= {}
  |   { members }

members
  ::= pair
  |   pair , members

pair
  ::= string : value
  |   symbol : value
  |   number : value

list
  ::= []
  |   [ elements ]

elements
  ::= value 
  |   value , elements

string
  ::= ''
  |   ' chars '

chars
  ::= char
  |   char chars

char
  ::= any-printable-ASCII-character-
    except-'-'"-or-\
  |   '\''
  |   '"'
  |   '\\'
  |   '/'
  |   '\b'
  |   '\f'
  |   '\n'
  |   '\r'
  |   '\t'
  |   '\u' four-hex-digits

symbol
  ::= # chars-limited
  |   # ' chars '

chars-limited
  ::= char-limited
  |   char-limited chars-limited

char-limited
  ::= a-z A-Z 0-9 - _ . /

classname
  ::= uppercase-alpha-char alphanumeric-char

number
  ::= int
  |   int frac
  |   int exp
  |   int frac exp

int
  ::= digit
  |   digit1-9 digits 
  |   - digit
  |   - digit1-9 digits

frac
  ::= . digits

exp
  ::= e digits

digits
  ::= digit
  |   digit digits

e
  ::= e
  |   e+
  |   e-
  |   E
  |   E+
  |   E-
```

--------------------------------

### STON Fraction Format

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Defines the structure for representing rational numbers as fractions. Fractions consist of a numerator and denominator, both of unlimited precision, and should be in their simplest form.

```ston
nominator = positive-integer | negative-integer
denominator = positive-integer
fraction = nominator "/" denominator
```

--------------------------------

### STON URL Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

General RFC URLs are represented as a singleton list containing the URL string. An uppercase tag is used to avoid implementation conflicts.

```STON
URL [ 'https://google.com/search?q=STON' ]
```

--------------------------------

### STON Time Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Simple time values are stored in a singleton list with an ISO-style string format, supporting optional nanoseconds.

```STON
Time [ '20:28:41' ]
```

```STON
Time [ '20:28:41.063687' ]
```

--------------------------------

### STON Primitives

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Lists the basic literal values supported by STON. These are the fundamental data types that can be directly represented.

```ston
primitive = number | string | symbol | boolean | nil
```

--------------------------------

### STON Pretty Printing API

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STON.class/README.md

Provides methods for generating human-readable, indented STON output. This is beneficial for debugging and manual inspection of serialized data.

```APIDOC
STON pretty printing methods:

#toStringPretty: object
  - Serializes the object to a STON string with indentation and multi-line formatting for readability.

#put: object onStreamPretty: stream
  - Writes the object to the stream in a pretty-printed STON format.
```

--------------------------------

### STON Integer Format

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Specifies the syntax for integers, which are whole numbers of unlimited precision. Leading zeros are disallowed, and a plus sign is not permitted for positive integers.

```ston
positive-integer = decimal-digit-non-zero decimal-digit *
negative-integer = "-" positive-integer
integer = "0" | positive-integer | negative-integer
```

--------------------------------

### STON MimeType Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

RFC mime types are represented by a singleton list containing a string, which may include optional properties.

```STON
MimeType [ 'text/plain' ]
```

```STON
MimeType [ 'text/html;charset=utf-8' ]
```

--------------------------------

### STON Writer for JSON Output

Source: https://github.com/svenvc/ston/blob/master/ston-paper.md

The STON writer can generate JSON-compatible output by setting `jsonMode: true` and `prettyPrint: true`. This requires converting Smalltalk collections like Arrays and Dictionaries to a JSON-friendly structure. Non-primitive instances that are not arrays or dictionaries will cause an error in JSON mode.

```Smalltalk
| bounds json |
bounds := World bounds.
json := Dictionary
    with: #origin -> (Dictionary with: #x -> bounds origin x with: #y -> bounds origin y)
    with: #corner -> (Dictionary with: #x -> bounds corner x with: #y -> bounds corner y).
String streamContents: [ :stream |
    (STON writer on: stream)
        prettyPrint: true;
        jsonMode: true;
        referencePolicy: #error;
        nextPut: json ].
```

--------------------------------

### STON DateAndTime Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Timestamp (date and time) objects use a singleton list with an ISO-style string, supporting timezone offsets and optional nanoseconds.

```STON
DateAndTime [ '2018-10-29T20:30:35+00:00' ]
```

```STON
DateAndTime [ '2018-10-29T20:30:35.899433+01:00' ]
```

--------------------------------

### STON Top-Level Structure

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Defines the fundamental building blocks of a STON object graph. STON can represent a single object graph or multiple independent graphs in sequence.

```ston
ston = primitive | list | association | map | object | reference
```

--------------------------------

### STONReader Customization Options

Source: https://github.com/svenvc/ston/blob/master/repository/STON-Core.package/STONReader.class/README.md

STONReader provides several customization options to control its parsing behavior. These options affect how unknown classes are handled, how newline characters within strings are interpreted, and the sequence used for end-of-line markers.

```APIDOC
STONReader Configuration Options:

acceptUnknownClasses <Boolean>
  Default: false
  Description: If true, unknown class names are allowed and mapped to a Dictionary instance using the value of #classNameKey. If false, unknown class names result in a NotFound error.

convertNewLines <Boolean>
  Default: false
  Description: If true, any unescaped EOL sequence (CR, LF, or CRLF) inside strings or symbols is read and converted to the sequence specified by #newLine. If false, these sequences are read unmodified.

newLine <String>
  Default: String cr
  Description: Specifies the EOL sequence to use when convertNewLines is true. The default is the carriage return character (CR).
```

--------------------------------

### STON Date Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Date objects are represented using a singleton list with an ISO-style string format, including an optional timezone offset.

```STON
Date [ '2018-10-29+01:00' ]
```

--------------------------------

### STON Float Format

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Outlines the standard IEEE 754-like representation for floating-point numbers in STON, excluding infinity and NaN. It supports optional fractional and exponent parts.

```ston
float-fraction = "." decimal-digit *
float-ee = "e" | "E"
float-ee-sign = "+" | "-"
float-exponent = float-ee [ float-ee-sign ] positive-integer
float = integer [ float-fraction ] [ float-exponent ]
```

--------------------------------

### STON Number Types

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Details the different formats for representing numbers in STON, including integers, fractions, scaled decimals, and floating-point numbers.

```ston
number = integer | fraction | scaled-decimal | float
```

--------------------------------

### STON Color Representation

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Color objects can be represented either as a map with RGBA float properties or a singleton list with a symbol for a named color.

```STON
Color [ #red ]
```

```STON
Color { #red:1.0, #green:0.0, #blue:0.0, #alpha:0.4 }
```

--------------------------------

### STON Semantic Behavior and JSON Compatibility

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

STON defines semantic behaviors for handling unknown class tags and nil values during writing. It is also backward compatible with JSON, allowing STON readers to process JSON and offering configuration for STON writers to output JSON.

```APIDOC
STON Semantic Behavior:

- Unknown Class Tags: Reading unknown STON class tags can result in a runtime error, or optionally be converted to generic dictionaries with a 'className' property.
- Nil Values: Properties with nil values are typically skipped during writing, assuming they will be re-initialized to nil upon reading. Writers may offer options to include nil properties.
- Class Tag Namespace: Class tags form a global namespace and do not require direct correspondence to implementation classes, allowing for decoupling.
- Whitespace: Whitespace is permitted between syntactic elements for pretty-printing.

STON JSON Compatibility:

- STON readers accept JSON: Double quotes for strings/symbols, 'null' for nil.
- STON writers can output JSON:
  - Strings delimited by double quotes.
  - 'null' instead of nil.
  - Fractions/Scaled Decimals written as floats.
  - Symbols written as strings.
  - Only Arrays and Dictionaries allowed as composites.
  - Shared references are doubled.
  - Circular references raise an error.
```

--------------------------------

### STON Character Classes Specification

Source: https://github.com/svenvc/ston/blob/master/ston-spec.md

Defines character classes used in the formal syntax of STON. These include definitions for lowercase letters, uppercase letters, decimal digits, hexadecimal digits, and various whitespace and control characters.

```APIDOC
lowercase-letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
uppercase-letter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
decimal-digit-non-zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
decimal-digit = "0" | decimal-digit-non-zero
hex-digit = decimal-digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"

whitespace = sp | ht | cr | lf | ff
sp = "\u0020" <space>
ht = "\u0009" <horizontal tab>
cr = "\u000D" <carriage return>
lf = "\u000A" <line feed>
ff = "\u000C" <form feed>
bs = "\u0008" <backspace>
ascii-control-char = "\u0000" | .. | "\u001F" | "\u007F"
ascii-char = "\u0000" | .. | "\u007F"
printable-ascii-char = "\u0020" | .. | "\u7E"
unicode-char = <any Unicode character>
```
Tokens:
Raw