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::
15 * Scheme procedures as properties::
20 @section Music functions
22 This section discusses how to create music functions within LilyPond.
25 * Overview of music functions::
26 * Simple substitution functions::
27 * Paired substitution functions::
28 * Mathematics in functions::
32 @node Overview of music functions
33 @subsection Overview of music functions
35 Making a function which substitutes a variable into LilyPond
36 code is easy. The general form of these functions is
40 #(define-music-function (parser location @var{var1} @var{var2}... )
41 (@var{var1-type?} @var{var2-type?}...)
50 @multitable @columnfractions .33 .66
51 @item @var{argi} @tab @var{i}th variable
52 @item @var{argi-type?} @tab type of variable
53 @item @var{...music...} @tab normal LilyPond input, using
54 variables as @code{#$var1}.
57 There following input types may be used as variables
58 in a music function. This list is not exhaustive; see
59 other documentation specifically about Scheme for more
62 @multitable @columnfractions .33 .66
63 @headitem Input type @tab @var{argi-type?} notation
64 @item Integer @tab @code{integer?}
65 @item Float (decimal number) @tab @code{number?}
66 @item Text string @tab @code{string?}
67 @item Markup @tab @code{markup?}
68 @item Music expression @tab @code{ly:music?}
69 @item A pair of variables @tab @code{pair?}
72 The @code{parser} and @code{location} argument are mandatory,
73 and are used in some advanced situations. The @code{parser}
74 argument is used to access to the value of another LilyPond
75 variable. The @code{location} argument
76 is used to set the ``origin'' of the music expression that is built
77 by the music function, so that in case of a syntax error LilyPond
78 can tell the user an appropriate place to look in the input file.
81 @node Simple substitution functions
82 @subsection Simple substitution functions
84 Here is a simple example,
86 @lilypond[quote,verbatim,ragged-right]
87 padText = #(define-music-function (parser location padding) (number?)
89 \once \override TextScript #'padding = #$padding
97 c4^"piu mosso" fis a g
101 Music expressions may be substituted as well,
103 @lilypond[quote,verbatim,ragged-right]
104 custosNote = #(define-music-function (parser location note)
107 \once \override Voice.NoteHead #'stencil =
108 #ly:text-interface::print
109 \once \override Voice.NoteHead #'text =
110 \markup \musicglyph #"custodes.mensural.u0"
111 \once \override Voice.Stem #'stencil = ##f
115 { c' d' e' f' \custosNote g' }
118 Multiple variables may be used,
120 @lilypond[quote,verbatim,ragged-right]
121 tempoMark = #(define-music-function (parser location padding marktext)
124 \once \override Score . RehearsalMark #'padding = $padding
125 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
126 \mark \markup { \bold $marktext }
131 \tempoMark #3.0 #"Allegro"
137 @node Paired substitution functions
138 @subsection Paired substitution functions
140 Some @code{\override} commands require a pair of numbers
141 (called a @code{cons cell} in Scheme). To pass these numbers
142 into a function, either use a @code{pair?} variable, or
143 insert the @code{cons} into the music function.
148 #(define-music-function (parser location beg-end)
151 \once \override Beam #'positions = #$beg-end
155 \manualBeam #'(3 . 6) c8 d e f
163 @lilypond[quote,verbatim,ragged-right]
165 #(define-music-function (parser location beg end)
168 \once \override Beam #'positions = #(cons $beg $end)
172 \manualBeam #3 #6 c8 d e f
177 @node Mathematics in functions
178 @subsection Mathematics in functions
180 Music functions can involve Scheme programming in
181 addition to simple substitution,
183 @lilypond[quote,verbatim,ragged-right]
184 AltOn = #(define-music-function (parser location mag) (number?)
185 #{ \override Stem #'length = #$(* 7.0 mag)
186 \override NoteHead #'font-size =
187 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
190 \revert Stem #'length
191 \revert NoteHead #'font-size
194 { c'2 \AltOn #0.5 c'4 c'
195 \AltOn #1.5 c' c' \AltOff c'2 }
199 This example may be rewritten to pass in music expressions,
201 @lilypond[quote,verbatim,ragged-right]
202 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
203 #{ \override Stem #'length = #$(* 7.0 mag)
204 \override NoteHead #'font-size =
205 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
207 \revert Stem #'length
208 \revert NoteHead #'font-size #})
210 { c'2 \withAlt #0.5 {c'4 c'}
211 \withAlt #1.5 {c' c'} c'2 }
216 @subsection Void functions
218 A music function must return a music expression, but sometimes we
219 may want to have a function which does not involve music (such as
220 turning off Point and Click). To do this, we return a @code{void}
224 that is returned is the @code{(make-music ...)}. With the
225 @code{'void} property set to @code{#t}, the parser is told to
226 actually disregard this returned music
227 expression. Thus the important part of the void music function is the
228 processing done by the function, not the music expression that is
233 #(define-music-function (parser location) ()
234 (ly:set-option 'point-and-click #f)
235 (make-music 'SequentialMusic 'void #t))
237 \noPointAndClick % disable point and click
241 @node Programmer interfaces
242 @section Programmer interfaces
244 This section contains information about mixing LilyPond
248 * Input variables and Scheme::
249 * Internal music representation::
253 @node Input variables and Scheme
254 @subsection Input variables and Scheme
256 The input format supports the notion of variables: in the following
257 example, a music expression is assigned to a variable with the name
261 traLaLa = @{ c'4 d'4 @}
266 There is also a form of scoping: in the following example, the
267 @code{\layout} block also contains a @code{traLaLa} variable, which is
268 independent of the outer @code{\traLaLa}.
270 traLaLa = @{ c'4 d'4 @}
271 \layout @{ traLaLa = 1.0 @}
274 In effect, each input file is a scope, and all @code{\header},
275 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
278 Both variables and scoping are implemented in the GUILE module system.
279 An anonymous Scheme module is attached to each scope. An assignment of
282 traLaLa = @{ c'4 d'4 @}
286 is internally converted to a Scheme definition
288 (define traLaLa @var{Scheme value of ``@code{... }''})
291 This means that input variables and Scheme variables may be freely
292 mixed. In the following example, a music fragment is stored in the
293 variable @code{traLaLa}, and duplicated using Scheme. The result is
294 imported in a @code{\score} block by means of a second variable
297 traLaLa = @{ c'4 d'4 @}
299 #(define newLa (map ly:music-deep-copy
300 (list traLaLa traLaLa)))
302 (make-sequential-music newLa))
307 In the above example, music expressions can be `exported' from the
308 input to the Scheme interpreter. The opposite is also possible. By
309 wrapping a Scheme value in the function @code{ly:export}, a Scheme
310 value is interpreted as if it were entered in LilyPond syntax. Instead
311 of defining @code{\twice}, the example above could also have been
315 @{ #(ly:export (make-sequential-music (list newLa))) @}
318 Scheme code is evaluated as soon as the parser encounters it. To
319 define some Scheme code in a macro (to be called later), use
320 @ref{Void functions} or
324 (ly:set-option 'point-and-click #f))
334 Mixing Scheme and LilyPond identifiers is not possible with the
335 @code{--safe} option.
338 @node Internal music representation
339 @subsection Internal music representation
341 When a music expression is parsed, it is converted into a set of
342 Scheme music objects. The defining property of a music object is that
343 it takes up time. Time is a rational number that measures the length
344 of a piece of music in whole notes.
346 A music object has three kinds of types:
349 music name: Each music expression has a name. For example, a note
350 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
351 a @internalsref{SimultaneousMusic}. A list of all expressions
352 available is in the Program reference manual, under
353 @internalsref{Music expressions}.
356 `type' or interface: Each music name has several `types' or
357 interfaces, for example, a note is an @code{event}, but it is also a
358 @code{note-event}, a @code{rhythmic-event}, and a
359 @code{melodic-event}. All classes of music are listed in the
360 Program reference, under
361 @internalsref{Music classes}.
364 C++ object: Each music object is represented by an object of the C++
368 The actual information of a music expression is stored in properties.
369 For example, a @internalsref{NoteEvent} has @code{pitch} and
370 @code{duration} properties that store the pitch and duration of that
371 note. A list of all properties available is in the internals manual,
372 under @internalsref{Music properties}.
374 A compound music expression is a music object that contains other
375 music objects in its properties. A list of objects can be stored in
376 the @code{elements} property of a music object, or a single `child'
377 music object in the @code{element} object. For example,
378 @internalsref{SequentialMusic} has its children in @code{elements},
379 and @internalsref{GraceMusic} has its single argument in
380 @code{element}. The body of a repeat is stored in the @code{element}
381 property of @internalsref{RepeatedMusic}, and the alternatives in
386 @node Building complicated functions
387 @section Building complicated functions
389 This section explains how to gather the information necessary
390 to create complicated music functions.
393 * Displaying music expressions::
395 * Doubling a note with slurs (example)::
396 * Adding articulation to notes (example)::
400 @node Displaying music expressions
401 @subsection Displaying music expressions
403 @cindex internal storage
404 @funindex \displayMusic
405 @funindex \displayLilyMusic
407 When writing a music function it is often instructive to inspect how
408 a music expression is stored internally. This can be done with the
409 music function @code{\displayMusic}
413 \displayMusic @{ c'4\f @}
430 (ly:make-duration 2 0 1 1)
432 (ly:make-pitch 0 0 0))
434 'AbsoluteDynamicEvent
439 By default, LilyPond will print these messages to the console along
440 with all the other messages. To split up these messages and save
441 the results of @code{\display@{STUFF@}}, redirect the output to
445 lilypond file.ly >display.txt
448 With a bit of reformatting, the above information is
452 (make-music 'SequentialMusic
453 'elements (list (make-music 'EventChord
454 'elements (list (make-music 'NoteEvent
455 'duration (ly:make-duration 2 0 1 1)
456 'pitch (ly:make-pitch 0 0 0))
457 (make-music 'AbsoluteDynamicEvent
461 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
462 and its inner expressions are stored as a list in its @code{'elements}
463 property. A note is represented as an @code{EventChord} expression,
464 containing a @code{NoteEvent} object (storing the duration and
465 pitch properties) and any extra information (in this case, an
466 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
469 @node Music properties
470 @subsection Music properties
472 The @code{NoteEvent} object is the first object of the
473 @code{'elements} property of @code{someNote}.
477 \displayMusic \someNote
485 (ly:make-duration 2 0 1 1)
487 (ly:make-pitch 0 0 0))))
490 The @code{display-scheme-music} function is the function used by
491 @code{\displayMusic} to display the Scheme representation of a music
495 #(display-scheme-music (first (ly:music-property someNote 'elements)))
500 (ly:make-duration 2 0 1 1)
502 (ly:make-pitch 0 0 0))
505 Then the note pitch is accessed through the @code{'pitch} property
506 of the @code{NoteEvent} object,
509 #(display-scheme-music
510 (ly:music-property (first (ly:music-property someNote 'elements))
513 (ly:make-pitch 0 0 0)
516 The note pitch can be changed by setting this 'pitch property,
519 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
521 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
522 \displayLilyMusic \someNote
528 @node Doubling a note with slurs (example)
529 @subsection Doubling a note with slurs (example)
531 Suppose we want to create a function which translates
532 input like ``@code{a}'' into ``@code{a( a)}''. We begin
533 by examining the internal representation of the music
534 we want to end up with.
537 \displayMusic@{ a'( a') @}
548 (ly:make-duration 2 0 1 1)
550 (ly:make-pitch 0 5 0))
561 (ly:make-duration 2 0 1 1)
563 (ly:make-pitch 0 5 0))
570 The bad news is that the @code{SlurEvent} expressions
571 must be added ``inside'' the note (or more precisely,
572 inside the @code{EventChord} expression).
574 Now we examine the input,
586 (ly:make-duration 2 0 1 1)
588 (ly:make-pitch 0 5 0))))))
591 So in our function, we need to clone this expression (so that we
592 have two notes to build the sequence), add @code{SlurEvents} to the
593 @code{'elements} property of each one, and finally make a
594 @code{SequentialMusic} with the two @code{EventChords}.
597 doubleSlur = #(def-music-function (parser location note) (ly:music?)
598 "Return: @{ note ( note ) @}.
599 `note' is supposed to be an EventChord."
600 (let ((note2 (ly:music-deep-copy note)))
601 (set! (ly:music-property note 'elements)
602 (cons (make-music 'SlurEvent 'span-direction -1)
603 (ly:music-property note 'elements)))
604 (set! (ly:music-property note2 'elements)
605 (cons (make-music 'SlurEvent 'span-direction 1)
606 (ly:music-property note2 'elements)))
607 (make-music 'SequentialMusic 'elements (list note note2))))
611 @node Adding articulation to notes (example)
612 @subsection Adding articulation to notes (example)
614 The easy way to add articulation to notes is to merge two music
615 expressions into one context, as explained in
616 @ref{Creating contexts}. However, suppose that we want to write
617 a music function which does this.
619 A @code{$variable} inside the @code{#@{...#@}} notation is like
620 using a regular @code{\variable} in classical LilyPond
621 notation. We know that
628 will not work in LilyPond. We could avoid this problem by attaching
629 the articulation to a fake note,
632 @{ << \music s1*0-.-> @}
636 but for the sake of this example, we will learn how to do this in
637 Scheme. We begin by examining our input and desired output,
649 (ly:make-duration 2 0 1 1)
651 (ly:make-pitch -1 0 0))))
662 (ly:make-duration 2 0 1 1)
664 (ly:make-pitch -1 0 0))
671 We see that a note (@code{c4}) is represented as an @code{EventChord}
672 expression, with a @code{NoteEvent} expression in its elements list. To
673 add a marcato articulation, an @code{ArticulationEvent} expression must
674 be added to the elements property of the @code{EventChord}
677 To build this function, we begin with
680 (define (add-marcato event-chord)
681 "Add a marcato ArticulationEvent to the elements of `event-chord',
682 which is supposed to be an EventChord expression."
683 (let ((result-event-chord (ly:music-deep-copy event-chord)))
684 (set! (ly:music-property result-event-chord 'elements)
685 (cons (make-music 'ArticulationEvent
686 'articulation-type "marcato")
687 (ly:music-property result-event-chord 'elements)))
691 The first line is the way to define a function in Scheme: the function
692 name is @code{add-marcato}, and has one variable called
693 @code{event-chord}. In Scheme, the type of variable is often clear
694 from its name. (this is good practice in other programming languages,
702 is a description of what the function does. This is not strictly
703 necessary, but just like clear variable names, it is good practice.
706 (let ((result-event-chord (ly:music-deep-copy event-chord)))
709 `@code{let}' is used to declare local variables. Here we use one local
710 variable, named `@code{result-event-chord}', to which we give the value
711 @code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
712 a function specific to LilyPond, like all functions prefixed by
713 `@code{ly:}'. It is use to make a copy of a music
714 expression. Here we copy `@code{event-chord} (the parameter of the
715 function). Recall that our purpose is to add a marcato to an
716 @code{EventChord} expression. It is better to not modify the
717 @code{EventChord} which was given as an argument, because it may be
720 Now we have a @code{result-event-chord}, which is a
721 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
722 add the marcato to its elements list property.
725 (set! place new-value)
728 Here, what we want to set (the "place") is the "elements" property of
729 @code{result-event-chord} expression
732 (ly:music-property result-event-chord 'elements)
735 @code{ly:music-property} is the function used to access music properties
736 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
737 see in the @code{\displayMusic} output above). The new value is the
738 former elements property, with an extra item: the
739 @code{MarcatoEvent} expression, which we copy from the
740 @code{\displayMusic} output,
743 (cons (make-music 'ArticulationEvent
744 'articulation-type "marcato")
745 (ly:music-property result-event-chord 'elements))
748 `@code{cons}' is used to add an element to a list without modifying the
749 original list. This is what we
750 want: the same list as before, plus the new @code{ArticulationEvent}
751 expression. The order inside the elements property is not important here.
753 Finally, once we have added the @code{MarcatoEvent} to its elements
754 property, we can return @code{result-event-chord}, hence the last line of
757 Now we transform the @code{add-marcato} function into a music
761 addMarcato = #(define-music-function (parser location event-chord)
763 "Add a marcato ArticulationEvent to the elements of `event-chord',
764 which is supposed to be an EventChord expression."
765 (let ((result-event-chord (ly:music-deep-copy event-chord)))
766 (set! (ly:music-property result-event-chord 'elements)
767 (cons (make-music 'ArticulationEvent
768 'articulation-type "marcato")
769 (ly:music-property result-event-chord 'elements)))
773 We may verify that this music function works correctly,
776 \displayMusic \addMarcato c4
780 @node Markup programmer interface
781 @section Markup programmer interface
783 Markups are implemented as special Scheme functions which produce a
784 Stencil object given a number of arguments.
787 * Markup construction in Scheme::
788 * How markups work internally::
789 * New markup command definition::
793 @node Markup construction in Scheme
794 @subsection Markup construction in Scheme
796 @cindex defining markup commands
798 The @code{markup} macro builds markup expressions in Scheme while
799 providing a LilyPond-like syntax. For example,
801 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
802 #:bigger #:line ("foo" "bar" "baz")))
808 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
809 \bigger \line @{ foo bar baz @} @}
813 This example demonstrates the main translation rules between regular
814 LilyPond markup syntax and Scheme markup syntax.
817 @multitable @columnfractions .3 .3
818 @item @b{LilyPond} @tab @b{Scheme}
819 @item @code{\markup markup1} @tab @code{(markup markup1)}
820 @item @code{\markup @{ markup1 markup2 ... @}} @tab
821 @code{(markup markup1 markup2 ... )}
822 @item @code{\command} @tab @code{#:command}
823 @item @code{\variable} @tab @code{variable}
824 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
825 @item @code{string} @tab @code{"string"}
826 @item @code{#scheme-arg} @tab @code{scheme-arg}
830 The whole Scheme language is accessible inside the
831 @code{markup} macro. For example, You may use function calls inside
832 @code{markup} in order to manipulate character strings. This is
833 useful when defining new markup commands (see
834 @ref{New markup command definition}).
839 The markup-list argument of commands such as @code{#:line},
840 @code{#:center}, and @code{#:column} cannot be a variable or
841 the result of a function call.
844 (markup #:line (function-that-returns-markups))
848 is invalid. One should use the @code{make-line-markup},
849 @code{make-center-markup}, or @code{make-column-markup} functions
853 (markup (make-line-markup (function-that-returns-markups)))
857 @node How markups work internally
858 @subsection How markups work internally
863 \raise #0.5 "text example"
867 @code{\raise} is actually represented by the @code{raise-markup}
868 function. The markup expression is stored as
871 (list raise-markup 0.5 (list simple-markup "text example"))
874 When the markup is converted to printable objects (Stencils), the
875 @code{raise-markup} function is called as
880 @var{list of property alists}
882 @var{the "text example" markup})
885 The @code{raise-markup} function first creates the stencil for the
886 @code{text example} string, and then it raises that Stencil by 0.5
887 staff space. This is a rather simple example; more complex examples
889 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
892 @node New markup command definition
893 @subsection New markup command definition
895 New markup commands can be defined
896 with the @code{define-markup-command} Scheme macro.
899 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
900 (@var{arg1-type?} @var{arg2-type?} ...)
908 @var{i}th command argument
910 a type predicate for the i@var{th} argument
912 the `layout' definition
914 a list of alists, containing all active properties.
917 As a simple example, we show how to add a @code{\smallcaps} command,
918 which selects a small caps font. Normally we could select the
922 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
926 This selects the caps font by setting the @code{font-shape} property to
927 @code{#'caps} for interpreting @code{Text-in-caps}.
929 To make the above available as @code{\smallcaps} command, we must
930 define a function using @code{define-markup-command}. The command should
931 take a single argument of type @code{markup}. Therefore the start of the
932 definition should read
935 (define-markup-command (smallcaps layout props argument) (markup?)
940 What follows is the content of the command: we should interpret
941 the @code{argument} as a markup, i.e.,
944 (interpret-markup layout @dots{} argument)
948 This interpretation should add @code{'(font-shape . caps)} to the active
949 properties, so we substitute the following for the @dots{} in the
953 (cons (list '(font-shape . caps) ) props)
957 The variable @code{props} is a list of alists, and we prepend to it by
958 cons'ing a list with the extra setting.
961 Suppose that we are typesetting a recitative in an opera and
962 we would like to define a command that will show character names in a
963 custom manner. Names should be printed with small caps and moved a
964 bit to the left and top. We will define a @code{\character} command
965 which takes into account the necessary translation and uses the newly
966 defined @code{\smallcaps} command:
969 #(define-markup-command (character layout props name) (string?)
970 "Print the character name in small caps, translated to the left and
971 top. Syntax: \\character #\"name\""
972 (interpret-markup layout props
973 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
976 There is one complication that needs explanation: texts above and below
977 the staff are moved vertically to be at a certain distance (the
978 @code{padding} property) from the staff and the notes. To make sure
979 that this mechanism does not annihilate the vertical effect of our
980 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
981 translated text. Now the @code{#:hspace 0} will be put above the notes,
983 @code{name} is moved in relation to that empty string. The net effect is
984 that the text is moved to the upper left.
986 The final result is as follows:
990 c''^\markup \character #"Cleopatra"
991 e'^\markup \character #"Giulio Cesare"
995 @lilypond[quote,ragged-right]
996 #(define-markup-command (smallcaps layout props str) (string?)
997 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
998 (interpret-markup layout props
1001 (if (= (string-length s) 0)
1003 (markup #:large (string-upcase (substring s 0 1))
1004 #:translate (cons -0.6 0)
1005 #:tiny (string-upcase (substring s 1)))))
1006 (string-split str #\Space)))))
1008 #(define-markup-command (character layout props name) (string?)
1009 "Print the character name in small caps, translated to the left and
1010 top. Syntax: \\character #\"name\""
1011 (interpret-markup layout props
1012 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1015 c''^\markup \character #"Cleopatra" c'' c'' c''
1016 e'^\markup \character #"Giulio Cesare" e' e' e'
1020 We have used the @code{caps} font shape, but suppose that our font
1021 does not have a small-caps variant. In that case we have to fake
1022 the small caps font by setting a string in upcase with the first
1023 letter a little larger:
1026 #(define-markup-command (smallcaps layout props str) (string?)
1027 "Print the string argument in small caps."
1028 (interpret-markup layout props
1031 (if (= (string-length s) 0)
1033 (markup #:large (string-upcase (substring s 0 1))
1034 #:translate (cons -0.6 0)
1035 #:tiny (string-upcase (substring s 1)))))
1036 (string-split str #\Space)))))
1039 The @code{smallcaps} command first splits its string argument into
1040 tokens separated by spaces (@code{(string-split str #\Space)}); for
1041 each token, a markup is built with the first letter made large and
1042 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1043 second markup built with the following letters made tiny and upcased
1044 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1045 introduces a space between markups on a line, the second markup is
1046 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1047 the markups built for each token are put in a line by
1048 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1049 to the @code{interpret-markup} function, with the @code{layout} and
1050 @code{props} arguments.
1052 Note: there is now an internal command @code{\smallCaps} which can
1053 be used to set text in small caps. See
1054 @ref{Overview of text markup commands} for details.
1058 @node Contexts for programmers
1059 @section Contexts for programmers
1062 * Context evaluation::
1063 * Running a function on all layout objects::
1066 @node Context evaluation
1067 @subsection Context evaluation
1069 @cindex calling code during interpreting
1070 @funindex \applyContext
1072 Contexts can be modified during interpretation with Scheme code. The
1075 \applyContext @var{function}
1078 @var{function} should be a Scheme function taking a single argument,
1079 being the context to apply it to. The following code will print the
1080 current bar number on the standard output during the compile:
1085 (format #t "\nWe were called in barnumber ~a.\n"
1086 (ly:context-property x 'currentBarNumber)))
1091 @node Running a function on all layout objects
1092 @subsection Running a function on all layout objects
1095 @cindex calling code on layout objects
1096 @funindex \applyOutput
1099 The most versatile way of tuning an object is @code{\applyOutput}. Its
1102 \applyOutput @var{context} @var{proc}
1106 where @var{proc} is a Scheme function, taking three arguments.
1108 When interpreted, the function @var{proc} is called for every layout
1109 object found in the context @var{context}, with the following
1112 @item the layout object itself,
1113 @item the context where the layout object was created, and
1114 @item the context where @code{\applyOutput} is processed.
1118 In addition, the cause of the layout object, i.e., the music
1119 expression or object that was responsible for creating it, is in the
1120 object property @code{cause}. For example, for a note head, this is a
1121 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1122 this is a @internalsref{NoteHead} object.
1124 Here is a function to use for @code{\applyOutput}; it blanks
1125 note-heads on the center-line:
1128 (define (blanker grob grob-origin context)
1129 (if (and (memq (ly:grob-property grob 'interfaces)
1130 note-head-interface)
1131 (eq? (ly:grob-property grob 'staff-position) 0))
1132 (set! (ly:grob-property grob 'transparent) #t)))
1136 @node Scheme procedures as properties
1137 @section Scheme procedures as properties
1139 Properties (like thickness, direction, etc.) can be set at fixed values
1140 with \override, e.g.
1143 \override Stem #'thickness = #2.0
1146 Properties can also be set to a Scheme procedure,
1148 @lilypond[fragment,verbatim,quote,relative=2]
1149 \override Stem #'thickness = #(lambda (grob)
1150 (if (= UP (ly:grob-property grob 'direction))
1156 Procedures may also be combined like that with
1157 "grob closure". Here is a setting from
1158 @code{AccidentalSuggestion},
1162 ,(ly:make-simple-closure
1164 ,(ly:make-simple-closure
1165 (list ly:self-alignment-interface::centered-on-x-parent))
1166 ,(ly:make-simple-closure
1167 (list ly:self-alignment-interface::x-aligned-on-self)))))