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.
13 @appendix Scheme tutorial
18 @cindex Scheme, in-line code
19 @cindex accessing Scheme
20 @cindex evaluating Scheme
23 LilyPond uses the Scheme programming language, both as part of the
24 input syntax, and as internal mechanism to glue modules of the program
25 together. This section is a very brief overview of entering data in
26 Scheme. If you want to know more about Scheme, see
27 @uref{http://@/www@/.schemers@/.org}.
29 LilyPond uses the GNU Guile implementation of Scheme, which is
30 based on the Scheme @qq{R5RS} standard. If you are learning Scheme
31 to use with LilyPond, working with a different implementation (or
32 referring to a different standard) is not recommended. Information
33 on guile can be found at @uref{http://www.gnu.org/software/guile/}.
34 The @qq{R5RS} Scheme standard is located at
35 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
37 The LilyPond installation also includes the Guile implementation of
38 Scheme. On most systems you can experiment in a Scheme sandbox by
39 opening a terminal window and typing @q{guile}. On some systems,
40 notably Windows, you may need to set the environment variable
41 @code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
42 in the LilyPond installation (for the full path to this directory
43 see @ref{Other sources of information}). Alternatively, Windows
44 users may simply choose @q{Run} from the Start menu and enter
47 The most basic concept in a language is data typing: numbers, character
48 strings, lists, etc. Here is a list of data types that are relevant to
53 Boolean values are True or False. The Scheme for True is @code{#t}
54 and False is @code{#f}.
59 Numbers are entered in the standard fashion,
60 @code{1} is the (integer) number one, while @code{-1.5} is a
61 floating point number (a non-integer number).
64 Strings are enclosed in double quotes,
70 Strings may span several lines
78 Quotation marks and newlines can also be added with so-called escape
79 sequences. The string @code{a said "b"} is entered as
85 Newlines and backslashes are escaped with @code{\n} and @code{\\}
90 In a music file, snippets of Scheme code are introduced with the hash
91 mark @code{#}. So, the previous examples translated to LilyPond are
102 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
103 be used within Scheme code. Comments in Guile Scheme are entered
107 ; this is a single-line comment
110 This a (non-nestable) Guile-style block comment
111 But these are rarely used by Schemers and never in
116 Multiple consecutive scheme expressions in a music file can be
117 combined using the @code{begin} operator. This permits the number
118 of hash marks to be reduced to one.
126 If @code{#} is followed by an opening bracket, @code{(}, as in
127 the example above, the parser will remain in Scheme mode until
128 a matching closing bracket, @code{)}, is found, so further
129 @code{#} symbols to introduce a Scheme section are not required.
131 For the rest of this section, we will assume that the data is entered
132 in a music file, so we add @code{#}s everywhere.
134 Scheme can be used to do calculations. It uses @emph{prefix}
135 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
136 traditional @math{1+2}.
143 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
144 is@tie{}@code{3}. Calculations may be nested; the result of a function may
145 be used for another calculation.
153 These calculations are examples of evaluations; an expression like
154 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
155 happens with variables. After defining a variable
162 variables can also be used in expressions, here
165 twentyFour = #(* 2 twelve)
169 the number 24 is stored in the variable @code{twentyFour}.
170 The same assignment can be done in completely in Scheme as well,
173 #(define twentyFour (* 2 twelve))
176 The @emph{name} of a variable is also an expression, similar to a
177 number or a string. It is entered as
184 @cindex quoting in Scheme
186 The quote mark @code{'} prevents the Scheme interpreter from substituting
187 @code{24} for the @code{twentyFour}. Instead, we get the name
190 This syntax will be used very frequently, since many of the layout
191 tweaks involve assigning (Scheme) values to internal variables, for
195 \override Stem #'thickness = #2.6
198 This instruction adjusts the appearance of stems. The value @code{2.6}
199 is put into the @code{thickness} variable of a @code{Stem}
200 object. @code{thickness} is measured relative to the thickness of
201 staff lines, so these stem lines will be @code{2.6} times the
202 width of staff lines. This makes stems almost twice as thick as their
203 normal size. To distinguish between variables defined in input files (like
204 @code{twentyFour} in the example above) and variables of internal
205 objects, we will call the latter @q{properties} and the former
206 @q{variables.} So, the stem object has a @code{thickness} property,
207 while @code{twentyFour} is an variable.
209 @cindex properties vs. variables
210 @cindex variables vs. properties
212 Two-dimensional offsets (X and Y coordinates) as well as object sizes
213 (intervals with a left and right point) are entered as @code{pairs}. A
214 pair@footnote{In Scheme terminology, the pair is called @code{cons},
215 and its two elements are called @code{car} and @code{cdr} respectively.}
216 is entered as @code{(first . second)} and, like symbols, they must be quoted,
219 \override TextScript #'extra-offset = #'(1 . 2)
222 This assigns the pair (1, 2) to the @code{extra-offset} property of the
223 TextScript object. These numbers are measured in staff-spaces, so
224 this command moves the object 1 staff space to the right, and 2 spaces up.
226 The two elements of a pair may be arbitrary values, for example
231 #'("blah-blah" . 3.14159265)
234 A list is entered by enclosing its elements in parentheses, and adding
235 a quote. For example,
242 We have been using lists all along. A calculation, like @code{(+ 1 2)}
243 is also a list (containing the symbol @code{+} and the numbers 1
244 and@tie{}2). Normally lists are interpreted as calculations, and the
245 Scheme interpreter substitutes the outcome of the calculation. To enter a
246 list, we stop the evaluation. This is done by quoting the list with a
247 quote @code{'} symbol. So, for calculations do not use a quote.
249 Inside a quoted list or pair, there is no need to quote anymore. The
250 following is a pair of symbols, a list of symbols and a list of lists
255 #'(staff clef key-signature)
261 * Tweaking with Scheme::
264 @node Tweaking with Scheme
265 @appendixsec Tweaking with Scheme
267 We have seen how LilyPond output can be heavily modified using
269 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
270 we have even more power if we use Scheme. For a full explanation
271 of this, see the @ref{Scheme tutorial}, and
272 @ruser{Interfaces for programmers}.
274 We can use Scheme to simply @code{\override} commands,
276 TODO Find a simple example
277 @c This isn't a valid example with skylining
278 @c It works fine without padText -td
281 @lilypond[quote,verbatim,ragged-right]
282 padText = #(define-music-function (parser location padding) (number?)
284 \once \override TextScript #'padding = #$padding
292 c4^"piu mosso" fis a g
297 We can use it to create new commands:
299 @c Check this is a valid example with skylining
300 @c It is - 'padding still works
303 @lilypond[quote,verbatim,ragged-right]
304 tempoPadded = #(define-music-function (parser location padding tempotext)
307 \once \override Score.MetronomeMark #'padding = $padding
308 \tempo \markup { \bold $tempotext }
312 \tempo \markup { "Low tempo" }
314 \tempoPadded #4.0 #"High tempo"
320 Even music expressions can be passed in:
322 @lilypond[quote,verbatim,ragged-right]
323 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
330 \pattern {d16 dis} { ais16-> b\p }