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))) @}
90 Scheme code is evaluated as soon as the parser encounters it. To
91 define some scheme code in a macro (to be called later), use
95 (ly:set-option 'point-and-click #f))
105 Mixing Scheme and LilyPond identifiers is not possible with the
106 @code{--safe} option.
109 @node Internal music representation
110 @subsection Internal music representation
112 When a music expression is parsed, it is converted into a set of
113 Scheme music objects. The defining property of a music object is that
114 it takes up time. Time is a rational number that measures the length
115 of a piece of music, in whole notes.
117 A music object has three kinds of types:
120 music name: Each music expression has a name, for example, a note
121 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
122 a @internalsref{SimultaneousMusic}. A list of all expressions
123 available is in the internals manual, under
124 @internalsref{Music expressions}.
127 `type' or interface: Each music name has several `types' or
128 interfaces, for example, a note is an @code{event}, but it is also a
129 @code{note-event}, a @code{rhythmic-event}, and a @code{melodic-event}.
131 All classes of music are listed in the internals manual, under
132 @internalsref{Music classes}.
135 C++ object: Each music object is represented by a C++ object. For
136 technical reasons, different music objects may be represented by
137 different C++ object types. For example, a note is @code{Event}
138 object, while @code{\grace} creates a @code{Grace_music} object.
140 We expect that distinctions between different C++ types will disappear
144 The actual information of a music expression is stored in properties.
145 For example, a @internalsref{NoteEvent} has @code{pitch} and
146 @code{duration} properties that store the pitch and duration of that
147 note. A list of all properties available is in the internals manual,
148 under @internalsref{Music properties}.
150 A compound music expression is a music object that contains other
151 music objects in its properties. A list of objects can be stored in
152 the @code{elements} property of a music object, or a single `child'
153 music object in the @code{element} object. For example,
154 @internalsref{SequentialMusic} has its children in @code{elements},
155 and @internalsref{GraceMusic} has its single argument in
156 @code{element}. The body of a repeat is stored in the @code{element}
157 property of @internalsref{RepeatedMusic}, and the alternatives in
163 @node Extending music syntax
164 @subsection Extending music syntax
166 @c TODO: rewrite example.
167 @c The use of FUNC as example argument is rather confusing.
169 The syntax of composite music expressions, like @code{\repeat},
170 @code{\transpose}, and @code{\context} follows the general form of
173 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
176 Such syntax can also be defined as user code. To do this, it is
177 necessary to create a @emph{music function}. This is a specially marked
178 Scheme function. For example, the music function @code{\applyMusic} applies
179 a user-defined function to a music expression. Its syntax is
182 \applyMusic #@var{func} @var{music}
185 A music function is created with @code{ly:make-music-function},
188 (ly:make-music-function
191 @code{\applyMusic} takes a Scheme function and a Music expression as
192 arguments. This is encoded in its parameter list,
195 (list procedure? ly:music?)
198 The function itself takes another argument, an Input location
199 object. That object is used to provide error messages with file names
200 and line numbers. The definition is the second argument of
201 @code{ly:make-music-function}. The body simply calls the function
204 (lambda (where func music)
208 The above Scheme code only defines the functionality. The tag
209 @code{\applyMusic} is selected by defining
212 applyMusic = #(ly:make-music-function
213 (list procedure? ly:music?)
214 (lambda (parser location func music)
218 A @code{def-music-function} macro is introduced on top of
219 @code{ly:make-music-function} to ease the definition of music
223 applyMusic = #(def-music-function (parser location func music)
224 (procedure? ly:music?)
228 Examples of the use of @code{\applyMusic} are in the next section.
231 @file{ly/@/music@/-functions@/-init@/.ly}.
233 @node Manipulating music expressions
234 @subsection Manipulating music expressions
236 Music objects and their properties can be accessed and manipulated
237 directly, through the @code{\applyMusic} mechanism.
238 The syntax for @code{\applyMusic} is
240 \applyMusic #@var{func} @var{music}
244 This means that the Scheme function @var{func} is called with
245 @var{music} as its argument. The return value of @var{func} is the
246 result of the entire expression. @var{func} may read and write music
247 properties using the functions @code{ly:music-property} and
248 @code{ly:music-set-property!}.
250 An example is a function that reverses the order of elements in
252 @lilypond[quote,verbatim,ragged-right]
253 #(define (rev-music-1 m)
254 (ly:music-set-property! m 'elements
255 (reverse (ly:music-property m 'elements)))
258 \applyMusic #rev-music-1 { c'4 d'4 }
261 The use of such a function is very limited. The effect of this
262 function is void when applied to an argument that does not have
263 multiple children. The following function application has no effect
266 \applyMusic #rev-music-1 \grace @{ c4 d4 @}
270 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which
271 has no @code{elements}, only a single @code{element}. Every generally
272 applicable function for @code{\applyMusic} must -- like music expressions
273 themselves -- be recursive.
275 The following example is such a recursive function: It first extracts
276 the @code{elements} of an expression, reverses them and puts them
277 back. Then it recurses, both on @code{elements} and @code{element}
280 #(define (reverse-music music)
281 (let* ((elements (ly:music-property music 'elements))
282 (child (ly:music-property music 'element))
283 (reversed (reverse elements)))
286 (ly:music-set-property! music 'elements reversed)
289 (if (ly:music? child) (reverse-music child))
290 (map reverse-music reversed)
295 A slightly more elaborate example is in
296 @inputfileref{input/@/test,reverse@/-music@/.ly}.
298 Some of the input syntax is also implemented as recursive music
299 functions. For example, the syntax for polyphony
305 is actually implemented as a recursive function that replaces the
306 above by the internal equivalent of
308 << \context Voice = "1" @{ \voiceOne a @}
309 \context Voice = "2" @{ \voiceTwo b @} >>
312 Other applications of @code{\applyMusic} are writing out repeats
313 automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}),
314 saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and
315 exporting LilyPond input to other formats
316 @c no @inputfileref{} here
317 (eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}).
321 @file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
322 @inputfileref{input/@/test,add@/-staccato@/.ly},
323 @inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
324 @inputfileref{input/@/test,music@/-box@/.ly}.
327 @node Displaying music expressions
328 @subsection Displaying music expressions
330 @cindex internal storage
331 @cindex @code{\displayMusic}
332 @cindex @code{\displayLilyMusic}
334 When writing a music function, it is often instructive to inspect how
335 a music expression is stored internally. This can be done with the
336 music function @code{\displayMusic}.
340 \displayMusic @{ c'4\f @}
344 Conversely, displaying a music expression in LilyPond notation can be
345 done using the music function @code{\displayLilyMusic}. For instance:
349 \displayLilyMusic \transpose c a, @{ c e g a bes @}
359 @node Using LilyPond syntax inside Scheme
360 @subsection Using LilyPond syntax inside Scheme
362 Creating music expressions in Scheme can be tedious, as they are
363 heavily nested and the resulting Scheme code is large. For some
364 simple tasks, this can be avoided, using common LilyPond syntax inside
365 Scheme, with the dedicated @code{#@{ ... #@}} syntax.
367 The following two expressions give equivalent music expressions:
369 mynotes = @{ \override Stem #'thickness = #4
372 #(define mynotes #@{ \override Stem #'thickness = #4
376 The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
377 ... @}} block, which is parsed. The resulting music expression, a
378 @code{SequentialMusic} music object, is then returned and usable in Scheme.
380 Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
381 expressions with the @code{$} character (@code{$$} can be used to
382 produce a single @code{$} character). This makes the creation of simple
383 functions straightforward. In the following example, a function
384 setting the TextScript's padding is defined:
386 @lilypond[quote,verbatim,ragged-right]
387 #(use-modules (ice-9 optargs))
388 #(define* (textpad padding #:optional once?)
389 (ly:export ; this is necessary for using the expression
390 ; directly inside a block
392 #{ \once \override TextScript #'padding = #$padding #}
393 #{ \override TextScript #'padding = #$padding #})))
397 #(textpad 3.0 #t) % only once
406 Here, the variable @code{padding} is a number; music expression
407 variables may also be used in a similar fashion, as in the following
410 @lilypond[quote,verbatim,ragged-right]
411 #(define (with-padding padding)
413 #{ \override TextScript #'padding = #$padding
415 \revert TextScript #'padding #}))
419 \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
424 The function created by @code{(with-padding 3)} adds @code{\override} and
425 @code{\revert} statements around the music given as an argument, and returns
426 this new expression. Thus, this example is equivalent to:
431 @{ \override TextScript #'padding = #3
433 \revert TextScript #'padding
439 This function may also be defined as a music function:
441 @lilypond[quote,verbatim,ragged-right]
443 #(def-music-function (parser location padding music) (number? ly:music?)
444 #{ \override TextScript #'padding = #$padding
446 \revert TextScript #'padding #})
450 \withPadding #3 { c'^"2" c'^"3"}
456 @node Markup programmer interface
457 @section Markup programmer interface
459 @c Please rewrite the second sentence; I don't understand its meaning. AS
461 Markups are implemented as special Scheme functions. When applied
462 with as arguments an output definition (@code{\layout} or
463 @code{\paper}), and a list of properties and other arguments, produce
467 * Markup construction in Scheme::
468 * How markups work internally ::
469 * Markup command definition::
472 @node Markup construction in Scheme
473 @subsection Markup construction in Scheme
475 @cindex defining markup commands
477 The @code{markup} macro builds markup expressions in Scheme while
478 providing a LilyPond-like syntax. For example,
480 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
481 #:bigger #:line ("foo" "bar" "baz")))
487 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
488 \bigger \line @{ foo bar baz @} @}
492 This example exposes the main translation rules between regular
493 LilyPond markup syntax and Scheme markup syntax, which are summed up
497 @multitable @columnfractions .3 .3
498 @item @b{LilyPond} @tab @b{Scheme}
499 @item @code{\markup markup1 @}} @tab @code{(markup markup1)}
500 @item @code{\markup @{ markup1 markup2 ... @}} @tab
501 @code{(markup markup1 markup2 ... )}
502 @item @code{\command} @tab @code{#:command}
503 @item @code{\variable} @tab @code{variable}
504 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
505 @item @code{string} @tab @code{"string"}
506 @item @code{#scheme-arg} @tab @code{scheme-arg}
510 Besides, the whole scheme language is accessible inside the
511 @code{markup} macro: thus, one may use function calls inside
512 @code{markup} in order to manipulate character strings for
513 instance. This proves useful when defining new markup commands (see
514 @ref{Markup command definition}).
518 One can not feed the @code{#:line} (resp @code{#:center},
519 @code{#:column}) command with a variable or the result of a function
523 (markup #:line (fun-that-returns-markups))
527 is invalid. One should use the @code{make-line-markup} (resp.,
528 @code{make-center-markup} or @code{make-column-markup}) function
531 (markup (make-line-markup (fun-that-returns-markups)))
534 @node How markups work internally
535 @subsection How markups work internally
544 @code{\raise} is actually represented by the @code{raise-markup}
545 function. The markup expression is stored as
548 (list raise-markup 0.5 (list simple-markup "foo"))
551 When the markup is converted to printable objects (Stencils), the
552 @code{raise-markup} function is called as
557 @var{list of property alists}
559 @var{the "foo" markup})
562 The @code{raise-markup} function first creates the stencil for the
563 @code{foo} string, and then it raises that Stencil by 0.5 staff space.
564 This is a rather simple example; more complex examples are in the rest
565 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
567 @node Markup command definition
568 @subsection Markup command definition
570 New markup commands can be defined
571 with the @code{def-markup-command} scheme macro.
573 (def-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
574 (@var{arg1-type?} @var{arg2-type?} ...)
578 The arguments signify
582 @var{i}th command argument
584 a type predicate for the i@var{th} argument
586 the `layout' definition
588 a list of alists, containing all active properties.
591 As a simple example, we show how to add a @code{\smallcaps} command,
592 which selects @TeX{}'s small caps font. Normally, we could select the
593 small caps font as follows:
596 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
599 This selects the caps font by setting the @code{font-shape} property to
600 @code{#'caps} for interpreting @code{Text-in-caps}.
602 To make the above available as @code{\smallcaps} command, we have to
603 define a function using @code{def-markup-command}. The command should
604 take a single argument, of type markup. Therefore, the start of the
605 definition should read
607 (def-markup-command (smallcaps layout props argument) (markup?)
612 What follows is the content of the command: we should interpret
613 the @code{argument} as a markup, i.e.,
616 (interpret-markup layout @dots{} argument)
620 This interpretation should add @code{'(font-shape . caps)} to the active
621 properties, so we substitute the following for the @dots{} in the
625 (cons (list '(font-shape . caps) ) props)
629 The variable @code{props} is a list of alists, and we prepend to it by
630 cons'ing a list with the extra setting.
633 Suppose that we are typesetting a recitative in an opera, and
634 we would like to define a command that will show character names in a
635 custom manner. Names should be printed with small caps and translated a
636 bit to the left and top. We will define a @code{\character} command
637 that takes into account the necessary translation, and uses the newly
638 defined @code{\smallcaps} command:
641 #(def-markup-command (character layout props name) (string?)
642 "Print the character name in small caps, translated to the left and
643 top. Syntax: \\character #\"name\""
644 (interpret-markup layout props
645 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
648 There is one complication that needs explanation: texts above and below
649 the staff are moved vertically to be at a certain distance (the
650 @code{padding} property) from the staff and the notes. To make sure
651 that this mechanism does not annihilate the vertical effect of our
652 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
653 translated text. Now the @code{#:hspace 0} will be put above the notes, and the
654 @code{name} is moved in relation to that empty string. The net effect is
655 that the text is moved to the upper left.
657 The final result is as follows:
660 c''^\markup \character #"Cleopatra"
661 e'^\markup \character #"Giulio Cesare"
665 @lilypond[quote,ragged-right]
666 #(def-markup-command (smallcaps layout props str) (string?)
667 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
668 (interpret-markup layout props
671 (if (= (string-length s) 0)
673 (markup #:large (string-upcase (substring s 0 1))
674 #:translate (cons -0.6 0)
675 #:tiny (string-upcase (substring s 1)))))
676 (string-split str #\Space)))))
678 #(def-markup-command (character layout props name) (string?)
679 "Print the character name in small caps, translated to the left and
680 top. Syntax: \\character #\"name\""
681 (interpret-markup layout props
682 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
685 c''^\markup \character #"Cleopatra" c'' c'' c''
686 e'^\markup \character #"Giulio Cesare" e' e' e'
690 We have used the @code{caps} font shape, but suppose that our font
691 does not have a small-caps variant. In that case we have to fake
692 the small caps font by setting a string in upcase with the first
693 letter a little larger:
696 #(def-markup-command (smallcaps layout props str) (string?)
697 "Print the string argument in small caps."
698 (interpret-markup layout props
701 (if (= (string-length s) 0)
703 (markup #:large (string-upcase (substring s 0 1))
704 #:translate (cons -0.6 0)
705 #:tiny (string-upcase (substring s 1)))))
706 (string-split str #\Space)))))
709 The @code{smallcaps} command first splits its string argument into
710 tokens separated by spaces (@code{(string-split str #\Space)}); for
711 each token, a markup is built with the first letter made large and
712 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
713 second markup built with the following letters made tiny and upcased
714 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
715 introduces a space between markups on a line, the second markup is
716 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
717 the markups built for each token are put in a line by
718 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
719 to the @code{interpret-markup} function, with the @code{layout} and
720 @code{props} arguments.
724 @node Contexts for programmers
725 @section Contexts for programmers
729 * Context evaluation::
730 * Running a function on all layout objects::
733 @node Context evaluation
734 @subsection Context evaluation
736 @cindex calling code during interpreting
737 @cindex @code{\applyContext}
739 Contexts can be modified during interpretation with Scheme code. The
742 \applyContext @var{function}
745 @var{function} should be a Scheme function taking a single argument,
746 being the context to apply it to. The following code will print the
747 current bar number on the standard output during the compile:
752 (format #t "\nWe were called in barnumber ~a.\n"
753 (ly:context-property x 'currentBarNumber)))
758 @node Running a function on all layout objects
759 @subsection Running a function on all layout objects
762 @cindex calling code on layout objects
763 @cindex @code{\applyOutput}
766 The most versatile way of tuning an object is @code{\applyOutput}. Its
769 \applyOutput @var{proc}
773 where @var{proc} is a Scheme function, taking three arguments.
775 When interpreted, the function @var{proc} is called for every layout
776 object found in the context, with the following arguments:
778 @item the layout object itself,
779 @item the context where the layout object was created, and
780 @item the context where @code{\applyOutput} is processed.
784 In addition, the cause of the layout object, i.e., the music
785 expression or object that was responsible for creating it, is in the
786 object property @code{cause}. For example, for a note head, this is a
787 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
788 this is a @internalsref{NoteHead} object.
790 Here is a function to use for @code{\applyOutput}; it blanks
791 note-heads on the center-line:
794 (define (blanker grob grob-origin context)
795 (if (and (memq (ly:grob-property grob 'interfaces)
797 (eq? (ly:grob-property grob 'staff-position) 0))
798 (set! (ly:grob-property grob 'transparent) #t)))