Loon - Simple data-serialisation file format based on S-expressions

; ### a self-explanatory Loon sample file ###

; - Loon is a data serialisation file format based on S-expressions
; - Loon is designed to be easy for both people and machines to read
; - Loon files are required to be UTF-8 encoded and may have a UTF-8 BOM

; this is a comment - it starts with a semicolon and ends at the line end

; a Loon file contains a single value; in this sample that value is a dict
; structure, which itself may contain many values
(dict
    ; a dict is an unordered list of zero or more key/value pairs enclosed
    ; between (dict and ) tokens;  the key is always a string enclosed
    ; in double quotes and must be unique in the dict
    "key" "value"

    ; the value must be one of these three simple types, or a nested
    ; arry or dict structure or null
    "a number" 1234
    "a boolean" false
    "a string" "any Unicode text except backslash and double quote"
    "a nothing (has no type or value)" null

    ; an arry is an ordered list of zero or more values enclosed between
    ; (arry and ) tokens; the values do not have to be of the same type
    "heterogeneous array" (arry "the" 1 true "brace style")

    "an array of arrays" (arry
        (arry 1 0 0)
        (arry 0 1 0)
        (arry 0 0 1)
    )

    "books" (arry
        (dict
            "name" "Green Eggs and Ham"
            "author" "Dr. Seuss")
        (dict
            "name" "Gödel, Escher, Bach"
            "author" "Douglas Hofstadter")
    )

    "an empty arry" (arry)
    "an empty dict" (dict)
    
    ; white space is needed only where necessary to separate symbols that
    ; would otherwise merge and for human readability
    ; these three key/value pairs have the minimum necessary white space
"one two"(arry 1 2)"twelve"(arry 12)"three"3

    ; bad Loon: examples of ill-formed expressions
    ; (dict "key" 0 "key" 1) - keys not unique
    ; (dict "key")           - missing value
    ; (dict 0 "zero")        - key not a string
    ; (dict "key" hat)       - hat is not a valid Loon value
    ; (dict "key" arry)      - arry doesn't make sense in this context

    ; --- and that's all there is to a Loon file ---

    "Loon" (arry
        "a foolish fellow?"
        "List Oriented Object Notation?"
        "JSON done with S-expressions?")
)

loon-file: value
value: string
number
dictionary
array
true
false
null
dictionary: ( dict )
( dict pairs )
pairs: pair
pair pairs
pair: key value
key: string
array: ( arry )
( arry values )
values: value
value values

string: ""
" chars "
chars: char
char chars
char: any-Unicode-character-
except-"-or-\-or-
control-character
\"
\\
\/
\b
\f
\n
\r
\t
\u four-hex-digits
number: decimal
+ decimal
- decimal
hex

decimal: int
int .
int . frac
int exp
int . exp
int . frac exp
. frac
. frac exp
int: digits
frac: digits
exp: e digits
e + digits
e - digits
e: e
E
digits: digit
digit digits
digit: 0-9
hex: 0x hex-digits
0X hex-digits
hex-digits: hex-digit
hex-digit hex-digits
hex-digit: 0-9a-fA-F

white space - Outside a string white space is required only to separate tokens that would otherwise merge together, otherwise it is ignored. White space characters are {space U+0020} and {all ASCII control characters: U+0000-U+001F + U+007F}.

comments - A comment starts with a semicolon { ; U+003B} and continues to the end of the line. Comments do not occur within a string. A comment is equivalent to a single space character.

line splicing - A line that ends with a backslash { \ U+005C} is spliced onto the following line. Line splicing is done before division into tokens.

newline - The end of a line is signalled by any of these: {CR}, {LF}, {VT}, {FF} or {CR}{LF}.

Loon — Simple data-serialisation file format based on S-expressions

What is it for?

Loon can be used for data-interchange, persisting program state and program configuration.

It looks like JSON done with S-expressions?

Yes. Same idea, different syntax. Conversion between JSON and Loon data representations is straight-forward, if not trivial.

Why would I use Loon rather than JSON or XML?

If you need to exchange data with a system that supports one of these excellent data formats then of course you should use that format. But if you are independent of other systems and just need to serialise data in a simple, readable and rather elegant way then S-expressions in general, and Loon in particular, may be just what you need.

Is that all you’ve got: “it’s elegant?”

Yes. Pretty much. Loon is as lightweight as JSON but has simpler punctuation, which makes it easier on the eye. Loon is based on S-expressions, which are awesome and, yes, elegant (“pleasingly ingenious and simple”).

There are some things Loon allows that JSON doesn't. For example, Loon allows hexadecimal integers, comments and line splicing (so long lines may by broken up to make them more readable).

Where are the sample Loon parsers?

Is it LOON, Loon or loon?

Since the project takes its inspiration from JSON and LISP and the name is an acronym of List Orientated Object Notation it should really be LOON. But that looks a bit shouty, so let’s just agree to write Loon, or loon.

Also, Loon files might be more readily identifiable if they had a .loon suffix. (But of course, that's up to you.)

; a Loon dictionary containing one entry called Image

(dict
    "Image" (dict
        "Width"  800
        "Height" 600
        "Title"  "View from 15th Floor"
        "Thumbnail" (dict
            "Url"    "http://www.example.com/image/481989943"
            "Width"  125
            "Height" 100
        )
        "IDs" (arry 116 943 234 38793)
    )
)

; the value of the Image key is a dictionary whose Thumbnail key is another
; dictionary and whose IDs key is an array of numbers

; a Loon array containing two dictionaries

(arry
    (dict
        "Latitude"   51.427959
        "Longitude"  -1.8569018
        "Address"    "Avebury"
        "City"       ""
        "County"     "Wiltshire"
        "Post Code"  "SN8 1RF"
        "Country"    "GB"
    )
    (dict
        "Latitude"   51.176197
        "Longitude"  -1.8377299
        "Address"    "Stonehenge"
        "City"       ""
        "County"     "Wiltshire"
        "Post Code"  "SP4 7DE"
        "Country"    "GB"
    )
)