### 4.1 Scheme tutorial

LilyPond uses the Scheme programming language, both as part of the input syntax, and as internal mechanism to glue together modules of the program. This section is a very brief overview of entering data in Scheme.1

The most basic thing of a language is data: numbers, character strings, lists, etc. Here is a list of data types that are relevant to LilyPond input.

Booleans
  Boolean values are True or False. The Scheme for True is `#t` and False is `#f`.
Numbers
  Numbers are entered in the standard fashion, `1` is the (integer) number one, while `-1.5` is a floating point number (a non-integer number).
Strings
  Strings are enclosed in double quotes,

                    "this is a string"

  Strings may span several lines

                    "this
                    is
                    a string"

  Quotation marks and newlines can also be added with so-called escape sequences. The string `a said "b"` is entered as

                    "a said \"b\""

  Newlines and backslashes are escaped with `\n` and `\\` respectively.

In a music file, snippets of Scheme code are introduced with the hash mark `#`. So, the previous examples translated in LilyPond are

           ##t ##f
           #1 #-1.5
           #"this is a string"
           #"this
           is
           a string"

For the rest of this section, we will assume that the data is entered in a music file, so we add `#`s everywhere.

Scheme can be used to do calculations. It uses prefix syntax. Adding 1 and 2 is written as `(+ 1 2)` rather than the traditional 1+2.

           #(+ 1 2)
            => #3

The arrow => shows that the result of evaluating `(+ 1 2)` is `3`. Calculations may be nested; the result of a function may be used for another calculation.

           #(+ 1 (* 3 4))
            => #(+ 1 12)
            => #13

These calculations are examples of evaluations; an expression like `(* 3 4)` is replaced by its value `12`. A similar thing happens with variables. After defining a variable

           twelve = #12

variables can also be used in expressions, here

           twentyFour = #(* 2 twelve)

the number 24 is stored in the variable `twentyFour`.

The name of a variable is also an expression, similar to a number or a string. It is entered as

           #'twentyFour

The quote mark `'` prevents Scheme interpreter from substituting `24` for the `twentyFour`. Instead, we get the name `twentyFour`.

This syntax will be used very frequently, since many of the layout tweaks involve assigning (Scheme) values to internal variables, for example

           \override Stem #'thickness = #2.6

This instruction adjusts the appearance of stems. The value `2.6` is put into a the `thickness` variable of a `Stem` object. This makes stems almost twice as thick as their normal size. To distinguish between variables defined in input files (like `twentyFour` in the example above), and internal variables, we will call the latter “properties.” So, the stem object has a `thickness` property.

Two-dimensional offsets (X and Y coordinates) as well as object sizes (intervals with a left and right point) are entered as `pairs`. A pair2 is entered as `(first . second)` and, like symbols, they must be quoted,

           \override TextScript #'extra-offset = #'(1 . 2)

This assigns the pair (1, 2) to `extra-offset` variable of the TextScript object. This moves the object 1 staff space to the right, and 2 spaces up.

The two elements of a pair may be arbitrary values, for example

           #'(1 . 2)
           #'(#t . #f)
           #'("blah-blah" . 3.14159265)

A list is entered by enclosing its elements in parentheses, and adding a quote. For example,

           #'(1 2 3)
           #'(1 2 "string" #f)

We have been using lists all along. A calculation, like `(+ 1 2)` is also a list (containing the symbol `+` and the numbers 1 and 2). Normally lists are interpreted as calculations, and the Scheme interpreter substitutes the outcome of the calculation. To enter a list, we stop evaluation. This is done by quoting the list with a quote `'` symbol. For calculations, do not use a quote.

Inside a quoted list or pair, there is no need to quote anymore. The following is a pair of symbols, a list of symbols and a list of lists respectively,

           #'(stem . head)
           #'(staff clef key-signature)
           #'((1) (2))

#### Footnotes

[1] If you want to know more about Scheme, see http://www.schemers.org.

[2] In Scheme terminology, the pair is called `cons`, and its two elements are called car and cdr respectively.

Read comments on this page, or add one. This page is for LilyPond-2.2.5 (stable-branch).