Learn Confetti

Confetti is a minimalistic configuration language designed for humans. It combines the readability of Unix configuration files with the flexibility of S-expressions. By reading this guide, you can learn Confetti in just a few minutes!

Directives#

A Confetti configuration file consists of zero or more directives. You can think of a directive as a statement that is interpreted by the program processing the file. Here’s an example of a single directive:

ports 582 583

A directive consists of one or more arguments, separated by one or more whitespace characters. In the example above, the directive has three arguments: ports, 582, and 583.

Assigning semantic meaning to the arguments is up to you. For example, the first argument could be interpreted as a name, command, or key, and the remaining arguments its de facto arguments or values.

Terminating Directives#

Directives are terminated by a newline character. The following example defines two directives: the first with arguments login and jsmith, and the second with arguments password and hunter2.

login jsmith
password hunter2

Directives can also be terminated by a semicolon. The following snippet is equivalent to the previous snippet, except it uses a semicolon instead of a newline to separate the directives. Whitespace around the semicolon is ignored, though it’s added here for clarity.

login jsmith ; password hunter2

Arguments#

An argument is a sequence of one or more printable Unicode characters.

Arguments are typeless. While they may resemble identifiers, strings, or numbers — as commonly seen in various programming languages — they are all interpreted as typeless strings by Confetti.

Quoted Arguments#

Arguments are separated by whitespace. To define an argument that includes whitespace, enclose it in quotation marks.

This example defines a directive with two arguments: user and John Smith Jr. Note that the enclosing quotes are not part of the argument’s value.

user "John Smith Jr"

Multi-line Arguments#

To define a multi-line argument, enclose it in triple quotation marks. While the enclosing quotes are not part of the value, the newline characters inside are preserved.

The following directive has two arguments: user and The quick brown fox\njumps over the\nlazy dog. Here, the \n sequence indicates where the newline characters are.

user """The quick brown fox
jumps over the
lazy dog"""

Escaping Characters#

Any printable character can be escaped by writing a backslash in front of it. Most characters do not need to be escaped, but special characters do. For example, semicolons and quotation marks have special meaning in Confetti, and so they must be escaped if they are to be interpreted as part of an argument.

The following example escapes two quotation mark characters in a quoted argument. Here, the directive has two arguments: message and Say "Hi" to the guests.

message "Say \"Hi\" to the guests"

Escaping applies to any argument, not just quoted arguments. The following snippet defines one directive with two arguments: items and sword;shield. Notice how the semicolon didn’t terminate the directive because it is escaped!

items sword\;shield

Line Continuation#

To continue a directive on the next line, end the line with a backslash (\). The backslash and the newline are conceptually removed during parsing.

For example, the following snippet:

set $greeting "Hello, \
World!"
send_mail \
$greeting

will be interpreted by Confetti as:

set $greeting "Hello, World!"
send_mail $greeting

Line continuations are most useful for directives with many arguments. For really long arguments and for when newlines should be preserved, use triple quotes.

Subdirective Blocks#

Confetti supports hierarchical directives known as subdirectives. Subdirectives are enclosed in curly braces and are children of the parent directive.

The opening curly brace must appear after the parent directive, either on the same line or a subsequent line. The following example writes them on the same line for compactness.

user "John Smith Jr" {
    login jsmith
    password hunter2
    proxy {
        ports 582 583 584
    }
}

In the example, the directive user has subdirectives login, password, and proxy. The proxy subdirective has its own subdirective ports.

Subdirectives can be arbitrarily deep, unless an implementation imposes a limit.

Comments#

Confetti comments begin with a # character and continue until the end of the line.

# This is a comment.
login jsmith  # This is another comment.

In a quoted or multi-line argument, the # character is interpreted as part of the argument. The character can also appear in an unquoted argument by escaping it with a preceding backslash character.

Comments cannot appear after a line continuation backslash, as that would break continuation.

File Extension#

The recommended file extension for a Confetti file is .conf or .cfg. However, you’re free to choose a custom extension or drop the extension entirely.