Inident syntax

Inident is an intuitive, human readable, hierarchical configuration syntax based on a subset of YAML. Inident is used extensively by the site for plugin configurtion, metadata, and shortcode configuration purposes (notably for gn:contact and gn:library).

Many of the examples on this page show an Inident document followed by the equivalent JSON representation of the same document, as this provides an unambiguous syntax which can be used to verify your understanding. In some cases where the JSON representation would be unnecessary or overly complex, it has been omitted.

Inident has exactly two data types: strings and documents. Unlike YAML, Inident performs no automatic/surprise type inferral, which is the responsibility of the configuration consumer. Inident is also less stringent than YAML, and is generally willing to discard malformed data appearing in a document.

Mappings and verbatim strings

Like YAML, the Inident syntax is best described as an indentation-based hierarchy of mappings associating values to named or numbered keys.

The most common method of specifying both keys and values is verbatim string syntax.

Simply put, a verbatim string consists of all of the characters on a line, as they appear on the line, less any whitespace at the start and end of the line. As such verbatim strings are great for expressing both tokens (single words) and sentences as long as they fit on a single line.

One additional rule applies when expressing a mapping key as a verbatim string: the key ends at the first colon (:) character followed by at least one space or tab character. This convention allows you to express file path and URL keys as verbatim strings:

Indentation

Declaring a key without specifying a value on the same line creates a sub-document. From that point on, all mappings having a level of indentation greater than that of the key are a part of the document assigned to that key.

This gives you only one space worth of fudge factor when managing your indents - but generally this works suprisingly well. As long as it looks right, it probably is right.

A key must be "open", with no declared value, in order to associate subsequent indented lines. A mapping always belongs to the earliest preceding open key at a lower level of indentation. In the following example, c is associated with a because b is not open:

Quoted strings

Inident also supports a quoted string syntax which is nearly identical to JSON strings, and can be used for both keys and values. Quoted strings are enclosed in double (") or single (') quotes, and cannot span multiple lines.

A quoted string is necessary in the event that you need to retain whitespace characters at the beginning or end of a line, or you need to specify a key containing a colon followed by whitespace.

Any trailing garbage at the end of a line will cause a value resembling a quoted string to handled as an unquoted one.

Escape sequences

One notable advantage to quoted strings is that they support JSON-like escape sequences which can take several forms:

• single character escape sequences as seen in JSON and just about every programming language in existance (\b, \t, \n, \f and \r)
• literal escape sequences (e.g. \\ to produce a literal backslash)
• named escape sequences of the form \{name}, where name is a valid HTML5 entity name
• UTF-16 escape sequences of the form \uXXXX
• UTF-32 escape sequences of the form \UXXXXXXXX
• delimited unicode escape sequences specified by up to 8 hexadecimal digits of the form \u{XXXXXXXX} or \U{XXXXXXXX}

Escape sequences are only supported in quoted strings. Elsewhere characters must be expressed verbatim in the encoding of the document.

Comments

Any line within an Inident document beginning with whitespace followed by a # character is a comment, and is ignored entirely during processing. Comments can appear at any point in an Inident document; but will be processed as part of a line's content unless they are on their own line.

Note that comments only apply inside of an Inident document! If you attempt to use this comment syntax outside of a shortcode accepting an Inident document, your comment will most likely display on the page!

Folded and unfolded strings

When you want to deal with longer values, folded and unfolded string syntax allows you to specify a string value spanning multiple lines. Such strings are created by placing an > or | character following a mapping key. All lines following the mapping at a greater level of indentation are then treated as a part of the string value.

An unfolded string follows a | marker, and continues until a line at a higher level of indentation is encountered. Whitespace characters at the beginning and end of lines are discarded, but line breaks are preserved as they appear in the input.

Folded strings follow a > marker and behave identically save that the resulting value is folded into single-line "paragraphs" by collapsing whitespace between adjacent lines to a space character.

Folded and unfolded strings can also contain comments at any point provided that they appear on their own line.

As the only requirement for inclusion in such a string is the level of indentation, this syntax makes it easy to embed other syntaxes within an Inident document (particularly if the embedded syntax is not whitespace sensitive):

Even in the case of whitespace-sensitive syntaxes, a colon character can be used to specify a margin at the start of a line, causing whitespace to be retained at the beginning and end of the line.

Note that a single space is discarded following the margin character so that the margined content does not need to directly abut the margin and remains visually pleasing.

Margins are supported by both folded and unfolded strings; however these are purely decorative in the case of a folded string as the folding behavior will collapse whitespace between lines to a single space.

Lists

Inident supports a special form of mapping that makes it easy to create lists of values by automatically assigning to the next available integer key.

List mappings can be mixed freely with key-value mappings, and you can even create lists of lists:

Note that the next available integer key is not the same as the lowest available key in the event that some numbers have been skipped: