Learn Confetti

Confetti is a minimalistic configuration language designed for humans. It blends 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#

Confetti files consist of zero or more directives. You can think of a directive as a command or configuration setting that is interpreted by a program. The following is an example of a single directive:

ports 582 583

Every directive consists of one or more arguments. Arguments must be separated by at least one whitespace character. In the previous example, the directive has three arguments: ports, 582, and 583.

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

login jsmith
password hunter2

Directives can also be terminated by a semicolon. This following snippet is equivalent to the previous example, except it uses a semicolon instead of a newline to separate the directives. Whitespace around the semicolon is insignificant, although this example adds it for clarity.

login jsmith ; password hunter2

Arguments#

An argument is a sequence of one or more printable Unicode characters. Confetti arguments are typeless. Although they might resemble identifiers, strings, or numbers as you’re likely used to in various programming languages, they are all interpreted as typeless strings by Confetti. It is up to a software program to assign them meaning.

Quoted Arguments#

Arguments are separated by whitespace. However, you can define an argument with whitespace by enclosing it in quotation marks. This is demonstrated in the following snippet, which defines a single 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#

Directives terminate when a newline is found. However, you might want to define a directive with newline characters.

You can define a multi-line argument by enclosing it in triple quotation marks. The enclosing triple quotation marks are not part of the argument’s value.

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 snippet escapes two quotation mark characters in a quoted argument. Here, the directive consists of 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#

Directives and single quoted arguments can be continued onto the next line by ending the line with a backslash. Conceptually, Confetti will “remove” the backslash and newline from the result.

You can escape a newline character by writing a backslash in front of them. 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

Escaping directives is most useful for really long directives. If you need to preserve the newline characters, then use triple quotes.

Subdirectives#

Confetti supports hierarchical directives known as subdirectives. Conceptually, subdirectives can be thought of as children of a parent directive. Subdirectives are especially useful for grouping related concepts.

Subdirectives are enclosed in curly braces. The opening curly brace must be written after the directive that is intended to be 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 first directive, which consists of the arguments user and John Smith Jr, has subdirectives. These subdirectives begin with login, password, and proxy. The proxy subdirective has its own subdirective starting with the argument ports.

Comments#

Confetti comments begin with a # character and extend until the next line terminator. They can be written on their own line or after the end of a directive.

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

Comments cannot appear inside a quoted or triple quoted argument. In a quoted context, the # character is interpreted as part of the argument and not the beginning of a comment. The # character can appear in an unquoted argument by escaping it with a preceding backslash character.

File Extension#

Officially, the file extension for a Confetti file is .conf or .cfg. However, application authors are free to choose a custom extension or drop the extension entirely.