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::
21 * Using LilyPond syntax inside Scheme::
24 @node Input variables and Scheme
25 @appendixsubsec Input variables and Scheme
28 The input format supports the notion of variable: in the following
29 example, a music expression is assigned to a variable with the name
32 traLaLa = \notes @{ c'4 d'4 @}
37 There is also a form of scoping: in the following example, the
38 @code{\paper} block also contains a @code{traLaLa} variable, which is
39 independent of the outer @code{\traLaLa}.
41 traLaLa = \notes @{ c'4 d'4 @}
42 \paper @{ traLaLa = 1.0 @}
45 In effect, each input file is a scope, and all @code{\header},
46 @code{\midi} and @code{\paper} blocks are scopes nested inside that
49 Both variables and scoping are implemented in the GUILE module system.
50 An anonymous Scheme module is attached to each scope. An assignment of
53 traLaLa = \notes @{ c'4 d'4 @}
57 is internally converted to a Scheme definition
59 (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
62 This means that input variables and Scheme variables may be freely
63 mixed. In the following example, a music fragment is stored in the
64 variable @code{traLaLa}, and duplicated using Scheme. The result is
65 imported in a @code{\score} by means of a second variable
68 traLaLa = \notes @{ c'4 d'4 @}
70 #(define newLa (map ly:music-deep-copy
71 (list traLaLa traLaLa)))
73 (make-sequential-music newLa))
78 In the above example, music expressions can be `exported' from the
79 input to the Scheme interpreter. The opposite is also possible. By
80 wrapping a Scheme value in the function @code{ly:export}, a Scheme
81 value is interpreted as if it were entered in LilyPond syntax: instead
82 of defining @code{\twice}, the example above could also have been
86 \score @{ #(ly:export (make-sequential-music newLa)) @}
91 Mixing Scheme and lily identifiers is not possible with @code{--safe}.
93 @node Internal music representation
94 @appendixsubsec Internal music representation
96 When a music expression is parsed, it is converted into a set of
97 Scheme music objects. The defining property of a music object is that
98 it takes up time. Time is a rational number that measures the length
99 of a piece of music, in whole notes.
101 A music object has three kinds of types:
104 music name: Each music expression has a name, for example, a note
105 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
106 a @internalsref{SimultaneousMusic}. A list of all expressions
107 available is in the internals manual, under @internalsref{Music
111 `type' or interface: Each music name has several `types' or interface,
112 for example, a note is an @code{event}, but it is also a @code{note-event},
113 a @code{rhythmic-event} and a @code{melodic-event}.
115 All classes of music are listed in the internals manual, under
116 @internalsref{Music classes}.
118 C++ object: Each music object is represented by a C++ object. For technical
119 reasons, different music objects may be represented by different C++
120 object types. For example, a note is @code{Event} object, while
121 @code{\grace} creates a @code{Grace_music} object.
123 We expect that distinctions between different C++ types will disappear
127 The actual information of a music expression is stored in properties.
128 For example, a @internalsref{NoteEvent} has @code{pitch} and
129 @code{duration} properties that store the pitch and duration of that
130 note. A list of all properties available is in the internals manual,
131 under @internalsref{Music properties}.
133 A compound music expression is a music object that contains other
134 music objects in its properties. A list of objects can be stored in
135 the @code{elements} property of a music object, or a single `child'
136 music object in the @code{element} object. For example,
137 @internalsref{SequentialMusic} has its children in @code{elements},
138 and @internalsref{GraceMusic} has its single argument in
139 @code{element}. The body of a repeat is in @code{element} property of
140 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
145 @node Extending music syntax
146 @appendixsubsec Extending music syntax
148 The syntax of composite music expressions, like
149 @code{\repeat}, @code{\transpose} and @code{\context}
150 follows the general form of
153 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
156 Such syntax can also be defined as user code. To do this, it is
157 necessary to create a @emph{music function}. This is a specially marked
158 Scheme function. For example, the music function @code{\applymusic} applies
159 a user-defined function to a music expression. Its syntax is
162 \applymusic #@var{func} @var{music}
165 A music function is created with @code{ly:make-music-function},
168 (ly:make-music-function
171 @code{\applymusic} takes a Scheme function and a Music expression as
172 argument. This is encoded in its first argument,
175 (list procedure? ly:music?)
178 The function itself takes another argument, an Input location
179 object. That object is used to provide error messages with file names
180 and line numbers. The definition is the second argument of
181 @code{ly:make-music-function}. The body is function simply calls the
185 (lambda (where func music)
189 The above Scheme code only defines the functionality. The tag
190 @code{\applymusic} is selected by defining
193 applymusic = #(ly:make-music-function
194 (list procedure? ly:music?)
195 (lambda (location func music)
199 A @code{def-music-function} macro is introduced on top of
200 @code{ly:make-music-function} to ease the definition of music
204 applymusic = #(def-music-function (location func music) (procedure? ly:music?)
208 Examples of the use of @code{\applymusic} are in the next section.
211 @file{ly/music-functions-init.ly}.
213 @node Manipulating music expressions
214 @appendixsubsec Manipulating music expressions
216 Music objects and their properties can be accessed and manipulated
217 directly, through the @code{\applymusic} mechanism.
218 The syntax for @code{\applymusic} is
220 \applymusic #@var{func} @var{music}
224 This means that the scheme function @var{func} is called with
225 @var{music} as its argument. The return value of @var{func} is the
226 result of the entire expression. @var{func} may read and write music
227 properties using the functions @code{ly:music-property} and
228 @code{ly:music-set-property!}.
230 An example is a function that reverses the order of elements in
232 @lilypond[verbatim,raggedright]
233 #(define (rev-music-1 m)
234 (ly:music-set-property! m 'elements (reverse
235 (ly:music-property m 'elements)))
237 \score { \notes \applymusic #rev-music-1 { c4 d4 } }
240 The use of such a function is very limited. The effect of this
241 function is void when applied to an argument which is does not have
242 multiple children. The following function application has no effect:
245 \applymusic #rev-music-1 \grace @{ c4 d4 @}
249 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
250 @code{elements}, only a single @code{element}. Every generally
251 applicable function for @code{\applymusic} must -- like music expressions
252 themselves -- be recursive.
254 The following example is such a recursive function: It first extracts
255 the @code{elements} of an expression, reverses them and puts them
256 back. Then it recurses, both on @code{elements} and @code{element}
259 #(define (reverse-music music)
260 (let* ((elements (ly:music-property music 'elements))
261 (child (ly:music-property music 'element))
262 (reversed (reverse elements)))
265 (ly:music-set-property! music 'elements reversed)
268 (if (ly:music? child) (reverse-music child))
269 (map reverse-music reversed)
274 A slightly more elaborate example is in
275 @inputfileref{input/test,reverse-music.ly}.
277 Some of the input syntax is also implemented as recursive music
278 functions. For example, the syntax for polyphony
284 is actually implemented as a recursive function that replaces the
285 above by the internal equivalent of
287 << \context Voice = "1" @{ \voiceOne a @}
288 \context Voice = "2" @{ \voiceTwo b @} >>
291 Other applications of @code{\applymusic} are writing out repeats
292 automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
293 saving keystrokes (@inputfileref{input/test,music-box.ly}) and
295 LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
299 @file{scm/music-functions.scm}, @file{scm/music-types.scm},
300 @inputfileref{input/test,add-staccato.ly},
301 @inputfileref{input/test,unfold-all-repeats.ly}, and
302 @inputfileref{input/test,music-box.ly}.
305 @node Using LilyPond syntax inside Scheme
306 @appendixsubsec Using LilyPond syntax inside Scheme
308 Creating music expressions in scheme can be tedious, as they are
309 heavily nested and the resulting scheme code is large. For some
310 simple tasks, this can be avoided, using LilyPond usual syntax inside
311 scheme, with the dedicated @code{#@{ ... #@}} syntax.
313 The following two expressions give equivalent music expressions:
315 mynotes = @{ \override Stem #'thickness = #4
316 \notes @{ c'8 d' @} @}
318 #(define mynotes #@{ \override Stem #'thickness = #4
319 \notes @{ c'8 d' @} #@})
322 The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
323 ... @}} block, which is parsed. The resulting music expression, a
324 @code{SequentialMusic} music object, is then returned and usable in scheme.
326 Arbitrary scheme forms, including variables, can be used in @code{#@{ ... #@}}
327 expressions with the @code{$} character (@code{$$} can be used to
328 produce a single $ character). This makes the creation of simple
329 functions straightforward. In the following example, a function
330 setting the TextScript's padding is defined:
332 @lilypond[verbatim,raggedright]
333 #(use-modules (ice-9 optargs))
334 #(define* (textpad padding #:optional once?)
335 (ly:export ; this is necessary for using the expression
336 ; directly inside a \notes block
338 #{ \once \override TextScript #'padding = #$padding #}
339 #{ \override TextScript #'padding = #$padding #})))
344 #(textpad 3.0 #t) % only once
355 Here, the variable @code{padding} is a number; music expression
356 variables may also be used in a similar fashion, as in the following
359 @lilypond[verbatim,raggedright]
360 #(define (with-padding padding)
362 #{ \override TextScript #'padding = #$padding
364 \revert TextScript #'padding #}))
369 \applymusic #(with-padding 3)
376 The function created by @code{(with-padding 3)} adds @code{\override} and
377 @code{\revert} statements around the music given as an argument, and returns
378 this new expression. Thus, this example is equivalent to:
384 @{ \override TextScript #'padding = #3
386 \revert TextScript #'padding
393 This function may also be defined as a music function:
395 @lilypond[verbatim,raggedright]
396 withPadding = #(def-music-function (location padding music) (number? ly:music?)
397 #{ \override TextScript #'padding = #$padding
399 \revert TextScript #'padding #})
412 @node Markup programmer interface
413 @appendixsec Markup programmer interface
417 * Markup construction in scheme::
418 * Markup command definition::
421 @node Markup construction in scheme
422 @appendixsubsec Markup construction in scheme
424 @cindex defining markup commands
426 The @code{markup} macro builds markup expressions in Scheme while
427 providing a LilyPond-like syntax. For example,
429 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
430 #:bigger #:line ("foo" "bar" "baz")))
436 \markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
437 \bigger @{ foo bar baz @} >
441 This example exposes the main translation rules between regular
442 LilyPond markup syntax and scheme markup syntax, which are summed up
444 @multitable @columnfractions .5 .5
445 @item @b{LilyPond} @tab @b{Scheme}
446 @item @code{\command} @tab @code{#:command}
447 @item @code{\variable} @tab @code{variable}
448 @item @code{@{ ... @}} @tab @code{#:line ( ... )}
449 @item @code{\center-align < ... >} @tab @code{#:center ( ... )}
450 @item @code{string} @tab @code{"string"}
451 @item @code{#scheme-arg} @tab @code{scheme-arg}
454 Besides, the whole scheme language is accessible inside the
455 @code{markup} macro: thus, one may use function calls inside
456 @code{markup} in order to manipulate character strings for
457 instance. This proves useful when defining new markup commands (see
458 @ref{Markup command definition}).
462 One can not feed the @code{#:line} (resp @code{#:center},
463 @code{#:column}) command with a variable or the result of a function
466 (markup #:line (fun-that-returns-markups))
468 is illegal. One should use the @code{make-line-markup} (resp
469 @code{make-center-markup}, @code{make-column-markup}) function
472 (markup (make-line-markup (fun-that-returns-markups)))
475 @node Markup command definition
476 @appendixsubsec Markup command definition
478 New markup commands can be defined
479 with the @code{def-markup-command} scheme macro.
481 (def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
482 (@var{arg1-type?} @var{arg2-type?} ...)
486 The arguments signify
490 @var{i}th command argument
492 a type predicate for the i@var{th} argument
494 the `paper' definition
496 a list of alists, containing all active properties.
499 As a simple example, we show how to add a @code{\smallcaps} command,
500 which selects @TeX{}'s small caps font. Normally, we could select the
501 small caps font as follows:
504 \markup { \override #'(font-shape . caps) Text-in-caps }
507 This selects the caps font by setting the @code{font-shape} property to
508 @code{#'caps} for interpreting @code{Text-in-caps}.
510 To make the above available as @code{\smallcaps} command, we have to
511 define a function using @code{def-markup-command}. The command should
512 take a single argument, of markup type. Therefore, the start of the
513 definition should read
515 (def-markup-command (smallcaps paper props argument) (markup?)
520 What follows is the content of the command: we should interpret
521 the @code{argument} as a markup, i.e.
524 (interpret-markup paper @dots{} argument)
528 This interpretation should add @code{'(font-shape . caps)} to the active
529 properties, so we substitute the following for the @dots{} in the
533 (cons (list '(font-shape . caps) ) props)
537 The variable @code{props} is a list of alists, and we prepend to it by
538 consing a list with the extra setting.
541 Suppose that we are typesetting a recitative in an opera, and
542 we would like to define a command that will show character names in a
543 custom manner. Names should be printed with small caps and translated a
544 bit to the left and top. We will define a @code{\character} command
545 that takes into account the needed translation, and uses the newly
546 defined @code{\smallcaps} command:
549 #(def-markup-command (character paper props name) (string?)
550 "Print the character name in small caps, translated to the left and
551 top. Syntax: \\character #\"name\""
552 (interpret-markup paper props
553 (markup "" #:translate (cons -4 2) #:smallcaps name)))
556 There is one complication that needs explanation: texts above and below
557 the staff are moved vertically to be at a certain distance (the
558 @code{padding} property) from the staff and the notes. To make sure
559 that this mechanism does not annihilate the vertical effect of our
560 @code{#:translate}, we add an empty string (@code{""}) before the
561 translated text. Now the @code{""} will be put above the notes, and the
562 @code{name} is moved in relation to that empty string. The net effect is
563 that the text is moved to the upper left.
565 The final result is as follows:
569 c''^\markup \character #"Cleopatra"
570 e'^\markup \character #"Giulio Cesare"
575 @lilypond[raggedright]
576 #(def-markup-command (smallcaps paper props str) (string?)
577 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
578 (interpret-markup paper props
581 (if (= (string-length s) 0)
583 (markup #:large (string-upcase (substring s 0 1))
584 #:translate (cons -0.6 0)
585 #:tiny (string-upcase (substring s 1)))))
586 (string-split str #\Space)))))
588 #(def-markup-command (character paper props name) (string?)
589 "Print the character name in small caps, translated to the left and
590 top. Syntax: \\character #\"name\""
591 (interpret-markup paper props
592 (markup "" #:translate (cons -4 0) #:smallcaps name)))
596 c''^\markup \character #"Cleopatra"
597 e'^\markup \character #"Giulio Cesare"
602 We have used the @code{caps} font shape, but suppose that our font
603 that does not have a small-caps variant. In that case, we have to fake
604 the small caps font, by setting a string in upcase, with the first
605 letter a little larger:
608 #(def-markup-command (smallcaps paper props str) (string?)
609 "Print the string argument in small caps."
610 (interpret-markup paper props
613 (if (= (string-length s) 0)
615 (markup #:large (string-upcase (substring s 0 1))
616 #:translate (cons -0.6 0)
617 #:tiny (string-upcase (substring s 1)))))
618 (string-split str #\Space)))))
621 The @code{smallcaps} command first splits its string argument into
622 tokens separated by spaces (@code{(string-split str #\Space)}); for
623 each token, a markup is built with the first letter made large and
624 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
625 second markup built with the following letters made tiny and upcased
626 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
627 introduces a space between markups on a line, the second markup is
628 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
629 the markups built for each token are put in a line by
630 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
631 to the @code{interpret-markup} function, with the @code{paper} and
632 @code{props} arguments.
636 @node Contexts for programmers
637 @appendixsec Contexts for programmers
641 * Context evaluation::
642 * Running a function on all layout objects::
645 @node Context evaluation
646 @appendixsubsec Context evaluation
648 @cindex calling code during interpreting
649 @cindex @code{\applycontext}
651 Contexts can be modified during interpretation with Scheme code. The
654 \applycontext @var{function}
657 @var{function} should be a Scheme function taking a single argument,
658 being the context to apply it to. The following code will print the
659 current bar number on the standard output during the compile:
664 (format #t "\nWe were called in barnumber ~a.\n"
665 (ly:context-property x 'currentBarNumber)))
670 @node Running a function on all layout objects
671 @appendixsubsec Running a function on all layout objects
674 @cindex calling code on layout objects
675 @cindex @code{\applyoutput}
678 The most versatile way of tuning an object is @code{\applyoutput}. Its
681 \applyoutput @var{proc}
685 where @var{proc} is a Scheme function, taking three arguments.
687 When interpreted, the function @var{proc} is called for every layout
688 object found in the context, with the following arguments:
690 @item the layout object itself,
691 @item the context where the layout object was created, and
692 @item the context where @code{\applyoutput} is processed.
696 In addition, the cause of the layout object, i.e. the music
697 expression or object that was responsible for creating it, is in the
698 object property @code{cause}. For example, for a note head, this is a
699 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
700 this is a @internalsref{NoteHead} object.
702 Here is a function to use for @code{\applyoutput}; it blanks
703 note-heads on the center-line:
706 (define (blanker grob grob-origin context)
707 (if (and (memq (ly:grob-property grob 'interfaces)
709 (eq? (ly:grob-property grob 'staff-position) 0))
711 (set! (ly:grob-property grob 'transparent) #t)))