Next: , Up: Changing defaults



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.6 (stable-branch).

Report errors to <bug-lilypond@gnu.org>.