LEFT | RIGHT |
1 @c -*- coding: utf-8; mode: texinfo; -*- | 1 @c -*- coding: utf-8; mode: texinfo; -*- |
2 | 2 |
3 @ignore | 3 @ignore |
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH | 4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH |
5 | 5 |
6 When revising a translation, copy the HEAD committish of the | 6 When revising a translation, copy the HEAD committish of the |
7 version that you are working on. For details, see the Contributors' | 7 version that you are working on. For details, see the Contributors' |
8 Guide, node Updating translation committishes.. | 8 Guide, node Updating translation committishes.. |
9 @end ignore | 9 @end ignore |
10 | 10 |
(...skipping 12 matching lines...) Expand all Loading... |
23 * Contexts for programmers:: | 23 * Contexts for programmers:: |
24 * Callback functions:: | 24 * Callback functions:: |
25 * Inline Scheme code:: | 25 * Inline Scheme code:: |
26 * Difficult tweaks:: | 26 * Difficult tweaks:: |
27 @end menu | 27 @end menu |
28 | 28 |
29 | 29 |
30 @node Music functions | 30 @node Music functions |
31 @section Music functions | 31 @section Music functions |
32 | 32 |
33 Music functions are scheme functions that are used to | 33 @emph{Music functions} are scheme procedures that can create music |
34 automatically create music expressions. They can be used to | 34 expressions automatically, and can be used to greatly simplify the |
35 greatly simplify the input file. | 35 input file. |
36 | 36 |
37 @menu | 37 @menu |
38 * Music function syntax:: | 38 * Music function syntax:: |
39 * Simple substitution functions:: | 39 * Simple substitution functions:: |
40 * Intermediate substitution functions:: | 40 * Intermediate substitution functions:: |
41 * Mathematics in functions:: | 41 * Mathematics in functions:: |
| 42 * Functions without arguments:: |
42 * Void functions:: | 43 * Void functions:: |
43 * Functions without arguments:: | |
44 @end menu | 44 @end menu |
| 45 |
45 | 46 |
46 @node Music function syntax | 47 @node Music function syntax |
47 @subsection Music function syntax | 48 @subsection Music function syntax |
48 | 49 |
49 The general syntax of a music function is: | 50 The general form for music functions is: |
50 | 51 |
51 @example | 52 @example |
52 myFunction = | 53 function = |
53 #(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n}) | 54 #(define-music-function |
54 (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?}
) | 55 (parser location @var{arg1} @var{arg2} @dots{}) |
55 @var{...valid music expression...}) | 56 (@var{type1?} @var{type2?} @dots{}) |
| 57 @var{music}) |
56 @end example | 58 @end example |
57 | 59 |
58 @noindent | 60 @noindent |
59 where | 61 where |
60 | 62 |
61 @multitable @columnfractions .33 .66 | 63 @multitable @columnfractions .33 .66 |
62 @item @var{var_i} @tab @var{i}th variable | 64 @item @code{@var{argN}} |
63 @item @var{var_i-type?} @tab type of @var{i}th variable | 65 @tab @var{n}th argument |
64 @item @var{...valid music expression...} @tab expression that returns | 66 |
65 valid music, generally in the form of a Scheme expression. There is | 67 @item @code{@var{typeN?}} |
66 also special syntax that allows LilyPond input code in this music | 68 @tab a scheme @emph{type predicate} for which @code{@var{argN}} |
67 expression. | 69 must return @code{#t}. |
| 70 |
| 71 @item @code{@var{music}} |
| 72 @tab A music expression, optionally written in scheme, with any |
| 73 LilyPond code enclosed in hashed braces |
| 74 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Within LilyPond code |
| 75 blocks, use @code{$} to reference function arguments (eg., |
| 76 @samp{$arg1}) or to start an inline scheme expression containing |
| 77 function arguments (eg., @w{@samp{$(cons arg1 arg2)}}). |
| 78 |
68 @end multitable | 79 @end multitable |
69 | 80 |
70 The variable type checkers are scheme procedures that will return | 81 @noindent |
71 @code{#t} if a variable is of a given type. Some common types | 82 For a list of available type predicates, see |
72 are shown in the table below. Other types can be found in the files | 83 @ruser{Predefined type predicates}. User-defined type predicates |
73 @file{lily/music-scheme.cc} and @file{scm/c++.scm}. The complete | 84 are also allowed. |
74 list of named type checkers for LilyPond is found in the | 85 |
75 @var{type-p-name-alist} of @file{scm/lily.scm}. | 86 |
76 | 87 @seealso |
77 @c TODO -- automatically document type-p-name-alist | 88 |
78 | 89 Notation Reference: |
79 @multitable @columnfractions .33 .66 | 90 @ruser{Predefined type predicates}. |
80 @headitem Input type @tab @var{vari-type?} notation | 91 |
81 @item Integer @tab @code{integer?} | 92 Installed Files: |
82 @item Float (decimal number) @tab @code{number?} | 93 @file{lily/music-scheme.cc}, |
83 @item Text string @tab @code{string?} | 94 @file{scm/c++.scm}, |
84 @item Markup @tab @code{markup?} | 95 @file{scm/lily.scm}. |
85 @item Music expression @tab @code{ly:music?} | 96 |
86 @item A pair of variables @tab @code{pair?} | |
87 @end multitable | |
88 | |
89 The @code{parser} and @code{location} arguments are mandatory. | |
90 The @code{parser} argument is used in the body of the function | |
91 to gain access to the value of another LilyPond variable. | |
92 The @code{location} argument is used to set the @q{origin} | |
93 of the music expression that is built by the music function, | |
94 so that in case of a syntax error LilyPond | |
95 can tell the user an appropriate place to look in the input file. | |
96 | 97 |
97 @node Simple substitution functions | 98 @node Simple substitution functions |
98 @subsection Simple substitution functions | 99 @subsection Simple substitution functions |
99 | 100 |
100 A simple substitution function is a music function whose output music | 101 Simple substitution functions are music functions whose output |
101 expression is written in LilyPond code, but with an input variable | 102 music expression is written in LilyPond format and contains |
102 substituted into the LilyPond code. The general form of these functions is | 103 function arguments in the output expression. They are described |
103 | 104 in @ruser{Substitution function examples}. |
104 @example | 105 |
105 myFunction = | |
106 #(define-music-function (parser location @var{var1}) | |
107 (@var{var1-type?}) | |
108 #@{ | |
109 @emph{... LilyPond input code with} @code{#$var1} @emph{for substition ...} | |
110 #@}) | |
111 @end example | |
112 | |
113 Note that the special characters @code{#@{} and @code{#@}} surround the | |
114 LilyPond music. | |
115 | |
116 @multitable @columnfractions .33 .66 | |
117 @item @var{vari} @tab @var{i}th variable | |
118 @item @var{vari-type?} @tab type of @var{i}th variable | |
119 @item @var{...music...} @tab normal LilyPond input, using | |
120 variables as @code{#$var1}, etc. | |
121 @end multitable | |
122 | |
123 For example, a function can be defined that simplifies | |
124 setting the padding of a TextScript: | |
125 | |
126 @lilypond[quote,verbatim,ragged-right] | |
127 padText = #(define-music-function (parser location padding) (number?) | |
128 #{ | |
129 \once \override TextScript #'padding = #$padding | |
130 #}) | |
131 | |
132 \relative c''' { | |
133 c4^"piu mosso" b a b | |
134 \padText #1.8 | |
135 c4^"piu mosso" d e f | |
136 \padText #2.6 | |
137 c4^"piu mosso" fis a g | |
138 } | |
139 @end lilypond | |
140 | |
141 In addition to numbers, we can use music expressions such | |
142 as notes for arguments to music functions: | |
143 | |
144 @lilypond[quote,verbatim,ragged-right] | |
145 custosNote = #(define-music-function (parser location note) | |
146 (ly:music?) | |
147 #{ | |
148 \once \override Voice.NoteHead #'stencil = | |
149 #ly:text-interface::print | |
150 \once \override Voice.NoteHead #'text = | |
151 \markup \musicglyph #"custodes.mensural.u0" | |
152 \once \override Voice.Stem #'stencil = ##f | |
153 $note | |
154 #}) | |
155 @end lilypond | |
156 | 106 |
157 @node Intermediate substitution functions | 107 @node Intermediate substitution functions |
158 @subsection Intermediate substitution functions | 108 @subsection Intermediate substitution functions |
159 | 109 |
160 Slightly more complicated than simple substitution function, | 110 Intermediate substitution functions involve a mix of Scheme code |
161 intermediate substitution functions involve a mix of Scheme code and | 111 and LilyPond code in the music expression to be returned. |
162 LilyPond code in the music expression to be | |
163 returned. | |
164 | 112 |
165 Some @code{\override} commands require an argument consisting of | 113 Some @code{\override} commands require an argument consisting of |
166 a pair of numbers (called a @code{cons cell} in Scheme). | 114 a pair of numbers (called a @code{cons cell} in Scheme). |
167 | 115 |
168 The pair can be directly passed into the music function, | 116 The pair can be directly passed into the music function, |
169 using a @code{pair?} variable: | 117 using a @code{pair?} variable: |
170 | 118 |
171 @quotation | |
172 @example | 119 @example |
173 manualBeam = | 120 manualBeam = |
174 #(define-music-function (parser location beg-end) | 121 #(define-music-function |
175 (pair?) | 122 (parser location beg-end) |
176 #@{ | 123 (pair?) |
177 \once \override Beam #'positions = #$beg-end | 124 #@{ |
178 #@}) | 125 \once \override Beam #'positions = $beg-end |
| 126 #@}) |
179 | 127 |
180 \relative c' @{ | 128 \relative c' @{ |
181 \manualBeam #'(3 . 6) c8 d e f | 129 \manualBeam #'(3 . 6) c8 d e f |
182 @} | 130 @} |
183 @end example | 131 @end example |
184 @end quotation | |
185 | 132 |
186 Alternatively, the numbers making up the pair can be | 133 Alternatively, the numbers making up the pair can be |
187 passed as separate arguments, and the Scheme code | 134 passed as separate arguments, and the Scheme code |
188 used to create the pair can be included in the | 135 used to create the pair can be included in the |
189 music expression: | 136 music expression: |
190 | 137 |
191 @lilypond[quote,verbatim,ragged-right] | 138 @lilypond[quote,verbatim,ragged-right] |
192 manualBeam = | 139 manualBeam = |
193 #(define-music-function (parser location beg end) | 140 #(define-music-function |
194 (number? number?) | 141 (parser location beg end) |
195 #{ | 142 (number? number?) |
196 \once \override Beam #'positions = #(cons $beg $end) | 143 #{ |
197 #}) | 144 \once \override Beam #'positions = $(cons beg end) |
| 145 #}) |
198 | 146 |
199 \relative c' { | 147 \relative c' { |
200 \manualBeam #3 #6 c8 d e f | 148 \manualBeam #3 #6 c8 d e f |
201 } | 149 } |
202 @end lilypond | 150 @end lilypond |
203 | 151 |
204 | 152 |
205 @node Mathematics in functions | 153 @node Mathematics in functions |
206 @subsection Mathematics in functions | 154 @subsection Mathematics in functions |
207 | 155 |
208 Music functions can involve Scheme programming in | 156 Music functions can involve Scheme programming in |
209 addition to simple substitution, | 157 addition to simple substitution, |
210 | 158 |
211 @lilypond[quote,verbatim,ragged-right] | 159 @lilypond[quote,verbatim,ragged-right] |
212 AltOn = #(define-music-function (parser location mag) (number?) | 160 AltOn = |
213 #{ \override Stem #'length = #$(* 7.0 mag) | 161 #(define-music-function |
| 162 (parser location mag) |
| 163 (number?) |
| 164 #{ |
| 165 \override Stem #'length = $(* 7.0 mag) |
214 \override NoteHead #'font-size = | 166 \override NoteHead #'font-size = |
215 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #}) | 167 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) |
| 168 #}) |
216 | 169 |
217 AltOff = { | 170 AltOff = { |
218 \revert Stem #'length | 171 \revert Stem #'length |
219 \revert NoteHead #'font-size | 172 \revert NoteHead #'font-size |
220 } | 173 } |
221 | 174 |
222 { c'2 \AltOn #0.5 c'4 c' | 175 \relative c' { |
223 \AltOn #1.5 c' c' \AltOff c'2 } | 176 c2 \AltOn #0.5 c4 c |
| 177 \AltOn #1.5 c c \AltOff c2 |
| 178 } |
224 @end lilypond | 179 @end lilypond |
225 | 180 |
226 @noindent | 181 @noindent |
227 This example may be rewritten to pass in music expressions, | 182 This example may be rewritten to pass in music expressions, |
228 | 183 |
229 @lilypond[quote,verbatim,ragged-right] | 184 @lilypond[quote,verbatim,ragged-right] |
230 withAlt = #(define-music-function (parser location mag music) (number? ly:music?
) | 185 withAlt = |
231 #{ \override Stem #'length = #$(* 7.0 mag) | 186 #(define-music-function |
| 187 (parser location mag music) |
| 188 (number? ly:music?) |
| 189 #{ |
| 190 \override Stem #'length = $(* 7.0 mag) |
232 \override NoteHead #'font-size = | 191 \override NoteHead #'font-size = |
233 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) | 192 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) |
234 $music | 193 $music |
235 \revert Stem #'length | 194 \revert Stem #'length |
236 \revert NoteHead #'font-size #}) | 195 \revert NoteHead #'font-size |
237 | 196 #}) |
238 { c'2 \withAlt #0.5 {c'4 c'} | 197 |
239 \withAlt #1.5 {c' c'} c'2 } | 198 \relative c' { |
| 199 c2 \withAlt #0.5 { c4 c } |
| 200 \withAlt #1.5 { c c } c2 |
| 201 } |
240 @end lilypond | 202 @end lilypond |
| 203 |
| 204 |
| 205 @node Functions without arguments |
| 206 @subsection Functions without arguments |
| 207 |
| 208 In most cases a function without arguments should be written |
| 209 with a variable, |
| 210 |
| 211 @example |
| 212 dolce = \markup@{ \italic \bold dolce @} |
| 213 @end example |
| 214 |
| 215 However, in rare cases it may be useful to create a music function |
| 216 without arguments, |
| 217 |
| 218 @example |
| 219 displayBarNum = |
| 220 #(define-music-function |
| 221 (parser location) |
| 222 () |
| 223 (if (eq? #t (ly:get-option 'display-bar-numbers)) |
| 224 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@} |
| 225 #@{#@})) |
| 226 @end example |
| 227 |
| 228 To actually display bar numbers where this function is called, |
| 229 invoke @command{lilypond} with |
| 230 |
| 231 @example |
| 232 lilypond -d display-bar-numbers FILENAME.ly |
| 233 @end example |
| 234 |
241 | 235 |
242 @node Void functions | 236 @node Void functions |
243 @subsection Void functions | 237 @subsection Void functions |
244 | 238 |
245 A music function must return a music expression, but sometimes we | 239 A music function must return a music expression, but sometimes we |
246 may want to have a function that does not involve music (such as | 240 may want to have a function that does not involve music (such as |
247 turning off Point and Click). To do this, we return a @code{void} | 241 turning off Point and Click). To do this, we return a @code{void} |
248 music expression. | 242 music expression. |
249 | 243 |
250 That is why the form | 244 That is why the form that is returned is the |
251 that is returned is the @code{(make-music ...)}. With the | 245 @w{@code{(make-music @dots{})}}. With the @code{'void} property |
252 @code{'void} property set to @code{#t}, the parser is told to | 246 set to @code{#t}, the parser is told to actually disregard this |
253 actually disregard this returned music | 247 returned music expression. Thus the important part of the void |
254 expression. Thus the important part of the void music function is the | 248 music function is the processing done by the function, not the |
255 processing done by the function, not the music expression that is | 249 music expression that is returned. |
256 returned. | |
257 | 250 |
258 @example | 251 @example |
259 noPointAndClick = | 252 noPointAndClick = |
260 #(define-music-function (parser location) () | 253 #(define-music-function |
| 254 (parser location) |
| 255 () |
261 (ly:set-option 'point-and-click #f) | 256 (ly:set-option 'point-and-click #f) |
262 (make-music 'SequentialMusic 'void #t)) | 257 (make-music 'SequentialMusic 'void #t)) |
263 ... | 258 ... |
264 \noPointAndClick % disable point and click | 259 \noPointAndClick % disable point and click |
265 @end example | 260 @end example |
266 | |
267 | |
268 @node Functions without arguments | |
269 @subsection Functions without arguments | |
270 | |
271 In most cases a function without arguments should be written | |
272 with a variable, | |
273 | |
274 @example | |
275 dolce = \markup@{ \italic \bold dolce @} | |
276 @end example | |
277 | |
278 However, in rare cases it may be useful to create a music function | |
279 without arguments, | |
280 | |
281 @example | |
282 displayBarNum = | |
283 #(define-music-function (parser location) () | |
284 (if (eq? #t (ly:get-option 'display-bar-numbers)) | |
285 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@} | |
286 #@{#@})) | |
287 @end example | |
288 | |
289 To actually display bar numbers where this function is called, | |
290 invoke @command{lilypond} with | |
291 | |
292 @example | |
293 lilypond -d display-bar-numbers FILENAME.ly | |
294 @end example | |
295 | |
296 | 261 |
297 | 262 |
298 @node Markup functions | 263 @node Markup functions |
299 @section Markup functions | 264 @section Markup functions |
300 | 265 |
301 Markups are implemented as special Scheme functions which produce a | 266 Markups are implemented as special Scheme functions which produce a |
302 @code{Stencil} object given a number of arguments. | 267 @code{Stencil} object given a number of arguments. |
303 | 268 |
304 @menu | 269 @menu |
305 * Markup construction in Scheme:: | 270 * Markup construction in Scheme:: |
(...skipping 140 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
446 @item argi | 411 @item argi |
447 @var{i}th command argument | 412 @var{i}th command argument |
448 @item argi-type? | 413 @item argi-type? |
449 a type predicate for the i@var{th} argument | 414 a type predicate for the i@var{th} argument |
450 @end table | 415 @end table |
451 | 416 |
452 If the command uses properties from the @var{props} arguments, the | 417 If the command uses properties from the @var{props} arguments, the |
453 @code{#:properties} keyword can be used, to specify which properties are | 418 @code{#:properties} keyword can be used, to specify which properties are |
454 used, and their default values. | 419 used, and their default values. |
455 | 420 |
456 @knownissues | |
457 There are restrictions on the possible arguments to a markup command. | |
458 | |
459 Arguments are distinguished according to their type: | 421 Arguments are distinguished according to their type: |
460 @itemize | 422 @itemize |
461 @item a list of markup, corresponding to type predicate | 423 @item a markup, corresponding to type predicate @code{markup?}; |
| 424 @item a list of markups, corresponding to type predicate |
462 @code{markup-list?}; | 425 @code{markup-list?}; |
463 @item a markup, corresponding to type predicate @code{markup?}; | |
464 @item any other scheme object, corresponding to type predicates such as | 426 @item any other scheme object, corresponding to type predicates such as |
465 @code{list?}, @code{number?}, @code{boolean?}, etc. | 427 @code{list?}, @code{number?}, @code{boolean?}, etc. |
466 @end itemize | 428 @end itemize |
467 | 429 |
468 The order of arguments (after the standard @var{layout} | 430 There is no limitation on the order of arguments (after the standard |
469 and @var{props} arguments) to a markup command defined with | 431 @var{layout} and @var{props} arguments). However, markup functions |
470 @code{define-markup-command} has to follow the above order backwards: | 432 taking a markup as their last argument are somewhat special as you can |
471 markup lists have to come last in the argument lists, preceded by | 433 apply them to a markup list, and the result is a markup list where the |
472 markups, preceded by scheme objects. | 434 markup function (with the specified leading arguments) has been applied |
473 | 435 to every element of the original markup list. |
474 Markup command signatures defined with a different order will cause | 436 |
475 @cindex Scheme signature | 437 Since replicating the leading arguments for applying a markup function |
476 @cindex signature, Scheme | 438 to a markup list is cheap mostly for Scheme arguments, you avoid |
477 @noindent | 439 performance pitfalls by just using Scheme arguments for the leading |
478 @command{lilypond} to complain about a bad Scheme signature at the time | 440 arguments of markup functions that take a markup as their last argument. |
479 of definition. | |
480 | 441 |
481 @node On properties | 442 @node On properties |
482 @unnumberedsubsubsec On properties | 443 @unnumberedsubsubsec On properties |
483 | 444 |
484 The @code{layout} and @code{props} arguments of markup commands bring a | 445 The @code{layout} and @code{props} arguments of markup commands bring a |
485 context for the markup interpretation: font size, line width, etc. | 446 context for the markup interpretation: font size, line width, etc. |
486 | 447 |
487 The @code{layout} argument allows access to properties defined in | 448 The @code{layout} argument allows access to properties defined in |
488 @code{paper} blocks, using the @code{ly:output-def-lookup} function. | 449 @code{paper} blocks, using the @code{ly:output-def-lookup} function. |
489 For instance, the line width (the same as the one used in scores) is | 450 For instance, the line width (the same as the one used in scores) is |
(...skipping 553 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1043 @end itemize | 1004 @end itemize |
1044 | 1005 |
1045 @node LilyPond Scheme interfaces | 1006 @node LilyPond Scheme interfaces |
1046 @chapter LilyPond Scheme interfaces | 1007 @chapter LilyPond Scheme interfaces |
1047 | 1008 |
1048 This chapter covers the various tools provided by LilyPond to help | 1009 This chapter covers the various tools provided by LilyPond to help |
1049 Scheme programmers get information into and out of the music streams. | 1010 Scheme programmers get information into and out of the music streams. |
1050 | 1011 |
1051 TODO -- figure out what goes in here and how to organize it | 1012 TODO -- figure out what goes in here and how to organize it |
1052 | 1013 |
LEFT | RIGHT |