2 @node Interfaces for programmers
3 @appendix Interfaces for programmers
8 * Programmer interfaces for input ::
9 * Markup programmer interface::
10 * Contexts for programmers::
13 @node Programmer interfaces for input
14 @appendixsec Programmer interfaces for input
17 * Input variables and Scheme::
18 * Internal music representation::
19 * Extending music syntax::
20 * Manipulating music expressions::
23 @node Input variables and Scheme
24 @appendixsubsec Input variables and Scheme
27 The input format supports the notion of variable: in the following
28 example, a music expression is assigned to a variable with the name
31 traLaLa = \notes @{ c'4 d'4 @}
36 There is also a form of scoping: in the following example, the
37 @code{\paper} block also contains a @code{traLaLa} variable, which is
38 independent of the outer @code{\traLaLa}.
40 traLaLa = \notes @{ c'4 d'4 @}
41 \paper @{ traLaLa = 1.0 @}
44 In effect, each input file is a scope, and all @code{\header},
45 @code{\midi} and @code{\paper} blocks are scopes nested inside that
48 Both variables and scoping are implemented in the GUILE module system.
49 An anonymous Scheme module is attached to each scope. An assignment of
52 traLaLa = \notes @{ c'4 d'4 @}
56 is internally converted to a Scheme definition
58 (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
61 This means that input variables and Scheme variables may be freely
62 mixed. In the following example, a music fragment is stored in the
63 variable @code{traLaLa}, and duplicated using Scheme. The result is
64 imported in a @code{\score} by means of a second variable
67 traLaLa = \notes @{ c'4 d'4 @}
69 #(define newLa (map ly:music-deep-copy
70 (list traLaLa traLaLa)))
72 (make-sequential-music newLa))
77 In the above example, music expressions can be `exported' from the
78 input to the Scheme interpreter. The opposite is also possible. By
79 wrapping a Scheme value in the function @code{ly:export}, a Scheme
80 value is interpreted as if it were entered in LilyPond syntax: instead
81 of defining @code{\twice}, the example above could also have been
85 \score @{ #(ly:export (make-sequential-music newLa)) @}
90 Mixing Scheme and lily identifiers is not possible with @code{--safe}.
92 @node Internal music representation
93 @appendixsubsec Internal music representation
95 When a music expression is parsed, it is converted into a set of
96 Scheme music objects. The defining property of a music object is that
97 it takes up time. Time is a rational number that measures the length
98 of a piece of music, in whole notes.
100 A music object has three kinds of types:
103 music name: Each music expression has a name, for example, a note
104 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
105 a @internalsref{SimultaneousMusic}. A list of all expressions
106 available is in the internals manual, under @internalsref{Music
110 `type' or interface: Each music name has several `types' or interface,
111 for example, a note is an @code{event}, but it is also a @code{note-event},
112 a @code{rhythmic-event} and a @code{melodic-event}.
114 All classes of music are listed in the internals manual, under
115 @internalsref{Music classes}.
117 C++ object: Each music object is represented by a C++ object. For technical
118 reasons, different music objects may be represented by different C++
119 object types. For example, a note is @code{Event} object, while
120 @code{\grace} creates a @code{Grace_music} object.
122 We expect that distinctions between different C++ types will disappear
126 The actual information of a music expression is stored in properties.
127 For example, a @internalsref{NoteEvent} has @code{pitch} and
128 @code{duration} properties that store the pitch and duration of that
129 note. A list of all properties available is in the internals manual,
130 under @internalsref{Music properties}.
132 A compound music expression is a music object that contains other
133 music objects in its properties. A list of objects can be stored in
134 the @code{elements} property of a music object, or a single `child'
135 music object in the @code{element} object. For example,
136 @internalsref{SequentialMusic} has its children in @code{elements},
137 and @internalsref{GraceMusic} has its single argument in
138 @code{element}. The body of a repeat is in @code{element} property of
139 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
144 @node Extending music syntax
145 @appendixsubsec Extending music syntax
147 The syntax of composite music expressions, like
148 @code{\repeat}, @code{\transpose} and @code{\context}
149 follows the general form of
152 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
155 Such syntax can also be defined as user code. To do this, it is
156 necessary to create a @emph{music function}. This is a specially marked
157 Scheme function. For example, the music function @code{\applymusic} applies
158 a user-defined function to a music expression. Its syntax is
161 \applymusic #@var{func} @var{music}
164 A music function is created with @code{ly:make-music-function},
167 (ly:make-music-function
170 @code{\applymusic} takes a Scheme function and a Music expression as
171 argument. This is encoded in its first argument,
174 (list procedure? ly:music?)
177 The function itself takes another argument, an Input location
178 object. That object is used to provide error messages with file names
179 and line numbers. The definition is the second argument of
180 @code{ly:make-music-function}. The body is function simply calls the
184 (lambda (where func music)
188 The above Scheme code only defines the functionality. The tag
189 @code{\applymusic} is selected by defining
192 apply = #(ly:make-music-function
193 (list procedure? ly:music?)
194 (lambda (where func music)
198 Examples of the use of @code{\applymusic} are in the next section.
201 @node Manipulating music expressions
202 @appendixsubsec Manipulating music expressions
204 Music objects and their properties can be accessed and manipulated
205 directly, through the @code{\applymusic} mechanism.
206 The syntax for @code{\applymusic} is
208 \applymusic #@var{func} @var{music}
212 This means that the scheme function @var{func} is called with
213 @var{music} as its argument. The return value of @var{func} is the
214 result of the entire expression. @var{func} may read and write music
215 properties using the functions @code{ly:music-property} and
216 @code{ly:music-set-property!}.
218 An example is a function that reverses the order of elements in
220 @lilypond[verbatim,raggedright]
221 #(define (rev-music-1 m)
222 (ly:music-set-property! m 'elements (reverse
223 (ly:music-property m 'elements)))
225 \score { \notes \applymusic #rev-music-1 { c4 d4 } }
228 The use of such a function is very limited. The effect of this
229 function is void when applied to an argument which is does not have
230 multiple children. The following function application has no effect:
233 \applymusic #rev-music-1 \grace @{ c4 d4 @}
237 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
238 @code{elements}, only a single @code{element}. Every generally
239 applicable function for @code{\applymusic} must -- like music expressions
240 themselves -- be recursive.
242 The following example is such a recursive function: It first extracts
243 the @code{elements} of an expression, reverses them and puts them
244 back. Then it recurses, both on @code{elements} and @code{element}
247 #(define (reverse-music music)
248 (let* ((elements (ly:music-property music 'elements))
249 (child (ly:music-property music 'element))
250 (reversed (reverse elements)))
253 (ly:music-set-property! music 'elements reversed)
256 (if (ly:music? child) (reverse-music child))
257 (map reverse-music reversed)
262 A slightly more elaborate example is in
263 @inputfileref{input/test,reverse-music.ly}.
265 Some of the input syntax is also implemented as recursive music
266 functions. For example, the syntax for polyphony
272 is actually implemented as a recursive function that replaces the
273 above by the internal equivalent of
275 << \context Voice = "1" @{ \voiceOne a @}
276 \context Voice = "2" @{ \voiceTwo b @} >>
279 Other applications of @code{\applymusic} are writing out repeats
280 automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
281 saving keystrokes (@inputfileref{input/test,music-box.ly}) and
283 LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
287 @file{scm/music-functions.scm}, @file{scm/music-types.scm},
288 @inputfileref{input/test,add-staccato.ly},
289 @inputfileref{input/test,unfold-all-repeats.ly}, and
290 @inputfileref{input/test,music-box.ly}.
294 @node Markup programmer interface
295 @appendixsec Markup programmer interface
299 * Markup construction in scheme::
300 * Markup command definition::
303 @node Markup construction in scheme
304 @appendixsubsec Markup construction in scheme
306 @cindex defining markup commands
308 The @code{markup} macro builds markup expressions in Scheme while
309 providing a LilyPond-like syntax. For example,
311 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
312 #:bigger #:line ("foo" "bar" "baz")))
318 \markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
319 \bigger @{ foo bar baz @} >
323 This example exposes the main translation rules between regular
324 LilyPond markup syntax and scheme markup syntax, which are summed up
326 @multitable @columnfractions .5 .5
327 @item @b{LilyPond} @tab @b{Scheme}
328 @item @code{\command} @tab @code{#:command}
329 @item @code{\variable} @tab @code{variable}
330 @item @code{@{ ... @}} @tab @code{#:line ( ... )}
331 @item @code{\center-align < ... >} @tab @code{#:center ( ... )}
332 @item @code{string} @tab @code{"string"}
333 @item @code{#scheme-arg} @tab @code{scheme-arg}
336 Besides, the whole scheme language is accessible inside the
337 @code{markup} macro: thus, one may use function calls inside
338 @code{markup} in order to manipulate character strings for
339 instance. This proves useful when defining new markup commands (see
340 @ref{Markup command definition}).
344 One can not feed the @code{#:line} (resp @code{#:center},
345 @code{#:column}) command with a variable or the result of a function
348 (markup #:line (fun-that-returns-markups))
350 is illegal. One should use the @code{make-line-markup} (resp
351 @code{make-center-markup}, @code{make-column-markup}) function
354 (markup (make-line-markup (fun-that-returns-markups)))
357 @node Markup command definition
358 @appendixsubsec Markup command definition
360 New markup commands can be defined
361 with the @code{def-markup-command} scheme macro.
363 (def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
364 (@var{arg1-type?} @var{arg2-type?} ...)
368 The arguments signify
372 @var{i}th command argument
374 a type predicate for the i@var{th} argument
376 the `paper' definition
378 a list of alists, containing all active properties.
381 As a simple example, we show how to add a @code{\smallcaps} command,
382 which selects @TeX{}'s small caps font. Normally, we could select the
383 small caps font as follows:
386 \markup { \override #'(font-shape . caps) Text-in-caps }
389 This selects the caps font by setting the @code{font-shape} property to
390 @code{#'caps} for interpreting @code{Text-in-caps}.
392 To make the above available as @code{\smallcaps} command, we have to
393 define a function using @code{def-markup-command}. The command should
394 take a single argument, of markup type. Therefore, the start of the
395 definition should read
397 (def-markup-command (smallcaps paper props argument) (markup?)
402 What follows is the content of the command: we should interpret
403 the @code{argument} as a markup, i.e.
406 (interpret-markup paper @dots{} argument)
410 This interpretation should add @code{'(font-shape . caps)} to the active
411 properties, so we substitute the following for the @dots{} in the
415 (cons (list '(font-shape . caps) ) props)
419 The variable @code{props} is a list of alists, and we prepend to it by
420 consing a list with the extra setting.
423 Suppose that we are typesetting a recitative in an opera, and
424 we would like to define a command that will show character names in a
425 custom manner. Names should be printed with small caps and translated a
426 bit to the left and top. We will define a @code{\character} command
427 that takes into account the needed translation, and uses the newly
428 defined @code{\smallcaps} command:
431 #(def-markup-command (character paper props name) (string?)
432 "Print the character name in small caps, translated to the left and
433 top. Syntax: \\character #\"name\""
434 (interpret-markup paper props
435 (markup "" #:translate (cons -4 2) #:smallcaps name)))
438 There is one complication that needs explanation: texts above and below
439 the staff are moved vertically to be at a certain distance (the
440 @code{padding} property) from the staff and the notes. To make sure
441 that this mechanism does not annihilate the vertical effect of our
442 @code{#:translate}, we add an empty string (@code{""}) before the
443 translated text. Now the @code{""} will be put above the notes, and the
444 @code{name} is moved in relation to that empty string. The net effect is
445 that the text is moved to the upper left.
447 The final result is as follows:
451 c''^\markup \character #"Cleopatra"
452 e'^\markup \character #"Giulio Cesare"
457 @lilypond[raggedright]
458 #(def-markup-command (smallcaps paper props str) (string?)
459 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
460 (interpret-markup paper props
463 (if (= (string-length s) 0)
465 (markup #:large (string-upcase (substring s 0 1))
466 #:translate (cons -0.6 0)
467 #:tiny (string-upcase (substring s 1)))))
468 (string-split str #\Space)))))
470 #(def-markup-command (character paper props name) (string?)
471 "Print the character name in small caps, translated to the left and
472 top. Syntax: \\character #\"name\""
473 (interpret-markup paper props
474 (markup "" #:translate (cons -4 0) #:smallcaps name)))
478 c''^\markup \character #"Cleopatra"
479 e'^\markup \character #"Giulio Cesare"
484 We have used the @code{caps} font shape, but suppose that our font
485 that does not have a small-caps variant. In that case, we have to fake
486 the small caps font, by setting a string in upcase, with the first
487 letter a little larger:
490 #(def-markup-command (smallcaps paper props str) (string?)
491 "Print the string argument in small caps."
492 (interpret-markup paper props
495 (if (= (string-length s) 0)
497 (markup #:large (string-upcase (substring s 0 1))
498 #:translate (cons -0.6 0)
499 #:tiny (string-upcase (substring s 1)))))
500 (string-split str #\Space)))))
503 The @code{smallcaps} command first splits its string argument into
504 tokens separated by spaces (@code{(string-split str #\Space)}); for
505 each token, a markup is built with the first letter made large and
506 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
507 second markup built with the following letters made tiny and upcased
508 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
509 introduces a space between markups on a line, the second markup is
510 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
511 the markups built for each token are put in a line by
512 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
513 to the @code{interpret-markup} function, with the @code{paper} and
514 @code{props} arguments.
518 @node Contexts for programmers
519 @appendixsec Contexts for programmers
523 * Context evaluation::
524 * Running a function on all layout objects::
527 @node Context evaluation
528 @appendixsubsec Context evaluation
530 @cindex calling code during interpreting
531 @cindex @code{\applycontext}
533 Contexts can be modified during interpretation with Scheme code. The
536 \applycontext @var{function}
539 @var{function} should be a Scheme function taking a single argument,
540 being the context to apply it to. The following code will print the
541 current bar number on the standard output during the compile:
546 (format #t "\nWe were called in barnumber ~a.\n"
547 (ly:context-property x 'currentBarNumber)))
552 @node Running a function on all layout objects
553 @appendixsubsec Running a function on all layout objects
556 @cindex calling code on layout objects
557 @cindex @code{\applyoutput}
560 The most versatile way of tuning an object is @code{\applyoutput}. Its
563 \applyoutput @var{proc}
567 where @var{proc} is a Scheme function, taking three arguments.
569 When interpreted, the function @var{proc} is called for every layout
570 object found in the context, with the following arguments:
572 @item the layout object itself,
573 @item the context where the layout object was created, and
574 @item the context where @code{\applyoutput} is processed.
578 In addition, the cause of the layout object, i.e. the music
579 expression or object that was responsible for creating it, is in the
580 object property @code{cause}. For example, for a note head, this is a
581 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
582 this is a @internalsref{NoteHead} object.
584 Here is a function to use for @code{\applyoutput}; it blanks
585 note-heads on the center-line:
588 (define (blanker grob grob-origin context)
589 (if (and (memq (ly:grob-property grob 'interfaces)
591 (eq? (ly:grob-property grob 'staff-position) 0))
593 (set! (ly:grob-property grob 'transparent) #t)))