1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Interfaces for programmers
3 @chapter Interfaces for programmers
5 Advanced tweaks may be performed by using Scheme. If you are
6 not familiar with Scheme, you may wish to read our
11 * Programmer interfaces::
12 * Building complicated functions::
13 * Markup programmer interface::
14 * Contexts for programmers::
19 @section Music functions
21 This section discusses how to create music functions within LilyPond.
24 * Overview of music functions::
25 * Simple substitution functions::
26 * Paired substition functions::
27 * Mathematics in functions::
31 @node Overview of music functions
32 @subsection Overview of music functions
34 Making a funcion which substitutes a variable into LilyPond
35 code is easy. The general form of these functions is
39 #(define-music-function (parser location @var{var1} @var{var2}... )
40 (@var{var1-type?} @var{var2-type?}...)
49 @multitable @columnfractions .33 .66
50 @item @var{argi} @tab @var{i}th variable
51 @item @var{argi-type?} @tab type of variable
52 @item @var{...music...} @tab normal LilyPond input, using
53 variables as @code{#$var1}.
56 There following input types may be used as variables
57 in a music function. This list is not exhaustive; see
58 other documentation specifically about Scheme for more
61 @multitable @columnfractions .33 .66
62 @headitem Input type @tab @var{argi-type?} notation
63 @item Integer @tab @code{integer?}
64 @item Float (decimal number) @tab @code{number?}
65 @item Text string @tab @code{string?}
66 @item Markup @tab @code{markup?}
67 @item Music expression @tab @code{ly:music?}
68 @item A pair of variables @tab @code{pair?}
71 The @code{parser} and @code{location} argument are mandatory,
72 and are used in some advanced situations. The @code{parser}
73 argument is used to access to the value of another LilyPond
74 variable. The @code{location} argument
75 is used to set the ``origin'' of the music expression that is built
76 by the music function, so that in case of a syntax error LilyPond
77 can tell the user an appropriate place to look in the input file.
80 @node Simple substitution functions
81 @subsection Simple substitution functions
83 Here is a simple example,
85 @lilypond[quote,verbatim,ragged-right]
86 padText = #(define-music-function (parser location padding) (number?)
88 \once \override TextScript #'padding = #$padding
96 c4^"piu mosso" fis a g
100 Music expressions may be substituted as well,
102 @lilypond[quote,verbatim,ragged-right]
103 custosNote = #(define-music-function (parser location note)
106 \once \override Voice.NoteHead #'stencil =
107 #ly:text-interface::print
108 \once \override Voice.NoteHead #'text =
109 \markup \musicglyph #"custodes.mensural.u0"
110 \once \override Voice.Stem #'stencil = ##f
114 { c' d' e' f' \custosNote g' }
117 Multiple variables may be used,
119 @lilypond[quote,verbatim,ragged-right]
120 tempoMark = #(define-music-function (parser location padding marktext)
123 \once \override Score . RehearsalMark #'padding = $padding
124 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
125 \mark \markup { \bold $marktext }
130 \tempoMark #3.0 #"Allegro"
136 @node Paired substition functions
137 @subsection Paired substition functions
139 Some @code{\override} commands require a pair of numbers
140 (called a @code{cons cell} in Scheme). To pass these numbers
141 into a function, either use a @code{pair?} variable, or
142 insert the @code{cons} into the music function.
147 #(define-music-function (parser location beg-end)
150 \once \override Beam #'positions = #$beg-end
154 \manualBeam #'(3 . 6) c8 d e f
162 @lilypond[quote,verbatim,ragged-right]
164 #(define-music-function (parser location beg end)
167 \once \override Beam #'positions = #(cons $beg $end)
171 \manualBeam #3 #6 c8 d e f
176 @node Mathematics in functions
177 @subsection Mathematics in functions
179 Music functions can involve Scheme programming in
180 addition to simple substitution,
182 @lilypond[quote,verbatim,ragged-right]
183 AltOn = #(define-music-function (parser location mag) (number?)
184 #{ \override Stem #'length = #$(* 7.0 mag)
185 \override NoteHead #'font-size =
186 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
189 \revert Stem #'length
190 \revert NoteHead #'font-size
193 { c'2 \AltOn #0.5 c'4 c'
194 \AltOn #1.5 c' c' \AltOff c'2 }
198 This example may be rewritten to pass in music expressions,
200 @lilypond[quote,verbatim,ragged-right]
201 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
202 #{ \override Stem #'length = #$(* 7.0 mag)
203 \override NoteHead #'font-size =
204 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
206 \revert Stem #'length
207 \revert NoteHead #'font-size #})
209 { c'2 \withAlt #0.5 {c'4 c'}
210 \withAlt #1.5 {c' c'} c'2 }
215 @subsection Void functions
217 A music function must return a music expression, but sometimes we
218 may want to have a function which does not involve music (such as
219 turning off Point and Click). To do this, we return a @code{void}
223 that is returned is the @code{(make-music ...)}. With the
224 @code{'void} property set to @code{#t}, the parser is told to
225 actually disregard this returned music
226 expression. Thus the important part of the void music function is the
227 processing done by the function, not the music expression that is
232 #(define-music-function (parser location) ()
233 (ly:set-option 'point-and-click #f)
234 (make-music 'SequentialMusic 'void #t))
236 \noPointAndClick % disable point and click
240 @node Programmer interfaces
241 @section Programmer interfaces
243 This section contains information about mixing LilyPond
247 * Input variables and Scheme::
248 * Internal music representation::
252 @node Input variables and Scheme
253 @subsection Input variables and Scheme
255 The input format supports the notion of variables: in the following
256 example, a music expression is assigned to a variable with the name
260 traLaLa = @{ c'4 d'4 @}
265 There is also a form of scoping: in the following example, the
266 @code{\layout} block also contains a @code{traLaLa} variable, which is
267 independent of the outer @code{\traLaLa}.
269 traLaLa = @{ c'4 d'4 @}
270 \layout @{ traLaLa = 1.0 @}
273 In effect, each input file is a scope, and all @code{\header},
274 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
277 Both variables and scoping are implemented in the GUILE module system.
278 An anonymous Scheme module is attached to each scope. An assignment of
281 traLaLa = @{ c'4 d'4 @}
285 is internally converted to a Scheme definition
287 (define traLaLa @var{Scheme value of ``@code{... }''})
290 This means that input variables and Scheme variables may be freely
291 mixed. In the following example, a music fragment is stored in the
292 variable @code{traLaLa}, and duplicated using Scheme. The result is
293 imported in a @code{\score} block by means of a second variable
296 traLaLa = @{ c'4 d'4 @}
298 #(define newLa (map ly:music-deep-copy
299 (list traLaLa traLaLa)))
301 (make-sequential-music newLa))
306 In the above example, music expressions can be `exported' from the
307 input to the Scheme interpreter. The opposite is also possible. By
308 wrapping a Scheme value in the function @code{ly:export}, a Scheme
309 value is interpreted as if it were entered in LilyPond syntax. Instead
310 of defining @code{\twice}, the example above could also have been
314 @{ #(ly:export (make-sequential-music (list newLa))) @}
317 Scheme code is evaluated as soon as the parser encounters it. To
318 define some scheme code in a macro (to be called later), use
319 @ref{Void functions} or
323 (ly:set-option 'point-and-click #f))
333 Mixing Scheme and LilyPond identifiers is not possible with the
334 @code{--safe} option.
337 @node Internal music representation
338 @subsection Internal music representation
340 When a music expression is parsed, it is converted into a set of
341 Scheme music objects. The defining property of a music object is that
342 it takes up time. Time is a rational number that measures the length
343 of a piece of music in whole notes.
345 A music object has three kinds of types:
348 music name: Each music expression has a name. For example, a note
349 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
350 a @internalsref{SimultaneousMusic}. A list of all expressions
351 available is in the Program reference manual, under
352 @internalsref{Music expressions}.
355 `type' or interface: Each music name has several `types' or
356 interfaces, for example, a note is an @code{event}, but it is also a
357 @code{note-event}, a @code{rhythmic-event}, and a
358 @code{melodic-event}. All classes of music are listed in the
359 Profram reference, under
360 @internalsref{Music classes}.
363 C++ object: Each music object is represented by an object of the C++
367 The actual information of a music expression is stored in properties.
368 For example, a @internalsref{NoteEvent} has @code{pitch} and
369 @code{duration} properties that store the pitch and duration of that
370 note. A list of all properties available is in the internals manual,
371 under @internalsref{Music properties}.
373 A compound music expression is a music object that contains other
374 music objects in its properties. A list of objects can be stored in
375 the @code{elements} property of a music object, or a single `child'
376 music object in the @code{element} object. For example,
377 @internalsref{SequentialMusic} has its children in @code{elements},
378 and @internalsref{GraceMusic} has its single argument in
379 @code{element}. The body of a repeat is stored in the @code{element}
380 property of @internalsref{RepeatedMusic}, and the alternatives in
385 @node Building complicated functions
386 @section Building complicated functions
388 This section explains how to gather the information necessary
389 to create complicated music functions.
392 * Displaying music expressions::
394 * Doubling a note with slurs (example)::
395 * Adding articulation to notes (example)::
399 @node Displaying music expressions
400 @subsection Displaying music expressions
402 @cindex internal storage
403 @findex \displayMusic
404 @findex \displayLilyMusic
406 When writing a music function it is often instructive to inspect how
407 a music expression is stored internally. This can be done with the
408 music function @code{\displayMusic}
412 \displayMusic @{ c'4\f @}
429 (ly:make-duration 2 0 1 1)
431 (ly:make-pitch 0 0 0))
433 'AbsoluteDynamicEvent
438 By default, LilyPond will print these messages to the console along
439 with all the other messages. To split up these messages and save
440 the results of @code{\display@{STUFF@}}, redirect the output to
444 lilypond file.ly >display.txt
447 With a bit of reformatting, the above information is
451 (make-music 'SequentialMusic
452 'elements (list (make-music 'EventChord
453 'elements (list (make-music 'NoteEvent
454 'duration (ly:make-duration 2 0 1 1)
455 'pitch (ly:make-pitch 0 0 0))
456 (make-music 'AbsoluteDynamicEvent
460 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
461 and its inner expressions are stored as a list in its @code{'elements}
462 property. A note is represented as an @code{EventChord} expression,
463 containing a @code{NoteEvent} object (storing the duration and
464 pitch properties) and any extra information (in this case, an
465 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
468 @node Music properties
469 @subsection Music properties
471 The @code{NoteEvent} object is the first object of the
472 @code{'elements} property of @code{someNote}.
476 \displayMusic \someNote
484 (ly:make-duration 2 0 1 1)
486 (ly:make-pitch 0 0 0))))
489 The @code{display-scheme-music} function is the function used by
490 @code{\displayMusic} to display the scheme representation of a music
494 #(display-scheme-music (first (ly:music-property someNote 'elements)))
499 (ly:make-duration 2 0 1 1)
501 (ly:make-pitch 0 0 0))
504 Then the note pitch is accessed thourgh the @code{'pitch} property
505 of the @code{NoteEvent} object,
508 #(display-scheme-music
509 (ly:music-property (first (ly:music-property someNote 'elements))
512 (ly:make-pitch 0 0 0)
515 The note pitch can be changed by setting this 'pitch property,
518 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
520 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
521 \displayLilyMusic \someNote
527 @node Doubling a note with slurs (example)
528 @subsection Doubling a note with slurs (example)
530 Suppose we want to create a function which translates
531 input like ``@code{a}'' into ``@code{a( a)}''. We begin
532 by examining the internal representation of the music
533 we want to end up with.
536 \displayMusic@{ a'( a') @}
547 (ly:make-duration 2 0 1 1)
549 (ly:make-pitch 0 5 0))
560 (ly:make-duration 2 0 1 1)
562 (ly:make-pitch 0 5 0))
569 The bad news is that the @code{SlurEvent} expressions
570 must be added ``inside'' the note (or more precisely,
571 inside the @code{EventChord} expression).
573 Now we examine the input,
585 (ly:make-duration 2 0 1 1)
587 (ly:make-pitch 0 5 0))))))
590 So in our function, we need to clone this expression (so that we
591 have two notes to build the sequence), add @code{SlurEvents} to the
592 @code{'elements} property of each one, and finally make a
593 @code{SequentialMusic} with the two @code{EventChords}.
596 doubleSlur = #(def-music-function (parser location note) (ly:music?)
597 "Return: @{ note ( note ) @}.
598 `note' is supposed to be an EventChord."
599 (let ((note2 (ly:music-deep-copy note)))
600 (set! (ly:music-property note 'elements)
601 (cons (make-music 'SlurEvent 'span-direction -1)
602 (ly:music-property note 'elements)))
603 (set! (ly:music-property note2 'elements)
604 (cons (make-music 'SlurEvent 'span-direction 1)
605 (ly:music-property note2 'elements)))
606 (make-music 'SequentialMusic 'elements (list note note2))))
610 @node Adding articulation to notes (example)
611 @subsection Adding articulation to notes (example)
613 The easy way to add articulation to notes is to merge two music
614 expressions into one context, as explained in
615 @ref{Creating contexts}. However, suppose that we want to write
616 a music function which does this.
618 A @code{$variable} inside the @code{#@{...#@}} notation is like
619 using a regular @code{\variable} in classical LilyPond
620 notation. We know that
627 will not work in LilyPond. We could avoid this problem by attaching
628 the articulation to a fake note,
631 @{ << \music s1*0-.-> @}
635 but for the sake of this example, we will learn how to do this in
636 Scheme. We begin by examining our input and desired output,
648 (ly:make-duration 2 0 1 1)
650 (ly:make-pitch -1 0 0))))
661 (ly:make-duration 2 0 1 1)
663 (ly:make-pitch -1 0 0))
670 We see that a note (@code{c4}) is represented as an @code{EventChord}
671 expression, with a @code{NoteEvent} expression in its elements list. To
672 add a marcato articulation, an @code{ArticulationEvent} expression must
673 be added to the elements property of the @code{EventChord}
676 To build this function, we begin with
679 (define (add-marcato event-chord)
680 "Add a marcato ArticulationEvent to the elements of `event-chord',
681 which is supposed to be an EventChord expression."
682 (let ((result-event-chord (ly:music-deep-copy event-chord)))
683 (set! (ly:music-property result-event-chord 'elements)
684 (cons (make-music 'ArticulationEvent
685 'articulation-type "marcato")
686 (ly:music-property result-event-chord 'elements)))
690 The first line is the way to define a function in Scheme: the function
691 name is @code{add-marcato}, and has one variable called
692 @code{event-chord}. In Scheme, the type of variable is often clear
693 from its name. (this is good practice in other programming languages,
701 is a description of what the function does. This is not strictly
702 necessary, but just like clear variable names, it is good practice.
705 (let ((result-event-chord (ly:music-deep-copy event-chord)))
708 `@code{let}' is used to declare local variables. Here we use one local
709 variable, named `@code{result-event-chord}', to which we give the value
710 @code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
711 a function specific to LilyPond, like all functions prefixed by
712 `@code{ly:}'. It is use to make a copy of a music
713 expression. Here we copy `@code{event-chord} (the parameter of the
714 function). Recall that our purpose is to add a marcato to an
715 @code{EventChord} expression. It is better to not modify the
716 @code{EventChord} which was given as an argument, because it may be
719 Now we have a @code{result-event-chord}, which is a
720 @code{oteEventChord} expression and is a copy of @code{event-chord}. We
721 add the marcato to its elements list property.
724 (set! place new-value)
727 Here, what we want to set (the "place") is the "elements" property of
728 @code{result-event-chord} expression
731 (ly:music-property result-event-chord 'elements)
734 @code{ly:music-property} is the function used to access music properties
735 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
736 see in the @code{\displayMusic} output above). The new value is the
737 former elements property, with an extra item: the
738 @code{MarcatoEvent} expression, which we copy from the
739 @code{\displayMusic} output,
742 (cons (make-music 'ArticulationEvent
743 'articulation-type "marcato")
744 (ly:music-property result-event-chord 'elements))
747 `@code{cons}' is used to add an element to a list without modifying the
748 original list. This is what we
749 want: the same list as before, plus the new @code{ArticulationEvent}
750 expression. The order inside the elements property is not important here.
752 Finally, once we have added the @code{MarcatoEvent} to its elements
753 property, we can return @code{result-event-chord}, hence the last line of
756 Now we transform the @code{add-marcato} function into a music
760 addMarcato = #(define-music-function (parser location event-chord)
762 "Add a marcato ArticulationEvent to the elements of `event-chord',
763 which is supposed to be an EventChord expression."
764 (let ((result-event-chord (ly:music-deep-copy event-chord)))
765 (set! (ly:music-property result-event-chord 'elements)
766 (cons (make-music 'ArticulationEvent
767 'articulation-type "marcato")
768 (ly:music-property result-event-chord 'elements)))
772 We may verify that this music function works correctly,
775 \displayMusic \addMarcato c4
779 @node Markup programmer interface
780 @section Markup programmer interface
782 Markups are implemented as special Scheme functions which produce a
783 Stencil object given a number of arguments.
786 * Markup construction in Scheme::
787 * How markups work internally::
788 * New markup command definition::
792 @node Markup construction in Scheme
793 @subsection Markup construction in Scheme
795 @cindex defining markup commands
797 The @code{markup} macro builds markup expressions in Scheme while
798 providing a LilyPond-like syntax. For example,
800 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
801 #:bigger #:line ("foo" "bar" "baz")))
807 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
808 \bigger \line @{ foo bar baz @} @}
812 This example demonstrates the main translation rules between regular
813 LilyPond markup syntax and Scheme markup syntax.
816 @multitable @columnfractions .3 .3
817 @item @b{LilyPond} @tab @b{Scheme}
818 @item @code{\markup markup1} @tab @code{(markup markup1)}
819 @item @code{\markup @{ markup1 markup2 ... @}} @tab
820 @code{(markup markup1 markup2 ... )}
821 @item @code{\command} @tab @code{#:command}
822 @item @code{\variable} @tab @code{variable}
823 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
824 @item @code{string} @tab @code{"string"}
825 @item @code{#scheme-arg} @tab @code{scheme-arg}
829 The whole scheme language is accessible inside the
830 @code{markup} macro. For example, You may use function calls inside
831 @code{markup} in order to manipulate character strings. This is
832 useful when defining new markup commands (see
833 @ref{New markup command definition}).
838 The markup-list argument of commands such as @code{#:line},
839 @code{#:center}, and @code{#:column} cannot be a variable or
840 the result of a function call.
843 (markup #:line (function-that-returns-markups))
847 is invalid. One should use the @code{make-line-markup},
848 @code{make-center-markup}, or @code{make-column-markup} functions
852 (markup (make-line-markup (function-that-returns-markups)))
856 @node How markups work internally
857 @subsection How markups work internally
862 \raise #0.5 "text example"
866 @code{\raise} is actually represented by the @code{raise-markup}
867 function. The markup expression is stored as
870 (list raise-markup 0.5 (list simple-markup "text example"))
873 When the markup is converted to printable objects (Stencils), the
874 @code{raise-markup} function is called as
879 @var{list of property alists}
881 @var{the "text example" markup})
884 The @code{raise-markup} function first creates the stencil for the
885 @code{text example} string, and then it raises that Stencil by 0.5
886 staff space. This is a rather simple example; more complex examples
888 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
891 @node New markup command definition
892 @subsection New markup command definition
894 New markup commands can be defined
895 with the @code{define-markup-command} scheme macro.
898 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
899 (@var{arg1-type?} @var{arg2-type?} ...)
907 @var{i}th command argument
909 a type predicate for the i@var{th} argument
911 the `layout' definition
913 a list of alists, containing all active properties.
916 As a simple example, we show how to add a @code{\smallcaps} command,
917 which selects a small caps font. Normally we could select the
921 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
925 This selects the caps font by setting the @code{font-shape} property to
926 @code{#'caps} for interpreting @code{Text-in-caps}.
928 To make the above available as @code{\smallcaps} command, we must
929 define a function using @code{define-markup-command}. The command should
930 take a single argument of type @code{markup}. Therefore the start of the
931 definition should read
934 (define-markup-command (smallcaps layout props argument) (markup?)
939 What follows is the content of the command: we should interpret
940 the @code{argument} as a markup, i.e.,
943 (interpret-markup layout @dots{} argument)
947 This interpretation should add @code{'(font-shape . caps)} to the active
948 properties, so we substitute the following for the @dots{} in the
952 (cons (list '(font-shape . caps) ) props)
956 The variable @code{props} is a list of alists, and we prepend to it by
957 cons'ing a list with the extra setting.
960 Suppose that we are typesetting a recitative in an opera and
961 we would like to define a command that will show character names in a
962 custom manner. Names should be printed with small caps and moved a
963 bit to the left and top. We will define a @code{\character} command
964 which takes into account the necessary translation and uses the newly
965 defined @code{\smallcaps} command:
968 #(define-markup-command (character layout props name) (string?)
969 "Print the character name in small caps, translated to the left and
970 top. Syntax: \\character #\"name\""
971 (interpret-markup layout props
972 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
975 There is one complication that needs explanation: texts above and below
976 the staff are moved vertically to be at a certain distance (the
977 @code{padding} property) from the staff and the notes. To make sure
978 that this mechanism does not annihilate the vertical effect of our
979 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
980 translated text. Now the @code{#:hspace 0} will be put above the notes,
982 @code{name} is moved in relation to that empty string. The net effect is
983 that the text is moved to the upper left.
985 The final result is as follows:
989 c''^\markup \character #"Cleopatra"
990 e'^\markup \character #"Giulio Cesare"
994 @lilypond[quote,ragged-right]
995 #(define-markup-command (smallcaps layout props str) (string?)
996 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
997 (interpret-markup layout props
1000 (if (= (string-length s) 0)
1002 (markup #:large (string-upcase (substring s 0 1))
1003 #:translate (cons -0.6 0)
1004 #:tiny (string-upcase (substring s 1)))))
1005 (string-split str #\Space)))))
1007 #(define-markup-command (character layout props name) (string?)
1008 "Print the character name in small caps, translated to the left and
1009 top. Syntax: \\character #\"name\""
1010 (interpret-markup layout props
1011 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1014 c''^\markup \character #"Cleopatra" c'' c'' c''
1015 e'^\markup \character #"Giulio Cesare" e' e' e'
1019 We have used the @code{caps} font shape, but suppose that our font
1020 does not have a small-caps variant. In that case we have to fake
1021 the small caps font by setting a string in upcase with the first
1022 letter a little larger:
1025 #(define-markup-command (smallcaps layout props str) (string?)
1026 "Print the string argument in small caps."
1027 (interpret-markup layout props
1030 (if (= (string-length s) 0)
1032 (markup #:large (string-upcase (substring s 0 1))
1033 #:translate (cons -0.6 0)
1034 #:tiny (string-upcase (substring s 1)))))
1035 (string-split str #\Space)))))
1038 The @code{smallcaps} command first splits its string argument into
1039 tokens separated by spaces (@code{(string-split str #\Space)}); for
1040 each token, a markup is built with the first letter made large and
1041 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1042 second markup built with the following letters made tiny and upcased
1043 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1044 introduces a space between markups on a line, the second markup is
1045 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1046 the markups built for each token are put in a line by
1047 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1048 to the @code{interpret-markup} function, with the @code{layout} and
1049 @code{props} arguments.
1051 Note: there is now an internal command @code{\smallCaps} which can
1052 be used to set text in small caps. See
1053 @ref{Overview of text markup commands} for details.
1057 @node Contexts for programmers
1058 @section Contexts for programmers
1061 * Context evaluation::
1062 * Running a function on all layout objects::
1065 @node Context evaluation
1066 @subsection Context evaluation
1068 @cindex calling code during interpreting
1069 @findex \applyContext
1071 Contexts can be modified during interpretation with Scheme code. The
1074 \applyContext @var{function}
1077 @var{function} should be a Scheme function taking a single argument,
1078 being the context to apply it to. The following code will print the
1079 current bar number on the standard output during the compile:
1084 (format #t "\nWe were called in barnumber ~a.\n"
1085 (ly:context-property x 'currentBarNumber)))
1090 @node Running a function on all layout objects
1091 @subsection Running a function on all layout objects
1094 @cindex calling code on layout objects
1095 @findex \applyOutput
1098 The most versatile way of tuning an object is @code{\applyOutput}. Its
1101 \applyOutput @var{context} @var{proc}
1105 where @var{proc} is a Scheme function, taking three arguments.
1107 When interpreted, the function @var{proc} is called for every layout
1108 object found in the context @var{context}, with the following
1111 @item the layout object itself,
1112 @item the context where the layout object was created, and
1113 @item the context where @code{\applyOutput} is processed.
1117 In addition, the cause of the layout object, i.e., the music
1118 expression or object that was responsible for creating it, is in the
1119 object property @code{cause}. For example, for a note head, this is a
1120 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1121 this is a @internalsref{NoteHead} object.
1123 Here is a function to use for @code{\applyOutput}; it blanks
1124 note-heads on the center-line:
1127 (define (blanker grob grob-origin context)
1128 (if (and (memq (ly:grob-property grob 'interfaces)
1129 note-head-interface)
1130 (eq? (ly:grob-property grob 'staff-position) 0))
1131 (set! (ly:grob-property grob 'transparent) #t)))