1 @c -*- coding: latin-1; 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 * Using LilyPond syntax inside Scheme::
24 @node Input variables and Scheme
25 @subsection Input variables and Scheme
28 The input format supports the notion of variables: in the following
29 example, a music expression is assigned to a variable with the name
32 traLaLa = @{ c'4 d'4 @}
37 There is also a form of scoping: in the following example, the
38 @code{\layout} block also contains a @code{traLaLa} variable, which is
39 independent of the outer @code{\traLaLa}.
41 traLaLa = @{ c'4 d'4 @}
42 \layout @{ traLaLa = 1.0 @}
45 In effect, each input file is a scope, and all @code{\header},
46 @code{\midi}, and @code{\layout} 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 = @{ c'4 d'4 @}
57 is internally converted to a Scheme definition
59 (define traLaLa @var{Scheme value of ``@code{... }''})
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} block by means of a second variable
68 traLaLa = @{ 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 @{ #(ly:export (make-sequential-music (list newLa))) @}
91 Mixing Scheme and LilyPond identifiers is not possible with the
94 @node Internal music representation
95 @subsection Internal music representation
97 When a music expression is parsed, it is converted into a set of
98 Scheme music objects. The defining property of a music object is that
99 it takes up time. Time is a rational number that measures the length
100 of a piece of music, in whole notes.
102 A music object has three kinds of types:
105 music name: Each music expression has a name, for example, a note
106 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
107 a @internalsref{SimultaneousMusic}. A list of all expressions
108 available is in the internals manual, under
109 @internalsref{Music expressions}.
112 `type' or interface: Each music name has several `types' or
113 interfaces, for example, a note is an @code{event}, but it is also a
114 @code{note-event}, a @code{rhythmic-event}, and a @code{melodic-event}.
116 All classes of music are listed in the internals manual, under
117 @internalsref{Music classes}.
120 C++ object: Each music object is represented by a C++ object. For
121 technical reasons, different music objects may be represented by
122 different C++ object types. For example, a note is @code{Event}
123 object, while @code{\grace} creates a @code{Grace_music} object.
125 We expect that distinctions between different C++ types will disappear
129 The actual information of a music expression is stored in properties.
130 For example, a @internalsref{NoteEvent} has @code{pitch} and
131 @code{duration} properties that store the pitch and duration of that
132 note. A list of all properties available is in the internals manual,
133 under @internalsref{Music properties}.
135 A compound music expression is a music object that contains other
136 music objects in its properties. A list of objects can be stored in
137 the @code{elements} property of a music object, or a single `child'
138 music object in the @code{element} object. For example,
139 @internalsref{SequentialMusic} has its children in @code{elements},
140 and @internalsref{GraceMusic} has its single argument in
141 @code{element}. The body of a repeat is stored in the @code{element}
142 property of @internalsref{RepeatedMusic}, and the alternatives in
148 @node Extending music syntax
149 @subsection Extending music syntax
151 @c TODO: rewrite example.
152 @c The use of FUNC as example argument is rather confusing.
154 The syntax of composite music expressions, like @code{\repeat},
155 @code{\transpose}, and @code{\context} follows the general form of
158 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
161 Such syntax can also be defined as user code. To do this, it is
162 necessary to create a @emph{music function}. This is a specially marked
163 Scheme function. For example, the music function @code{\applymusic} applies
164 a user-defined function to a music expression. Its syntax is
167 \applymusic #@var{func} @var{music}
170 A music function is created with @code{ly:make-music-function},
173 (ly:make-music-function
176 @code{\applymusic} takes a Scheme function and a Music expression as
177 arguments. This is encoded in its parameter list,
180 (list procedure? ly:music?)
183 The function itself takes another argument, an Input location
184 object. That object is used to provide error messages with file names
185 and line numbers. The definition is the second argument of
186 @code{ly:make-music-function}. The body simply calls the function
189 (lambda (where func music)
193 The above Scheme code only defines the functionality. The tag
194 @code{\applymusic} is selected by defining
197 applymusic = #(ly:make-music-function
198 (list procedure? ly:music?)
199 (lambda (parser location func music)
203 A @code{def-music-function} macro is introduced on top of
204 @code{ly:make-music-function} to ease the definition of music
208 applymusic = #(def-music-function (parser location func music)
209 (procedure? ly:music?)
213 Examples of the use of @code{\applymusic} are in the next section.
216 @file{ly/@/music@/-functions@/-init@/.ly}.
218 @node Manipulating music expressions
219 @subsection Manipulating music expressions
221 Music objects and their properties can be accessed and manipulated
222 directly, through the @code{\applymusic} mechanism.
223 The syntax for @code{\applymusic} is
225 \applymusic #@var{func} @var{music}
229 This means that the Scheme function @var{func} is called with
230 @var{music} as its argument. The return value of @var{func} is the
231 result of the entire expression. @var{func} may read and write music
232 properties using the functions @code{ly:music-property} and
233 @code{ly:music-set-property!}.
235 An example is a function that reverses the order of elements in
237 @lilypond[quote,verbatim,raggedright]
238 #(define (rev-music-1 m)
239 (ly:music-set-property! m 'elements
240 (reverse (ly:music-property m 'elements)))
243 \applymusic #rev-music-1 { c'4 d'4 }
246 The use of such a function is very limited. The effect of this
247 function is void when applied to an argument that does not have
248 multiple children. The following function application has no effect
251 \applymusic #rev-music-1 \grace @{ c4 d4 @}
255 In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which
256 has no @code{elements}, only a single @code{element}. Every generally
257 applicable function for @code{\applymusic} must -- like music expressions
258 themselves -- be recursive.
260 The following example is such a recursive function: It first extracts
261 the @code{elements} of an expression, reverses them and puts them
262 back. Then it recurses, both on @code{elements} and @code{element}
265 #(define (reverse-music music)
266 (let* ((elements (ly:music-property music 'elements))
267 (child (ly:music-property music 'element))
268 (reversed (reverse elements)))
271 (ly:music-set-property! music 'elements reversed)
274 (if (ly:music? child) (reverse-music child))
275 (map reverse-music reversed)
280 A slightly more elaborate example is in
281 @inputfileref{input/@/test,reverse@/-music@/.ly}.
283 Some of the input syntax is also implemented as recursive music
284 functions. For example, the syntax for polyphony
290 is actually implemented as a recursive function that replaces the
291 above by the internal equivalent of
293 << \context Voice = "1" @{ \voiceOne a @}
294 \context Voice = "2" @{ \voiceTwo b @} >>
297 Other applications of @code{\applymusic} are writing out repeats
298 automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}),
299 saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and
300 exporting LilyPond input to other formats
301 (@inputfileref{input/@/no@/-notation,to@/-xml@/.ly}).
303 @cindex internal storage
304 @cindex @code{\displayMusic}
305 When writing a music function, it is often instructive to inspect how
306 a music expression is stored internally. This can be done with the
307 music function @code{\displayMusic}.
311 @file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
312 @inputfileref{input/@/test,add@/-staccato@/.ly},
313 @inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
314 @inputfileref{input/@/test,music@/-box@/.ly}.
317 @node Using LilyPond syntax inside Scheme
318 @subsection Using LilyPond syntax inside Scheme
320 Creating music expressions in Scheme can be tedious, as they are
321 heavily nested and the resulting Scheme code is large. For some
322 simple tasks, this can be avoided, using common LilyPond syntax inside
323 Scheme, with the dedicated @code{#@{ ... #@}} syntax.
325 The following two expressions give equivalent music expressions:
327 mynotes = @{ \override Stem #'thickness = #4
330 #(define mynotes #@{ \override Stem #'thickness = #4
334 The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
335 ... @}} block, which is parsed. The resulting music expression, a
336 @code{SequentialMusic} music object, is then returned and usable in Scheme.
338 Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
339 expressions with the @code{$} character (@code{$$} can be used to
340 produce a single @code{$} character). This makes the creation of simple
341 functions straightforward. In the following example, a function
342 setting the TextScript's padding is defined:
344 @lilypond[quote,verbatim,raggedright]
345 #(use-modules (ice-9 optargs))
346 #(define* (textpad padding #:optional once?)
347 (ly:export ; this is necessary for using the expression
348 ; directly inside a block
350 #{ \once \override TextScript #'padding = #$padding #}
351 #{ \override TextScript #'padding = #$padding #})))
355 #(textpad 3.0 #t) % only once
364 Here, the variable @code{padding} is a number; music expression
365 variables may also be used in a similar fashion, as in the following
368 @lilypond[quote,verbatim,raggedright]
369 #(define (with-padding padding)
371 #{ \override TextScript #'padding = #$padding
373 \revert TextScript #'padding #}))
377 \applymusic #(with-padding 3) { c'^"2" c'^"3" }
382 The function created by @code{(with-padding 3)} adds @code{\override} and
383 @code{\revert} statements around the music given as an argument, and returns
384 this new expression. Thus, this example is equivalent to:
389 @{ \override TextScript #'padding = #3
391 \revert TextScript #'padding
397 This function may also be defined as a music function:
399 @lilypond[quote,verbatim,raggedright]
401 #(def-music-function (parser location padding music) (number? ly:music?)
402 #{ \override TextScript #'padding = #$padding
404 \revert TextScript #'padding #})
408 \withPadding #3 { c'^"2" c'^"3"}
414 @node Markup programmer interface
415 @section Markup programmer interface
417 @c Please rewrite the second sentence; I don't understand its meaning. AS
419 Markups are implemented as special Scheme functions. When applied
420 with as arguments an output definition (@code{\layout} or
421 @code{\paper}), and a list of properties and other arguments, produce
425 * Markup construction in Scheme::
426 * How markups work internally ::
427 * Markup command definition::
430 @node Markup construction in Scheme
431 @subsection Markup construction in Scheme
433 @cindex defining markup commands
435 The @code{markup} macro builds markup expressions in Scheme while
436 providing a LilyPond-like syntax. For example,
438 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
439 #:bigger #:line ("foo" "bar" "baz")))
445 \markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
446 \bigger @{ foo bar baz @} >
450 This example exposes the main translation rules between regular
451 LilyPond markup syntax and Scheme markup syntax, which are summed up
455 @multitable @columnfractions .3 .3
456 @item @b{LilyPond} @tab @b{Scheme}
457 @item @code{\command} @tab @code{#:command}
458 @item @code{\variable} @tab @code{variable}
459 @item @code{@{ ... @}} @tab @code{#:line ( ... )}
460 @item @code{\center-align < ... >} @tab @code{#:center ( ... )}
461 @item @code{string} @tab @code{"string"}
462 @item @code{#scheme-arg} @tab @code{scheme-arg}
466 Besides, the whole scheme language is accessible inside the
467 @code{markup} macro: thus, one may use function calls inside
468 @code{markup} in order to manipulate character strings for
469 instance. This proves useful when defining new markup commands (see
470 @ref{Markup command definition}).
474 One can not feed the @code{#:line} (resp @code{#:center},
475 @code{#:column}) command with a variable or the result of a function
479 (markup #:line (fun-that-returns-markups))
483 is invalid. One should use the @code{make-line-markup} (resp.,
484 @code{make-center-markup} or @code{make-column-markup}) function
487 (markup (make-line-markup (fun-that-returns-markups)))
490 @node How markups work internally
491 @subsection How markups work internally
500 @code{\raise} is actually represented by the @code{raise-markup}
501 function. The markup expression is stored as
504 (list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
508 In this case, @code{latin1} is the input encoding, which is set with
509 the @code{\encoding} command.
511 When the markup is converted to printable objects (Stencils), the
512 @code{raise-markup} function is called as
517 @var{list of property alists}
519 @var{the "foo" markup})
522 The @code{raise-markup} first creates the stencil for the @code{foo}
523 string, and then it raises that Stencil by 0.5 staff space. This is a
524 rather simple example; more complex examples are in the rest of this
525 section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
527 @node Markup command definition
528 @subsection Markup command definition
530 New markup commands can be defined
531 with the @code{def-markup-command} scheme macro.
533 (def-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
534 (@var{arg1-type?} @var{arg2-type?} ...)
538 The arguments signify
542 @var{i}th command argument
544 a type predicate for the i@var{th} argument
546 the `layout' definition
548 a list of alists, containing all active properties.
551 As a simple example, we show how to add a @code{\smallcaps} command,
552 which selects @TeX{}'s small caps font. Normally, we could select the
553 small caps font as follows:
556 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
559 This selects the caps font by setting the @code{font-shape} property to
560 @code{#'caps} for interpreting @code{Text-in-caps}.
562 To make the above available as @code{\smallcaps} command, we have to
563 define a function using @code{def-markup-command}. The command should
564 take a single argument, of type markup. Therefore, the start of the
565 definition should read
567 (def-markup-command (smallcaps layout props argument) (markup?)
572 What follows is the content of the command: we should interpret
573 the @code{argument} as a markup, i.e.,
576 (interpret-markup layout @dots{} argument)
580 This interpretation should add @code{'(font-shape . caps)} to the active
581 properties, so we substitute the following for the @dots{} in the
585 (cons (list '(font-shape . caps) ) props)
589 The variable @code{props} is a list of alists, and we prepend to it by
590 cons'ing a list with the extra setting.
593 Suppose that we are typesetting a recitative in an opera, and
594 we would like to define a command that will show character names in a
595 custom manner. Names should be printed with small caps and translated a
596 bit to the left and top. We will define a @code{\character} command
597 that takes into account the necessary translation, and uses the newly
598 defined @code{\smallcaps} command:
601 #(def-markup-command (character layout props name) (string?)
602 "Print the character name in small caps, translated to the left and
603 top. Syntax: \\character #\"name\""
604 (interpret-markup layout props
605 (markup "" #:translate (cons -3 1) #:smallcaps name)))
608 There is one complication that needs explanation: texts above and below
609 the staff are moved vertically to be at a certain distance (the
610 @code{padding} property) from the staff and the notes. To make sure
611 that this mechanism does not annihilate the vertical effect of our
612 @code{#:translate}, we add an empty string (@code{""}) before the
613 translated text. Now the @code{""} will be put above the notes, and the
614 @code{name} is moved in relation to that empty string. The net effect is
615 that the text is moved to the upper left.
617 The final result is as follows:
620 c''^\markup \character #"Cleopatra"
621 e'^\markup \character #"Giulio Cesare"
625 @lilypond[quote,raggedright]
626 #(def-markup-command (smallcaps layout props str) (string?)
627 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
628 (interpret-markup layout props
631 (if (= (string-length s) 0)
633 (markup #:large (string-upcase (substring s 0 1))
634 #:translate (cons -0.6 0)
635 #:tiny (string-upcase (substring s 1)))))
636 (string-split str #\Space)))))
638 #(def-markup-command (character layout props name) (string?)
639 "Print the character name in small caps, translated to the left and
640 top. Syntax: \\character #\"name\""
641 (interpret-markup layout props
642 (markup "" #:translate (cons -3 1) #:smallcaps name)))
645 c''^\markup \character #"Cleopatra" c'' c'' c''
646 e'^\markup \character #"Giulio Cesare" e' e' e'
650 We have used the @code{caps} font shape, but suppose that our font
651 does not have a small-caps variant. In that case we have to fake
652 the small caps font by setting a string in upcase with the first
653 letter a little larger:
656 #(def-markup-command (smallcaps layout props str) (string?)
657 "Print the string argument in small caps."
658 (interpret-markup layout props
661 (if (= (string-length s) 0)
663 (markup #:large (string-upcase (substring s 0 1))
664 #:translate (cons -0.6 0)
665 #:tiny (string-upcase (substring s 1)))))
666 (string-split str #\Space)))))
669 The @code{smallcaps} command first splits its string argument into
670 tokens separated by spaces (@code{(string-split str #\Space)}); for
671 each token, a markup is built with the first letter made large and
672 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
673 second markup built with the following letters made tiny and upcased
674 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
675 introduces a space between markups on a line, the second markup is
676 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
677 the markups built for each token are put in a line by
678 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
679 to the @code{interpret-markup} function, with the @code{layout} and
680 @code{props} arguments.
684 @node Contexts for programmers
685 @section Contexts for programmers
689 * Context evaluation::
690 * Running a function on all layout objects::
693 @node Context evaluation
694 @subsection Context evaluation
696 @cindex calling code during interpreting
697 @cindex @code{\applycontext}
699 Contexts can be modified during interpretation with Scheme code. The
702 \applycontext @var{function}
705 @var{function} should be a Scheme function taking a single argument,
706 being the context to apply it to. The following code will print the
707 current bar number on the standard output during the compile:
712 (format #t "\nWe were called in barnumber ~a.\n"
713 (ly:context-property x 'currentBarNumber)))
718 @node Running a function on all layout objects
719 @subsection Running a function on all layout objects
722 @cindex calling code on layout objects
723 @cindex @code{\applyoutput}
726 The most versatile way of tuning an object is @code{\applyoutput}. Its
729 \applyoutput @var{proc}
733 where @var{proc} is a Scheme function, taking three arguments.
735 When interpreted, the function @var{proc} is called for every layout
736 object found in the context, with the following arguments:
738 @item the layout object itself,
739 @item the context where the layout object was created, and
740 @item the context where @code{\applyoutput} is processed.
744 In addition, the cause of the layout object, i.e., the music
745 expression or object that was responsible for creating it, is in the
746 object property @code{cause}. For example, for a note head, this is a
747 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
748 this is a @internalsref{NoteHead} object.
750 Here is a function to use for @code{\applyoutput}; it blanks
751 note-heads on the center-line:
754 (define (blanker grob grob-origin context)
755 (if (and (memq (ly:grob-property grob 'interfaces)
757 (eq? (ly:grob-property grob 'staff-position) 0))
758 (set! (ly:grob-property grob 'transparent) #t)))