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 The most basic thing of a language is data: numbers, character
30 strings, lists, etc. Here is a list of data types that are relevant to
35 Boolean values are True or False. The Scheme for True is @code{#t}
36 and False is @code{#f}.
41 Numbers are entered in the standard fashion,
42 @code{1} is the (integer) number one, while @code{-1.5} is a
43 floating point number (a non-integer number).
46 Strings are enclosed in double quotes,
52 Strings may span several lines
60 Quotation marks and newlines can also be added with so-called escape
61 sequences. The string @code{a said "b"} is entered as
67 Newlines and backslashes are escaped with @code{\n} and @code{\\}
72 In a music file, snippets of Scheme code are introduced with the hash
73 mark @code{#}. So, the previous examples translated in LilyPond are
84 For the rest of this section, we will assume that the data is entered
85 in a music file, so we add @code{#}s everywhere.
87 Scheme can be used to do calculations. It uses @emph{prefix}
88 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
89 traditional @math{1+2}.
96 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
97 is@tie{}@code{3}. Calculations may be nested; the result of a function may
98 be used for another calculation.
106 These calculations are examples of evaluations; an expression like
107 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
108 happens with variables. After defining a variable
115 variables can also be used in expressions, here
118 twentyFour = #(* 2 twelve)
122 the number 24 is stored in the variable @code{twentyFour}.
123 The same assignment can be done in completely in Scheme as well,
126 #(define twentyFour (* 2 twelve))
129 The @emph{name} of a variable is also an expression, similar to a
130 number or a string. It is entered as
137 @cindex quoting in Scheme
139 The quote mark @code{'} prevents the Scheme interpreter from substituting
140 @code{24} for the @code{twentyFour}. Instead, we get the name
143 This syntax will be used very frequently, since many of the layout
144 tweaks involve assigning (Scheme) values to internal variables, for
148 \override Stem #'thickness = #2.6
151 This instruction adjusts the appearance of stems. The value @code{2.6}
152 is put into the @code{thickness} variable of a @code{Stem}
153 object. @code{thickness} is measured relative to the thickness of
154 staff lines, so these stem lines will be @code{2.6} times the
155 width of staff lines. This makes stems almost twice as thick as their
156 normal size. To distinguish between variables defined in input files (like
157 @code{twentyFour} in the example above) and variables of internal
158 objects, we will call the latter @q{properties} and the former
159 @q{variables.} So, the stem object has a @code{thickness} property,
160 while @code{twentyFour} is an variable.
162 @cindex properties vs. variables
163 @cindex variables vs. properties
165 Two-dimensional offsets (X and Y coordinates) as well as object sizes
166 (intervals with a left and right point) are entered as @code{pairs}. A
167 pair@footnote{In Scheme terminology, the pair is called @code{cons},
168 and its two elements are called @code{car} and @code{cdr} respectively.}
169 is entered as @code{(first . second)} and, like symbols, they must be quoted,
172 \override TextScript #'extra-offset = #'(1 . 2)
175 This assigns the pair (1, 2) to the @code{extra-offset} property of the
176 TextScript object. These numbers are measured in staff-spaces, so
177 this command moves the object 1 staff space to the right, and 2 spaces up.
179 The two elements of a pair may be arbitrary values, for example
184 #'("blah-blah" . 3.14159265)
187 A list is entered by enclosing its elements in parentheses, and adding
188 a quote. For example,
195 We have been using lists all along. A calculation, like @code{(+ 1 2)}
196 is also a list (containing the symbol @code{+} and the numbers 1
197 and@tie{}2). Normally lists are interpreted as calculations, and the
198 Scheme interpreter substitutes the outcome of the calculation. To enter a
199 list, we stop the evaluation. This is done by quoting the list with a
200 quote @code{'} symbol. So, for calculations do not use a quote.
202 Inside a quoted list or pair, there is no need to quote anymore. The
203 following is a pair of symbols, a list of symbols and a list of lists
208 #'(staff clef key-signature)
214 * Tweaking with Scheme::
217 @node Tweaking with Scheme
218 @appendixsec Tweaking with Scheme
220 We have seen how LilyPond output can be heavily modified using
222 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
223 we have even more power if we use Scheme. For a full explanation
224 of this, see the @ref{Scheme tutorial}, and
225 @ruser{Interfaces for programmers}.
227 We can use Scheme to simply @code{\override} commands,
229 TODO Find a simple example
230 @c This isn't a valid example with skylining
231 @c It works fine without padText -td
234 @lilypond[quote,verbatim,ragged-right]
235 padText = #(define-music-function (parser location padding) (number?)
237 \once \override TextScript #'padding = #$padding
245 c4^"piu mosso" fis a g
250 We can use it to create new commands:
252 @c Check this is a valid example with skylining
253 @c It is - 'padding still works
255 @lilypond[quote,verbatim,ragged-right]
256 tempoMark = #(define-music-function (parser location padding marktext)
259 \once \override Score . RehearsalMark #'padding = $padding
260 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
261 \mark \markup { \bold $marktext }
266 \tempoMark #3.0 #"Allegro"
271 Even music expressions can be passed in:
273 @lilypond[quote,verbatim,ragged-right]
274 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
281 \pattern {d16 dis} { ais16-> b\p }