1 @c -*- coding: utf-8; mode: texinfo; -*-
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 modules of the program
16 together. This section is a very brief overview of entering data in
17 Scheme. 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}.
32 Numbers are entered in the standard fashion,
33 @code{1} is the (integer) number one, while @code{-1.5} is a
34 floating point number (a non-integer number).
37 Strings are enclosed in double quotes,
43 Strings may span several lines
51 Quotation marks and newlines can also be added with so-called escape
52 sequences. The string @code{a said "b"} is entered as
58 Newlines and backslashes are escaped with @code{\n} and @code{\\}
63 In a music file, snippets of Scheme code are introduced with the hash
64 mark @code{#}. So, the previous examples translated in LilyPond are
75 For the rest of this section, we will assume that the data is entered
76 in a music file, so we add @code{#}s everywhere.
78 Scheme can be used to do calculations. It uses @emph{prefix}
79 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
80 traditional @math{1+2}.
87 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
88 is@tie{}@code{3}. Calculations may be nested; the result of a function may
89 be used for another calculation.
97 These calculations are examples of evaluations; an expression like
98 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
99 happens with variables. After defining a variable
106 variables can also be used in expressions, here
109 twentyFour = #(* 2 twelve)
113 the number 24 is stored in the variable @code{twentyFour}.
114 The same assignment can be done in completely in Scheme as well,
117 #(define twentyFour (* 2 twelve))
120 The @emph{name} of a variable is also an expression, similar to a
121 number or a string. It is entered as
128 @cindex quoting in Scheme
130 The quote mark @code{'} prevents the Scheme interpreter from substituting
131 @code{24} for the @code{twentyFour}. Instead, we get the name
134 This syntax will be used very frequently, since many of the layout
135 tweaks involve assigning (Scheme) values to internal variables, for
139 \override Stem #'thickness = #2.6
142 This instruction adjusts the appearance of stems. The value @code{2.6}
143 is put into the @code{thickness} variable of a @code{Stem}
144 object. @code{thickness} is measured relative to the thickness of
145 staff lines, so these stem lines will be @code{2.6} times the
146 width of staff lines. This makes stems almost twice as thick as their
147 normal size. To distinguish between variables defined in input files (like
148 @code{twentyFour} in the example above) and variables of internal
149 objects, we will call the latter @q{properties} and the former
150 @q{identifiers.} So, the stem object has a @code{thickness} property,
151 while @code{twentyFour} is an identifier.
153 @cindex properties vs. identifiers
154 @cindex identifiers vs. properties
156 Two-dimensional offsets (X and Y coordinates) as well as object sizes
157 (intervals with a left and right point) are entered as @code{pairs}. A
158 pair@footnote{In Scheme terminology, the pair is called @code{cons},
159 and its two elements are called @code{car} and @code{cdr} respectively.}
160 is entered as @code{(first . second)} and, like symbols, they must be quoted,
163 \override TextScript #'extra-offset = #'(1 . 2)
166 This assigns the pair (1, 2) to the @code{extra-offset} property of the
167 TextScript object. These numbers are measured in staff-spaces, so
168 this command moves the object 1 staff space to the right, and 2 spaces up.
170 The two elements of a pair may be arbitrary values, for example
175 #'("blah-blah" . 3.14159265)
178 A list is entered by enclosing its elements in parentheses, and adding
179 a quote. For example,
186 We have been using lists all along. A calculation, like @code{(+ 1 2)}
187 is also a list (containing the symbol @code{+} and the numbers 1
188 and@tie{}2). Normally lists are interpreted as calculations, and the
189 Scheme interpreter substitutes the outcome of the calculation. To enter a
190 list, we stop the evaluation. This is done by quoting the list with a
191 quote @code{'} symbol. So, for calculations do not use a quote.
193 Inside a quoted list or pair, there is no need to quote anymore. The
194 following is a pair of symbols, a list of symbols and a list of lists
199 #'(staff clef key-signature)