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. If you want to know more about Scheme, see http://www.schemers.org.

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 pair¹ 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))