4 @appendix Scheme tutorial
9 @cindex Scheme, in-line code
10 @cindex accessing Scheme
11 @cindex evaluating Scheme
14 LilyPond uses the Scheme programming language, both as part of the
15 input syntax, and as internal mechanism to glue together modules of
16 the program. This section is a very brief overview of entering data in
17 Scheme.@footnote{If you want to know more about Scheme, see
18 @uref{http://@/www@/.schemers@/.org}.}
20 The most basic thing of a language is data: numbers, character
21 strings, lists, etc. Here is a list of data types that are relevant to
26 Boolean values are True or False. The Scheme for True is @code{#t}
27 and False is @code{#f}.
31 Numbers are entered in the standard fashion,
32 @code{1} is the (integer) number one, while @code{-1.5} is a
33 floating point number (a non-integer number).
35 Strings are enclosed in double quotes,
40 Strings may span several lines
47 Quotation marks and newlines can also be added with so-called escape
48 sequences. The string @code{a said "b"} is entered as
53 Newlines and backslashes are escaped with @code{\n} and @code{\\}
58 In a music file, snippets of Scheme code are introduced with the hash
59 mark @code{#}. So, the previous examples translated in LilyPond are
70 For the rest of this section, we will assume that the data is entered
71 in a music file, so we add @code{#}s everywhere.
73 Scheme can be used to do calculations. It uses @emph{prefix}
74 syntax. Adding 1 and 2 is written as @code{(+ 1 2)} rather than the
82 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
83 is @code{3}. Calculations may be nested; the result of a function may
84 be used for another calculation.
92 These calculations are examples of evaluations; an expression like
93 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
94 happens with variables. After defining a variable
101 variables can also be used in expressions, here
104 twentyFour = #(* 2 twelve)
108 the number 24 is stored in the variable @code{twentyFour}.
109 The same assignment can be done in completely in Scheme as well,
112 #(define twentyFour (* twelve))
115 The @emph{name} of a variable is also an expression, similar to a
116 number or a string. It is entered as
122 @cindex @code{#'symbol}
123 @cindex quoting in Scheme
125 The quote mark @code{'} prevents Scheme interpreter from substituting
126 @code{24} for the @code{twentyFour}. Instead, we get the name
129 This syntax will be used very frequently, since many of the layout
130 tweaks involve assigning (Scheme) values to internal variables, for
134 \override Stem #'thickness = #2.6
137 This instruction adjusts the appearance of stems. The value @code{2.6}
138 is put into a the @code{thickness} variable of a @code{Stem}
139 object. This makes stems almost twice as thick as their normal size.
140 To distinguish between variables defined in input files (like
141 @code{twentyFour} in the example above) and variables of internal
142 objects, we will call the latter ``properties'' and the former
143 ``identifiers.'' So, the stem object has a @code{thickness} property,
144 while @code{twentyFour} is an identifier.
146 @cindex properties vs. identifiers
147 @cindex identifiers vs. properties
149 Two-dimensional offsets (X and Y coordinates) as well as object sizes
150 (intervals with a left and right point) are entered as @code{pairs}. A
151 pair@footnote{In Scheme terminology, the pair is called @code{cons},
152 and its two elements are called @code{car} and @code{cdr} respectively.} is entered
153 as @code{(first . second)} and, like symbols, they must be quoted,
156 \override TextScript #'extra-offset = #'(1 . 2)
159 This assigns the pair (1, 2) to the @code{extra-offset} property of the
160 TextScript object. This moves the object 1 staff space to the right,
163 The two elements of a pair may be arbitrary values, for example
168 #'("blah-blah" . 3.14159265)
171 A list is entered by enclosing its elements in parentheses, and adding
172 a quote. For example,
178 We have been using lists all along. A calculation, like @code{(+ 1
179 2)} is also a list (containing the symbol @code{+} and the numbers 1
180 and 2). Normally lists are interpreted as calculations, and the Scheme
181 interpreter substitutes the outcome of the calculation. To enter a
182 list, we stop evaluation. This is done by quoting the list with a
183 quote @code{'} symbol. So, for calculations do not use a quote.
185 Inside a quoted list or pair, there is no need to quote anymore. The
186 following is a pair of symbols, a list of symbols and a list of lists
191 #'(staff clef key-signature)