File Structure

SUCC files are parsed as a list of lines. Some lines contain data, and some lines do not.

Spec

• SUCC files can be encoded in either UTF-8 or UTF-32
• newlines in both Windows and Unix format are accepted

Non-Data Lines

If a line contains no characters, only spaces, or if the first non-space character is the comment indicator #, the line contains no data and is ignored by the data parser. Non-data lines are preserved when the file is modified, however. Take the following example:

# TODO: investigate the possibility of funnier numbers

Funny Number: 69

DontChangeThis: false

If SUCC modifies the value of DontChangeThis, that is the only line that changes. The one comment line and the two whitespace lines stay where they are.

Data Lines

Key Lines

Key lines represent data indexed by name. A key line contains a key part and a value part. These are separated by the character :.

All spaces surrounding the : character are ignored. All spaces at the beginning and end of the line are ignored.

Keys must conform to the following rules:

• a key must contain at least one character
• a key may not begin with the character -
• a key may not contain the character : (used for key/value separations)
• a key may not contain the character # (used for comments)
• a key cannot contain any newline characters
• a key may not start or end with a space

List Lines

List lines represent data indexed by number or unordered data with no indexing. A list line's first non-space character is -. Excluding any spaces between - and the next non-space character and any trailing spaces, the rest of the line is the value.

Multi-Line Strings

Strings can be represented over multiple lines, like so:

Sonnet LXV: """
    Matilde, where are you? Down here I noticed,
    under my necktie and just above my heart,
    a certain pang of grief between the ribs,
    you were gone that quickly.
    """

Multi-line strings are a special case and don't fit into the rules for the rest of SUCC files. Fore more details on their specific implementation, see Base Types#String.

Data Line Comments

If a data line contains the comment indicator #, that character and everything after it is ignored -- unless the # is immediately preceded by a \. The sequence \#, known as a "comment escape", is parsed as just the character #.

string1: hello # this is a comment
string2: hello \# this is still part of the string # THIS is a comment

When parsed, string1 will have the value hello, and string2 will have the value hello # this is still part of the string.

Note that \ does not escape any other control characters, including itself. For example, to encode the string \#, you use \\#.

Nesting

Nesting is a core part of SUCC, and the reason it can represent such a wide variety of data. Nesting means that a data line can have child data lines. Here's are the rules for nesting:

• if a data line has a higher indentation level (number of leading spaces) than the one above it, it is a child of the one above it
• all of the children of a given data line must have the same indentation level
• a data line cannot have children if it has a value (the exception to this is the string special case)
• all of the children of a given data line must be the same type
• if the type of children is key lines, all the keys must be unique

# This is fine
List of Numbers:
    - 1
    - 2
    - 69

# This is NOT fine (children have different indentation levels)
List of Numbers:
    - 1
  - 2
     - 69

# This is NOT fine (List of Numbers has children even though the line has a value)
List of Numbers: list
    - 1
    - 2
    - 69

# This is NOT fine (different types of child lines)
List of Numbers:
    item: 1
    - 2
    - 3

Structure

A SUCC file contains only the following:

• non-data lines
• top-level key lines - key lines with an indentation of 0
• the children/grandchildren/ect of the top-level key lines

SUCC will read, modify, add and remove data lines of a given file without disturbing the non-data content.