Friendly File Format

Introduction

FFF or Friendly File Format is a simple data serialization language. It allows any kind of data to be expressed using a simple, human readable (hence friendly) syntax. This makes FFF an excellent choice for a configuration file format.

Example

Below is an example of a simple configuration file in Friendly File Format:

# Example of FFF syntax

name "Jane Doe"

account {
    protocol imaps
    host "mail.example.com"
    port 993
}

The example illustrates the major syntactic features of FFF. In order of appearance:

• Comments are introduced by a hash mark (#) and run until the end of the line.
• Usually (although this is not a requirement), FFF files consist of a number of directives, each starting with a symbol followed by zero or more arguments.
• Symbols typically consist of lowercase letters, sometimes separated by underscores or dashes. For the full syntax of symbols, see the specification.
• Strings are text enclosed in double quotes. For the full syntax of strings, see the specification.
• A number of directives can be grouped together by enclosing them in curly braces.
• Numeric values can be entered by simply writing out the number. For the full syntax of numbers, see the specification.

Specification

Comments

A comment is introduced by a hash mark (#) and runs until the end of the line. Hash marks inside double quotes or inside escape sequences do not introduce comments.

Symbols

A symbol is a sequence of one or more characters. Any character can be included in a symbol by means of an escape sequence. Letters, underscores (_) and dashes (-) can and should be represented unescaped, and the same is true for digits that aren't the first character in a symbol.

Some examples of valid symbols are:

x
xyz
user_agent
domain-name
url2
with\ space

Strings

A string is a sequence of zero or more characters, surrounded by double quotes ("). Any character may be included a string by using escape sequences, but characters other than double quote (") and backslash (\) may also appear unescaped.

Some examples of valid strings are:

""
"foo"
"with \"quotes\""

Numbers

A number consists of an optional sign (+ or -), one or more digits, possibly separated by underscores, and may contain a decimal point followed by more digits possibly separated by underscores.

Examples of valid numbers include:

0
12
4_294_967_296
2.5
-5

Escape Sequences

Escape sequences can be used to encode characters that would otherwise have special meaning. For example, escape sequences can be used to encode spaces in symbols, or double quotes in strings. The following escape sequences are defined:

\  (backslash space)

A space character (U+0020)

\"

A double quote character (U+0022)

\\

A backslash character (U+005C)

\n

A linefeed character (U+000A)

\r

A carriage-return character (U+000D)

\xxx (backslash, x, two hexadecimal digits)

The byte with value xx

\uxxxx (backslash, lowercase u, four hexadecimal digits)

The Unicode character with code point U+xxxx

\Uxxxxxxxx (backslash, capital U, eight hexadecimal digits)

The Unicode character with code point U+xxxxxxxx

Additionally, the sequence backslash, newline followed by zero or more spaces may be used as a line continuation sequence. For example:

# Same as: foobar
foo\
bar

# Same as: foobar
foo\
   bar

# Same as: "Hello, world!"
"Hello, \
 world!"

# Same as: "Hello, world!"
"Hello,\
\ world"