1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Interfaces for programmers
3 @chapter Interfaces for programmers
8 * Programmer interfaces for input ::
9 * Markup programmer interface::
10 * Contexts for programmers::
13 @node Programmer interfaces for input
14 @section Programmer interfaces for input
17 * Input variables and Scheme::
18 * Internal music representation::
19 * Extending music syntax::
20 * Manipulating music expressions::
21 * Displaying music expressions::
22 * Using LilyPond syntax inside Scheme::
25 @node Input variables and Scheme
26 @subsection Input variables and Scheme
29 The input format supports the notion of variables: in the following
30 example, a music expression is assigned to a variable with the name
33 traLaLa = @{ c'4 d'4 @}
38 There is also a form of scoping: in the following example, the
39 @code{\layout} block also contains a @code{traLaLa} variable, which is
40 independent of the outer @code{\traLaLa}.
42 traLaLa = @{ c'4 d'4 @}
43 \layout @{ traLaLa = 1.0 @}
46 In effect, each input file is a scope, and all @code{\header},
47 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
50 Both variables and scoping are implemented in the GUILE module system.
51 An anonymous Scheme module is attached to each scope. An assignment of
54 traLaLa = @{ c'4 d'4 @}
58 is internally converted to a Scheme definition
60 (define traLaLa @var{Scheme value of ``@code{... }''})
63 This means that input variables and Scheme variables may be freely
64 mixed. In the following example, a music fragment is stored in the
65 variable @code{traLaLa}, and duplicated using Scheme. The result is
66 imported in a @code{\score} block by means of a second variable
69 traLaLa = @{ c'4 d'4 @}
71 #(define newLa (map ly:music-deep-copy
72 (list traLaLa traLaLa)))
74 (make-sequential-music newLa))
79 In the above example, music expressions can be `exported' from the
80 input to the Scheme interpreter. The opposite is also possible. By
81 wrapping a Scheme value in the function @code{ly:export}, a Scheme
82 value is interpreted as if it were entered in LilyPond syntax. Instead
83 of defining @code{\twice}, the example above could also have been
87 @{ #(ly:export (make-sequential-music (list newLa))) @}
92 Mixing Scheme and LilyPond identifiers is not possible with the
95 @node Internal music representation
96 @subsection Internal music representation
98 When a music expression is parsed, it is converted into a set of
99 Scheme music objects. The defining property of a music object is that
100 it takes up time. Time is a rational number that measures the length
101 of a piece of music, in whole notes.
103 A music object has three kinds of types:
106 music name: Each music expression has a name, for example, a note
107 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
108 a @internalsref{SimultaneousMusic}. A list of all expressions
109 available is in the internals manual, under
110 @internalsref{Music expressions}.
113 `type' or interface: Each music name has several `types' or
114 interfaces, for example, a note is an @code{event}, but it is also a
115 @code{note-event}, a @code{rhythmic-event}, and a @code{melodic-event}.
117 All classes of music are listed in the internals manual, under
118 @internalsref{Music classes}.
121 C++ object: Each music object is represented by a C++ object. For
122 technical reasons, different music objects may be represented by
123 different C++ object types. For example, a note is @code{Event}
124 object, while @code{\grace} creates a @code{Grace_music} object.
126 We expect that distinctions between different C++ types will disappear
130 The actual information of a music expression is stored in properties.
131 For example, a @internalsref{NoteEvent} has @code{pitch} and
132 @code{duration} properties that store the pitch and duration of that
133 note. A list of all properties available is in the internals manual,
134 under @internalsref{Music properties}.
136 A compound music expression is a music object that contains other
137 music objects in its properties. A list of objects can be stored in
138 the @code{elements} property of a music object, or a single `child'
139 music object in the @code{element} object. For example,
140 @internalsref{SequentialMusic} has its children in @code{elements},
141 and @internalsref{GraceMusic} has its single argument in
142 @code{element}. The body of a repeat is stored in the @code{element}
143 property of @internalsref{RepeatedMusic}, and the alternatives in
149 @node Extending music syntax
150 @subsection Extending music syntax
152 @c TODO: rewrite example.
153 @c The use of FUNC as example argument is rather confusing.
155 The syntax of composite music expressions, like @code{\repeat},
156 @code{\transpose}, and @code{\context} follows the general form of
159 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
162 Such syntax can also be defined as user code. To do this, it is
163 necessary to create a @emph{music function}. This is a specially marked
164 Scheme function. For example, the music function @code{\applymusic} applies
165 a user-defined function to a music expression. Its syntax is
168 \applymusic #@var{func} @var{music}
171 A music function is created with @code{ly:make-music-function},
174 (ly:make-music-function
177 @code{\applymusic} takes a Scheme function and a Music expression as
178 arguments. This is encoded in its parameter list,
181 (list procedure? ly:music?)
184 The function itself takes another argument, an Input location
185 object. That object is used to provide error messages with file names
186 and line numbers. The definition is the second argument of
187 @code{ly:make-music-function}. The body simply calls the function
190 (lambda (where func music)
194 The above Scheme code only defines the functionality. The tag
195 @code{\applymusic} is selected by defining
198 applymusic = #(ly:make-music-function
199 (list procedure? ly:music?)
200 (lambda (parser location func music)
204 A @code{def-music-function} macro is introduced on top of
205 @code{ly:make-music-function} to ease the definition of music
209 applymusic = #(def-music-function (parser location func music)
210 (procedure? ly:music?)
214 Examples of the use of @code{\applymusic} are in the next section.
217 @file{ly/@/music@/-functions@/-init@/.ly}.
219 @node Manipulating music expressions
220 @subsection Manipulating music expressions
222 Music objects and their properties can be accessed and manipulated
223 directly, through the @code{\applymusic} mechanism.
224 The syntax for @code{\applymusic} is
226 \applymusic #@var{func} @var{music}
230 This means that the Scheme function @var{func} is called with
231 @var{music} as its argument. The return value of @var{func} is the
232 result of the entire expression. @var{func} may read and write music
233 properties using the functions @code{ly:music-property} and
234 @code{ly:music-set-property!}.
236 An example is a function that reverses the order of elements in
238 @lilypond[quote,verbatim,raggedright]
239 #(define (rev-music-1 m)
240 (ly:music-set-property! m 'elements
241 (reverse (ly:music-property m 'elements)))
244 \applymusic #rev-music-1 { c'4 d'4 }
247 The use of such a function is very limited. The effect of this
248 function is void when applied to an argument that does not have
249 multiple children. The following function application has no effect
252 \applymusic #rev-music-1 \grace @{ c4 d4 @}
256 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which
257 has no @code{elements}, only a single @code{element}. Every generally
258 applicable function for @code{\applymusic} must -- like music expressions
259 themselves -- be recursive.
261 The following example is such a recursive function: It first extracts
262 the @code{elements} of an expression, reverses them and puts them
263 back. Then it recurses, both on @code{elements} and @code{element}
266 #(define (reverse-music music)
267 (let* ((elements (ly:music-property music 'elements))
268 (child (ly:music-property music 'element))
269 (reversed (reverse elements)))
272 (ly:music-set-property! music 'elements reversed)
275 (if (ly:music? child) (reverse-music child))
276 (map reverse-music reversed)
281 A slightly more elaborate example is in
282 @inputfileref{input/@/test,reverse@/-music@/.ly}.
284 Some of the input syntax is also implemented as recursive music
285 functions. For example, the syntax for polyphony
291 is actually implemented as a recursive function that replaces the
292 above by the internal equivalent of
294 << \context Voice = "1" @{ \voiceOne a @}
295 \context Voice = "2" @{ \voiceTwo b @} >>
298 Other applications of @code{\applymusic} are writing out repeats
299 automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}),
300 saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and
301 exporting LilyPond input to other formats
302 @c no @inputfileref{} here
303 (eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}).
307 @file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
308 @inputfileref{input/@/test,add@/-staccato@/.ly},
309 @inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
310 @inputfileref{input/@/test,music@/-box@/.ly}.
313 @node Displaying music expressions
314 @subsection Displaying music expressions
316 @cindex internal storage
317 @cindex @code{\displayMusic}
318 @cindex @code{\displayLilyMusic}
320 When writing a music function, it is often instructive to inspect how
321 a music expression is stored internally. This can be done with the
322 music function @code{\displayMusic}.
326 \displayMusic @{ c'4\f @}
330 Conversely, displaying a music expression in LilyPond notation can be
331 done using the music function @code{\displayLilyMusic}. For instance:
335 \displayLilyMusic \transpose c a, @{ c e g a bes @}
345 @node Using LilyPond syntax inside Scheme
346 @subsection Using LilyPond syntax inside Scheme
348 Creating music expressions in Scheme can be tedious, as they are
349 heavily nested and the resulting Scheme code is large. For some
350 simple tasks, this can be avoided, using common LilyPond syntax inside
351 Scheme, with the dedicated @code{#@{ ... #@}} syntax.
353 The following two expressions give equivalent music expressions:
355 mynotes = @{ \override Stem #'thickness = #4
358 #(define mynotes #@{ \override Stem #'thickness = #4
362 The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
363 ... @}} block, which is parsed. The resulting music expression, a
364 @code{SequentialMusic} music object, is then returned and usable in Scheme.
366 Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
367 expressions with the @code{$} character (@code{$$} can be used to
368 produce a single @code{$} character). This makes the creation of simple
369 functions straightforward. In the following example, a function
370 setting the TextScript's padding is defined:
372 @lilypond[quote,verbatim,raggedright]
373 #(use-modules (ice-9 optargs))
374 #(define* (textpad padding #:optional once?)
375 (ly:export ; this is necessary for using the expression
376 ; directly inside a block
378 #{ \once \override TextScript #'padding = #$padding #}
379 #{ \override TextScript #'padding = #$padding #})))
383 #(textpad 3.0 #t) % only once
392 Here, the variable @code{padding} is a number; music expression
393 variables may also be used in a similar fashion, as in the following
396 @lilypond[quote,verbatim,raggedright]
397 #(define (with-padding padding)
399 #{ \override TextScript #'padding = #$padding
401 \revert TextScript #'padding #}))
405 \applymusic #(with-padding 3) { c'^"2" c'^"3" }
410 The function created by @code{(with-padding 3)} adds @code{\override} and
411 @code{\revert} statements around the music given as an argument, and returns
412 this new expression. Thus, this example is equivalent to:
417 @{ \override TextScript #'padding = #3
419 \revert TextScript #'padding
425 This function may also be defined as a music function:
427 @lilypond[quote,verbatim,raggedright]
429 #(def-music-function (parser location padding music) (number? ly:music?)
430 #{ \override TextScript #'padding = #$padding
432 \revert TextScript #'padding #})
436 \withPadding #3 { c'^"2" c'^"3"}
442 @node Markup programmer interface
443 @section Markup programmer interface
445 @c Please rewrite the second sentence; I don't understand its meaning. AS
447 Markups are implemented as special Scheme functions. When applied
448 with as arguments an output definition (@code{\layout} or
449 @code{\paper}), and a list of properties and other arguments, produce
453 * Markup construction in Scheme::
454 * How markups work internally ::
455 * Markup command definition::
458 @node Markup construction in Scheme
459 @subsection Markup construction in Scheme
461 @cindex defining markup commands
463 The @code{markup} macro builds markup expressions in Scheme while
464 providing a LilyPond-like syntax. For example,
466 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
467 #:bigger #:line ("foo" "bar" "baz")))
473 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
474 \bigger \line @{ foo bar baz @} @}
478 This example exposes the main translation rules between regular
479 LilyPond markup syntax and Scheme markup syntax, which are summed up
483 @multitable @columnfractions .3 .3
484 @item @b{LilyPond} @tab @b{Scheme}
485 @item @code{\markup markup1 @}} @tab @code{(markup markup1)}
486 @item @code{\markup @{ markup1 markup2 ... @}} @tab
487 @code{(markup markup1 markup2 ... )}
488 @item @code{\command} @tab @code{#:command}
489 @item @code{\variable} @tab @code{variable}
490 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
491 @item @code{string} @tab @code{"string"}
492 @item @code{#scheme-arg} @tab @code{scheme-arg}
496 Besides, the whole scheme language is accessible inside the
497 @code{markup} macro: thus, one may use function calls inside
498 @code{markup} in order to manipulate character strings for
499 instance. This proves useful when defining new markup commands (see
500 @ref{Markup command definition}).
504 One can not feed the @code{#:line} (resp @code{#:center},
505 @code{#:column}) command with a variable or the result of a function
509 (markup #:line (fun-that-returns-markups))
513 is invalid. One should use the @code{make-line-markup} (resp.,
514 @code{make-center-markup} or @code{make-column-markup}) function
517 (markup (make-line-markup (fun-that-returns-markups)))
520 @node How markups work internally
521 @subsection How markups work internally
530 @code{\raise} is actually represented by the @code{raise-markup}
531 function. The markup expression is stored as
534 (list raise-markup 0.5 (list simple-markup "foo"))
537 When the markup is converted to printable objects (Stencils), the
538 @code{raise-markup} function is called as
543 @var{list of property alists}
545 @var{the "foo" markup})
548 The @code{raise-markup} function first creates the stencil for the
549 @code{foo} string, and then it raises that Stencil by 0.5 staff space.
550 This is a rather simple example; more complex examples are in the rest
551 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
553 @node Markup command definition
554 @subsection Markup command definition
556 New markup commands can be defined
557 with the @code{def-markup-command} scheme macro.
559 (def-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
560 (@var{arg1-type?} @var{arg2-type?} ...)
564 The arguments signify
568 @var{i}th command argument
570 a type predicate for the i@var{th} argument
572 the `layout' definition
574 a list of alists, containing all active properties.
577 As a simple example, we show how to add a @code{\smallcaps} command,
578 which selects @TeX{}'s small caps font. Normally, we could select the
579 small caps font as follows:
582 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
585 This selects the caps font by setting the @code{font-shape} property to
586 @code{#'caps} for interpreting @code{Text-in-caps}.
588 To make the above available as @code{\smallcaps} command, we have to
589 define a function using @code{def-markup-command}. The command should
590 take a single argument, of type markup. Therefore, the start of the
591 definition should read
593 (def-markup-command (smallcaps layout props argument) (markup?)
598 What follows is the content of the command: we should interpret
599 the @code{argument} as a markup, i.e.,
602 (interpret-markup layout @dots{} argument)
606 This interpretation should add @code{'(font-shape . caps)} to the active
607 properties, so we substitute the following for the @dots{} in the
611 (cons (list '(font-shape . caps) ) props)
615 The variable @code{props} is a list of alists, and we prepend to it by
616 cons'ing a list with the extra setting.
619 Suppose that we are typesetting a recitative in an opera, and
620 we would like to define a command that will show character names in a
621 custom manner. Names should be printed with small caps and translated a
622 bit to the left and top. We will define a @code{\character} command
623 that takes into account the necessary translation, and uses the newly
624 defined @code{\smallcaps} command:
627 #(def-markup-command (character layout props name) (string?)
628 "Print the character name in small caps, translated to the left and
629 top. Syntax: \\character #\"name\""
630 (interpret-markup layout props
631 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
634 There is one complication that needs explanation: texts above and below
635 the staff are moved vertically to be at a certain distance (the
636 @code{padding} property) from the staff and the notes. To make sure
637 that this mechanism does not annihilate the vertical effect of our
638 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
639 translated text. Now the @code{#:hspace 0} will be put above the notes, and the
640 @code{name} is moved in relation to that empty string. The net effect is
641 that the text is moved to the upper left.
643 The final result is as follows:
646 c''^\markup \character #"Cleopatra"
647 e'^\markup \character #"Giulio Cesare"
651 @lilypond[quote,raggedright]
652 #(def-markup-command (smallcaps layout props str) (string?)
653 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
654 (interpret-markup layout props
657 (if (= (string-length s) 0)
659 (markup #:large (string-upcase (substring s 0 1))
660 #:translate (cons -0.6 0)
661 #:tiny (string-upcase (substring s 1)))))
662 (string-split str #\Space)))))
664 #(def-markup-command (character layout props name) (string?)
665 "Print the character name in small caps, translated to the left and
666 top. Syntax: \\character #\"name\""
667 (interpret-markup layout props
668 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
671 c''^\markup \character #"Cleopatra" c'' c'' c''
672 e'^\markup \character #"Giulio Cesare" e' e' e'
676 We have used the @code{caps} font shape, but suppose that our font
677 does not have a small-caps variant. In that case we have to fake
678 the small caps font by setting a string in upcase with the first
679 letter a little larger:
682 #(def-markup-command (smallcaps layout props str) (string?)
683 "Print the string argument in small caps."
684 (interpret-markup layout props
687 (if (= (string-length s) 0)
689 (markup #:large (string-upcase (substring s 0 1))
690 #:translate (cons -0.6 0)
691 #:tiny (string-upcase (substring s 1)))))
692 (string-split str #\Space)))))
695 The @code{smallcaps} command first splits its string argument into
696 tokens separated by spaces (@code{(string-split str #\Space)}); for
697 each token, a markup is built with the first letter made large and
698 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
699 second markup built with the following letters made tiny and upcased
700 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
701 introduces a space between markups on a line, the second markup is
702 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
703 the markups built for each token are put in a line by
704 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
705 to the @code{interpret-markup} function, with the @code{layout} and
706 @code{props} arguments.
710 @node Contexts for programmers
711 @section Contexts for programmers
715 * Context evaluation::
716 * Running a function on all layout objects::
719 @node Context evaluation
720 @subsection Context evaluation
722 @cindex calling code during interpreting
723 @cindex @code{\applycontext}
725 Contexts can be modified during interpretation with Scheme code. The
728 \applycontext @var{function}
731 @var{function} should be a Scheme function taking a single argument,
732 being the context to apply it to. The following code will print the
733 current bar number on the standard output during the compile:
738 (format #t "\nWe were called in barnumber ~a.\n"
739 (ly:context-property x 'currentBarNumber)))
744 @node Running a function on all layout objects
745 @subsection Running a function on all layout objects
748 @cindex calling code on layout objects
749 @cindex @code{\applyoutput}
752 The most versatile way of tuning an object is @code{\applyoutput}. Its
755 \applyoutput @var{proc}
759 where @var{proc} is a Scheme function, taking three arguments.
761 When interpreted, the function @var{proc} is called for every layout
762 object found in the context, with the following arguments:
764 @item the layout object itself,
765 @item the context where the layout object was created, and
766 @item the context where @code{\applyoutput} is processed.
770 In addition, the cause of the layout object, i.e., the music
771 expression or object that was responsible for creating it, is in the
772 object property @code{cause}. For example, for a note head, this is a
773 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
774 this is a @internalsref{NoteHead} object.
776 Here is a function to use for @code{\applyoutput}; it blanks
777 note-heads on the center-line:
780 (define (blanker grob grob-origin context)
781 (if (and (memq (ly:grob-property grob 'interfaces)
783 (eq? (ly:grob-property grob 'staff-position) 0))
784 (set! (ly:grob-property grob 'transparent) #t)))