1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @appendix Scheme tutorial
16 @cindex Scheme, in-line code
17 @cindex accessing Scheme
18 @cindex evaluating Scheme
21 LilyPond uses the Scheme programming language, both as part of the
22 input syntax, and as internal mechanism to glue modules of the program
23 together. This section is a very brief overview of entering data in
24 Scheme. If you want to know more about Scheme, see
25 @uref{http://@/www@/.schemers@/.org}.
27 The most basic thing of a language is data: numbers, character
28 strings, lists, etc. Here is a list of data types that are relevant to
33 Boolean values are True or False. The Scheme for True is @code{#t}
34 and False is @code{#f}.
39 Numbers are entered in the standard fashion,
40 @code{1} is the (integer) number one, while @code{-1.5} is a
41 floating point number (a non-integer number).
44 Strings are enclosed in double quotes,
50 Strings may span several lines
58 Quotation marks and newlines can also be added with so-called escape
59 sequences. The string @code{a said "b"} is entered as
65 Newlines and backslashes are escaped with @code{\n} and @code{\\}
70 In a music file, snippets of Scheme code are introduced with the hash
71 mark @code{#}. So, the previous examples translated in LilyPond are
82 For the rest of this section, we will assume that the data is entered
83 in a music file, so we add @code{#}s everywhere.
85 Scheme can be used to do calculations. It uses @emph{prefix}
86 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
87 traditional @math{1+2}.
94 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
95 is@tie{}@code{3}. Calculations may be nested; the result of a function may
96 be used for another calculation.
104 These calculations are examples of evaluations; an expression like
105 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
106 happens with variables. After defining a variable
113 variables can also be used in expressions, here
116 twentyFour = #(* 2 twelve)
120 the number 24 is stored in the variable @code{twentyFour}.
121 The same assignment can be done in completely in Scheme as well,
124 #(define twentyFour (* 2 twelve))
127 The @emph{name} of a variable is also an expression, similar to a
128 number or a string. It is entered as
135 @cindex quoting in Scheme
137 The quote mark @code{'} prevents the Scheme interpreter from substituting
138 @code{24} for the @code{twentyFour}. Instead, we get the name
141 This syntax will be used very frequently, since many of the layout
142 tweaks involve assigning (Scheme) values to internal variables, for
146 \override Stem #'thickness = #2.6
149 This instruction adjusts the appearance of stems. The value @code{2.6}
150 is put into the @code{thickness} variable of a @code{Stem}
151 object. @code{thickness} is measured relative to the thickness of
152 staff lines, so these stem lines will be @code{2.6} times the
153 width of staff lines. This makes stems almost twice as thick as their
154 normal size. To distinguish between variables defined in input files (like
155 @code{twentyFour} in the example above) and variables of internal
156 objects, we will call the latter @q{properties} and the former
157 @q{variables.} So, the stem object has a @code{thickness} property,
158 while @code{twentyFour} is an variable.
160 @cindex properties vs. variables
161 @cindex variables vs. properties
163 Two-dimensional offsets (X and Y coordinates) as well as object sizes
164 (intervals with a left and right point) are entered as @code{pairs}. A
165 pair@footnote{In Scheme terminology, the pair is called @code{cons},
166 and its two elements are called @code{car} and @code{cdr} respectively.}
167 is entered as @code{(first . second)} and, like symbols, they must be quoted,
170 \override TextScript #'extra-offset = #'(1 . 2)
173 This assigns the pair (1, 2) to the @code{extra-offset} property of the
174 TextScript object. These numbers are measured in staff-spaces, so
175 this command moves the object 1 staff space to the right, and 2 spaces up.
177 The two elements of a pair may be arbitrary values, for example
182 #'("blah-blah" . 3.14159265)
185 A list is entered by enclosing its elements in parentheses, and adding
186 a quote. For example,
193 We have been using lists all along. A calculation, like @code{(+ 1 2)}
194 is also a list (containing the symbol @code{+} and the numbers 1
195 and@tie{}2). Normally lists are interpreted as calculations, and the
196 Scheme interpreter substitutes the outcome of the calculation. To enter a
197 list, we stop the evaluation. This is done by quoting the list with a
198 quote @code{'} symbol. So, for calculations do not use a quote.
200 Inside a quoted list or pair, there is no need to quote anymore. The
201 following is a pair of symbols, a list of symbols and a list of lists
206 #'(staff clef key-signature)