Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(69)

Delta Between Two Patch Sets: Documentation/extending/programming-interface.itely

Issue 969046: Don't hardcode a limited set of markup signatures. (Closed)
Left Patch Set: Check markup command signatures at definition time. Created 13 years, 11 months ago
Right Patch Set: Remove order restrictions on markup command arguments. Created 13 years, 10 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | lily/lexer.ll » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
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
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
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
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
LEFTRIGHT
« no previous file | lily/lexer.ll » ('j') | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b