SSYN Model and Syntax Specification

Elements are made up of up to four components:

Names are sequences of valid (except NUL) Unicode characters.

Values are sequences of valid (except NUL) Unicode characters.

Child elements are elements with parent elements. Child elements with the same parent element will be referred to as sibling elements. Child elements and their child elements, etc, are referred to as descendant elements to the element that’s the parent of the first set of child elements. Parent elements and their parent elements, etc, are referred to as ancestor elements.

The parent/child relationship in the SSYN model allows for arbitrary tree-like structures of elements to be constructed by document authors. Child elements in the model should be accessible via parent elements.

Parent elements act as “containers” for child elements. Parent elements in the model should be accessible via child elements. Elements without parents are considered “top-level” elements.

As previously stated, the SSYN model is unique and can most likely not be supported natively by most programming languages as they exist today. This does not mean that SSYN is inappropriate for modelling the data structures of these languages. In fact, the SSYN model can be considered a superset of most other models.

For example, to represent the data structures sometimes referred to as arrays, lists, or vectors, SSYN can use an element with multiple unnamed child elements.

a list:
  : item1
  : item2
  : item3
  : item4

To represent the data structures sometimes referred to as associative arrays, dictionaries, maps, or hash tables, SSYN can use an element with multiple named child elements.

a dict:
  key1: value1
  key2: value2

The simplicity of the SSYN model allows one to combine these structures to create new ones.

a list of lists:
  :
    : item1
    : item2
  :
    : item3
    : item4

a dict of dicts:
  key1:
    key2: value1
    key3: value2
  key4:
    key5: value3
    key6: value4

a list of dicts:
  :
    key1: value1
    key2: value2
  :
    key3: value3
    key4: value4

a dict of lists:
  key1:
    : item1
    : item2
  key2:
    : item3
    : item4

All conformant SSYN parsers MUST be able to process documents using the UTF-8, UTF-16, or UTF-32 encodings of Unicode 4.0.

SSYN documents encoded in UTF-16 or UTF-32 MUST begin with a Byte Order Mark. Documents encoded in UTF-8 MAY begin with a Byte Order Mark. The Byte Order Mark is used only to detect the encoding of the document and is not considered part of the document content.

The following table details the bytes that make up the Byte Order Marks for the different encodings.

The absence of a Byte Order Mark indicates the document is encoded in UTF-8.

TODO: Introduce the special !SSYN directive that can be used to declare what encoding a document uses if the encoding is not a UTF encoding.

Names must be serialized on a single line and are terminated with a literal colon, an end-of-line character, or the end of input. Terminating a name with a literal colon is used to separate an element’s name from its value.

All three of the elements depicted in the following example have a name of “name”.

name
name:
name: value

Names in the model are defined as being a sequence of Unicode characters but, because of their role in terminating a name, colons and end-of-line characters in names must be escaped in order to be serialized.

The element depicted in the following example has a name of “na:me”.

na|:me: value

The element depicted in the following example has a name of “na$me” where “$” is a placeholder for the line feed character.

na|LF!me: value

Names that begin with the “!” character indicate that the element is to be considered a directive. Names that begin with the “#” character indicate that the element is to be considered a comment. Given that, “!” and “#” characters must be escaped if a document author wishes a “normal” element name to begin with a “!” or “#”.

The elements depicted in the following example are not directives or comments.

|!name: value
|#name: value

See Escaping Characters section for more information on the syntax of escaping characters.

As defined in the model, names are an optional component of elements.

The element depicted in the following example has no name but does have a value.

: value

Note that space characters appearing immediately before any non-space characters on a line are only used for determining the depth of the element and are not considered part of the element’s name. To include leading spaces in a name, the spaces must be escaped.

There’s only one type of value in the model but there’s two different ways of encoding values in the syntax.

The simple value syntax is indicated with one literal colon and terminated with an end-of-line character or end of input in the syntax but does not include any terminating end-of-line character in the model.

Simple values will typically be serialized on the same line as the name of an element and will be terminated by the end-of-line character on that same line.

The element depicted in the following example has a value of “value”.

name: value

Simple values can extend across the line the separator appears on if a line continuation character is used.

The element depicted in the following example has a value of “value”.

name: val|
      ue

Since simple values are normally terminated with end-of-line characters, such characters must be escaped in order to be included in the actual value. Unlike names, however, colons do not need to be escaped.

