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.
#t
and False is #f
.
1
is the (integer) number one, while -1.5
is a
floating point number (a non-integer number).
"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))
[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). |