Scheme tutorial - GNU LilyPond
Description: GNU LilyPond

Next: Notation manual tables, Previous: Literature list, Up: Top

## Appendix B Scheme tutorial

LilyPond uses the Scheme programming language, both as part of the input syntax, and as internal mechanism to glue modules of the program together. 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 same assignment can be done in completely in Scheme as well,

    #(define twentyFour (* 2 twelve)

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 the 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 the `thickness` variable of a `Stem` object. `thickness` is measured relative to the thickness of staff lines, so these stem lines will be `2.6` times the width of staff lines. 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 variables of internal objects, we will call the latter “properties” and the former “identifiers.” So, the stem object has a `thickness` property, while `twentyFour` is an identifier.

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 the `extra-offset` property of the TextScript object. These numbers are measured in staff-spaces, so this command 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 the evaluation. This is done by quoting the list with a quote `'` symbol. So, 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.

This page is for LilyPond-2.8.8 (stable-branch).

Other languages: English.
Using automatic language selection.