The element depicted in the following example has a value of “val:ue$” where “$” is a placeholder for the line feed character.

name: val:ue|LF!

Note that space characters appearing immediately after a literal colon character but before any non-space characters are not considered part of the element’s value. To include leading spaces in a value, the spaces must be escaped.

Block values enable serializing actual values containing end-of-line characters without having to escape those end-of-line characters.

Block values are indicated by using two literal colons instead of the one literal colon used to indicate simple values.

Block values can span multiple lines without the use of the line continuation character. Each line in a block value must be indented by a number of space characters equal to the number of characters on the line leading up to the first non-space character in the block value.

Block values are terminated by a line with a fewer number of leading space characters than the number of space characters used to indent the first line containing non-space characters in the block value or the end of input.

End-of-line characters in the block value are included in the actual value unless a line continuation character is used.

The element depicted in the following example has a value of “value$” where “$” is a placeholder for the end-of-line character.

name:: value

The element depicted in the following example has a value of “line1$line2$” where “$” is a placeholder for the end-of-line character.

name:: line1
       line2

Care must be taken by document authors to ensure that subsequent lines in a block value are properly indented.

The element depicted in the following example has a value of “value$” where “$” is a placeholder for the end-of-line character. The line containing the string “name2” must be interpreted by conforming parsers as a child element with a name of “name2” and no value.

name1:: value
  name2

Block values can begin on a line after the line the block value indicator appears on. All space and end-of-line characters leading up to the first non-space character are not included in the actual value.

The element depicted in the following example also has a value of “line1$line2$” where “$” is a placeholder for the end-of-line character.

name::
  line1
  line2

Note that, like simple values, leading space characters in a block value are not considered part of the element’s value so care must be taken to insure that any leading space characters are properly escaped.

The element depicted in the following example has a value of “__line1$line2$” where “_” is a placeholder for the space character and “$” is a placeholder for the end-of-line character.

name::
  |  line1
  line2

Child elements are indicated by indenting an element a number of space characters greater than the number of space characters used to indent the parent element.

Elements indented with the same number of space characters are considered siblings to each other and children of the nearest parent element previously appearing in the document indented with a lesser number of space characters.

The element depicted in the following example has two child elements with names of “name2” and “name3”.

name1
  name2
  name3

Elements with child elements can, as defined in the model, also have a value.

The element depicted in the following example has a value of “value” and two child elements with names of “name2” and “name3”.

name1: value
  name2
  name3

Care must be taken by document authors when an element has both a block value and child elements.

The element depicted in the following example has a value of “line1$line2$” where “$” is a placeholder for the end-of-line character and one child element with a name of “name2”.

name1:: line1
        line2
  name2

Literal space characters on a line appearing before any non-space characters are only used for determining the indentation level of an element or value. To include leading spaces in a name or value, the spaces must be escaped.

The elements depicted in the following example have names of “_name” and values of “_value” where “_” is a placeholder for the space character.

| name: | value
  | name: | value

Describe the directive syntax here.

Mention the special !SSYN directive.

Describe the comment syntax here.

There are three different ways to escape characters. All three use the pipe character as the escape character. The pipe character was chosen because it occurs much less frequently in typical text than the world’s most popular escape character: the backslash. This makes it possible to have names and values in the model that refer to file paths (on systems that use backslashes as the path separator) or regular expressions.

Simple escaping is done by preceding what a SSYN parser would normally consider a special character with a pipe character. There are four special characters in SSYN: pipe (|), colon (:), bang (!), and hash (#).

Pipe characters must always be escaped. Colon characters only need be escaped when appearing in a name but are allowed to be escaped in values. Bang and hash characters only need to be escaped when appearing as the first character in a name but are allowed to be escaped elsewhere.

Another form of simple escaping is escaping space characters which is done by prefixing them with a pipe character. This is normally only required when a name or value needs to begin with leading space characters.

Named escaping is done by preceding a name with a pipe and terminating that name with a bang. The names that can be used in this manner and their substitution values appear in the following table.

TODO: Should we include HTML4 entities? Should we include other “control”-like characters from Unicode?

Numeric escaping is done by preceding a sequence of hexadecimal digits with a pipe and terminating those digits with a hash. The replacement character for numeric escapes is the Unicode character with the code point indicated by the hexadecimal digits in the escape. Any valid Unicode character (except NUL) can be referenced in this manner.