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,
202 i@l ilypond[quote,verbatim,ragged-right]
203 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
204 #{ \override Stem #'length = #$(* 7.0 mag)
205 \override NoteHead #'font-size =
206 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
208 \revert Stem #'length
209 \revert NoteHead #'font-size #})
211 { c'2 \withAlt #0.5 {c'4 c'}
212 \withAlt #1.5 {c' c'} c'2 }
217 @subsection Void functions
219 A music function must return a music expression, but sometimes we
220 may want to have a function which does not involve music (such as
221 turning off Point and Click). To do this, we return a @code{void}
225 that is returned is the @code{(make-music ...)}. With the
226 @code{'void} property set to @code{#t}, the parser is told to
227 actually disregard this returned music
228 expression. Thus the important part of the void music function is the
229 processing done by the function, not the music expression that is
234 #(define-music-function (parser location) ()
235 (ly:set-option 'point-and-click #f)
236 (make-music 'SequentialMusic 'void #t))
238 \noPointAndClick % disable point and click
242 @node Programmer interfaces
243 @section Programmer interfaces
245 This section contains information about mixing LilyPond
249 * Input variables and Scheme::
250 * Internal music representation::
254 @node Input variables and Scheme
255 @subsection Input variables and Scheme
257 The input format supports the notion of variables: in the following
258 example, a music expression is assigned to a variable with the name
262 traLaLa = @{ c'4 d'4 @}
267 There is also a form of scoping: in the following example, the
268 @code{\layout} block also contains a @code{traLaLa} variable, which is
269 independent of the outer @code{\traLaLa}.
271 traLaLa = @{ c'4 d'4 @}
272 \layout @{ traLaLa = 1.0 @}
275 In effect, each input file is a scope, and all @code{\header},
276 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
279 Both variables and scoping are implemented in the GUILE module system.
280 An anonymous Scheme module is attached to each scope. An assignment of
283 traLaLa = @{ c'4 d'4 @}
287 is internally converted to a Scheme definition
289 (define traLaLa @var{Scheme value of ``@code{... }''})
292 This means that input variables and Scheme variables may be freely
293 mixed. In the following example, a music fragment is stored in the
294 variable @code{traLaLa}, and duplicated using Scheme. The result is
295 imported in a @code{\score} block by means of a second variable
298 traLaLa = @{ c'4 d'4 @}
300 #(define newLa (map ly:music-deep-copy
301 (list traLaLa traLaLa)))
303 (make-sequential-music newLa))
308 In the above example, music expressions can be `exported' from the
309 input to the Scheme interpreter. The opposite is also possible. By
310 wrapping a Scheme value in the function @code{ly:export}, a Scheme
311 value is interpreted as if it were entered in LilyPond syntax. Instead
312 of defining @code{\twice}, the example above could also have been
316 @{ #(ly:export (make-sequential-music (list newLa))) @}
319 Scheme code is evaluated as soon as the parser encounters it. To
320 define some Scheme code in a macro (to be called later), use
321 @ref{Void functions} or
325 (ly:set-option 'point-and-click #f))
335 Mixing Scheme and LilyPond identifiers is not possible with the
336 @code{--safe} option.
339 @node Internal music representation
340 @subsection Internal music representation
342 When a music expression is parsed, it is converted into a set of
343 Scheme music objects. The defining property of a music object is that
344 it takes up time. Time is a rational number that measures the length
345 of a piece of music in whole notes.
347 A music object has three kinds of types:
350 music name: Each music expression has a name. For example, a note
351 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
352 a @internalsref{SimultaneousMusic}. A list of all expressions
353 available is in the Program reference manual, under
354 @internalsref{Music expressions}.
357 `type' or interface: Each music name has several `types' or
358 interfaces, for example, a note is an @code{event}, but it is also a
359 @code{note-event}, a @code{rhythmic-event}, and a
360 @code{melodic-event}. All classes of music are listed in the
361 Program reference, under
362 @internalsref{Music classes}.
365 C++ object: Each music object is represented by an object of the C++
369 The actual information of a music expression is stored in properties.
370 For example, a @internalsref{NoteEvent} has @code{pitch} and
371 @code{duration} properties that store the pitch and duration of that
372 note. A list of all properties available is in the internals manual,
373 under @internalsref{Music properties}.
375 A compound music expression is a music object that contains other
376 music objects in its properties. A list of objects can be stored in
377 the @code{elements} property of a music object, or a single `child'
378 music object in the @code{element} object. For example,
379 @internalsref{SequentialMusic} has its children in @code{elements},
380 and @internalsref{GraceMusic} has its single argument in
381 @code{element}. The body of a repeat is stored in the @code{element}
382 property of @internalsref{RepeatedMusic}, and the alternatives in
387 @node Building complicated functions
388 @section Building complicated functions
390 This section explains how to gather the information necessary
391 to create complicated music functions.
394 * Displaying music expressions::
396 * Doubling a note with slurs (example)::
397 * Adding articulation to notes (example)::
401 @node Displaying music expressions
402 @subsection Displaying music expressions
404 @cindex internal storage
405 @funindex \displayMusic
406 @funindex \displayLilyMusic
408 When writing a music function it is often instructive to inspect how
409 a music expression is stored internally. This can be done with the
410 music function @code{\displayMusic}
414 \displayMusic @{ c'4\f @}
431 (ly:make-duration 2 0 1 1)
433 (ly:make-pitch 0 0 0))
435 'AbsoluteDynamicEvent
440 By default, LilyPond will print these messages to the console along
441 with all the other messages. To split up these messages and save
442 the results of @code{\display@{STUFF@}}, redirect the output to
446 lilypond file.ly >display.txt
449 With a bit of reformatting, the above information is
453 (make-music 'SequentialMusic
454 'elements (list (make-music 'EventChord
455 'elements (list (make-music 'NoteEvent
456 'duration (ly:make-duration 2 0 1 1)
457 'pitch (ly:make-pitch 0 0 0))
458 (make-music 'AbsoluteDynamicEvent
462 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
463 and its inner expressions are stored as a list in its @code{'elements}
464 property. A note is represented as an @code{EventChord} expression,
465 containing a @code{NoteEvent} object (storing the duration and
466 pitch properties) and any extra information (in this case, an
467 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
470 @node Music properties
471 @subsection Music properties
473 The @code{NoteEvent} object is the first object of the
474 @code{'elements} property of @code{someNote}.
478 \displayMusic \someNote
486 (ly:make-duration 2 0 1 1)
488 (ly:make-pitch 0 0 0))))
491 The @code{display-scheme-music} function is the function used by
492 @code{\displayMusic} to display the Scheme representation of a music
496 #(display-scheme-music (first (ly:music-property someNote 'elements)))
501 (ly:make-duration 2 0 1 1)
503 (ly:make-pitch 0 0 0))
506 Then the note pitch is accessed through the @code{'pitch} property
507 of the @code{NoteEvent} object,
510 #(display-scheme-music
511 (ly:music-property (first (ly:music-property someNote 'elements))
514 (ly:make-pitch 0 0 0)
517 The note pitch can be changed by setting this 'pitch property,
520 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
522 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
523 \displayLilyMusic \someNote
529 @node Doubling a note with slurs (example)
530 @subsection Doubling a note with slurs (example)
532 Suppose we want to create a function which translates
533 input like ``@code{a}'' into ``@code{a( a)}''. We begin
534 by examining the internal representation of the music
535 we want to end up with.
538 \displayMusic@{ a'( a') @}
549 (ly:make-duration 2 0 1 1)
551 (ly:make-pitch 0 5 0))
562 (ly:make-duration 2 0 1 1)
564 (ly:make-pitch 0 5 0))
571 The bad news is that the @code{SlurEvent} expressions
572 must be added ``inside'' the note (or more precisely,
573 inside the @code{EventChord} expression).
575 Now we examine the input,
587 (ly:make-duration 2 0 1 1)
589 (ly:make-pitch 0 5 0))))))
592 So in our function, we need to clone this expression (so that we
593 have two notes to build the sequence), add @code{SlurEvents} to the
594 @code{'elements} property of each one, and finally make a
595 @code{SequentialMusic} with the two @code{EventChords}.
598 doubleSlur = #(def-music-function (parser location note) (ly:music?)
599 "Return: @{ note ( note ) @}.
600 `note' is supposed to be an EventChord."
601 (let ((note2 (ly:music-deep-copy note)))
602 (set! (ly:music-property note 'elements)
603 (cons (make-music 'SlurEvent 'span-direction -1)
604 (ly:music-property note 'elements)))
605 (set! (ly:music-property note2 'elements)
606 (cons (make-music 'SlurEvent 'span-direction 1)
607 (ly:music-property note2 'elements)))
608 (make-music 'SequentialMusic 'elements (list note note2))))
612 @node Adding articulation to notes (example)
613 @subsection Adding articulation to notes (example)
615 The easy way to add articulation to notes is to merge two music
616 expressions into one context, as explained in
617 @ref{Creating contexts}. However, suppose that we want to write
618 a music function which does this.
620 A @code{$variable} inside the @code{#@{...#@}} notation is like
621 using a regular @code{\variable} in classical LilyPond
622 notation. We know that
629 will not work in LilyPond. We could avoid this problem by attaching
630 the articulation to a fake note,
633 @{ << \music s1*0-.-> @}
637 but for the sake of this example, we will learn how to do this in
638 Scheme. We begin by examining our input and desired output,
650 (ly:make-duration 2 0 1 1)
652 (ly:make-pitch -1 0 0))))
663 (ly:make-duration 2 0 1 1)
665 (ly:make-pitch -1 0 0))
672 We see that a note (@code{c4}) is represented as an @code{EventChord}
673 expression, with a @code{NoteEvent} expression in its elements list. To
674 add a marcato articulation, an @code{ArticulationEvent} expression must
675 be added to the elements property of the @code{EventChord}
678 To build this function, we begin with
681 (define (add-marcato event-chord)
682 "Add a marcato ArticulationEvent to the elements of `event-chord',
683 which is supposed to be an EventChord expression."
684 (let ((result-event-chord (ly:music-deep-copy event-chord)))
685 (set! (ly:music-property result-event-chord 'elements)
686 (cons (make-music 'ArticulationEvent
687 'articulation-type "marcato")
688 (ly:music-property result-event-chord 'elements)))
692 The first line is the way to define a function in Scheme: the function
693 name is @code{add-marcato}, and has one variable called
694 @code{event-chord}. In Scheme, the type of variable is often clear
695 from its name. (this is good practice in other programming languages,
703 is a description of what the function does. This is not strictly
704 necessary, but just like clear variable names, it is good practice.
707 (let ((result-event-chord (ly:music-deep-copy event-chord)))
710 `@code{let}' is used to declare local variables. Here we use one local
711 variable, named `@code{result-event-chord}', to which we give the value
712 @code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
713 a function specific to LilyPond, like all functions prefixed by
714 `@code{ly:}'. It is use to make a copy of a music
715 expression. Here we copy `@code{event-chord} (the parameter of the
716 function). Recall that our purpose is to add a marcato to an
717 @code{EventChord} expression. It is better to not modify the
718 @code{EventChord} which was given as an argument, because it may be
721 Now we have a @code{result-event-chord}, which is a
722 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
723 add the marcato to its elements list property.
726 (set! place new-value)
729 Here, what we want to set (the "place") is the "elements" property of
730 @code{result-event-chord} expression
733 (ly:music-property result-event-chord 'elements)
736 @code{ly:music-property} is the function used to access music properties
737 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
738 see in the @code{\displayMusic} output above). The new value is the
739 former elements property, with an extra item: the
740 @code{MarcatoEvent} expression, which we copy from the
741 @code{\displayMusic} output,
744 (cons (make-music 'ArticulationEvent
745 'articulation-type "marcato")
746 (ly:music-property result-event-chord 'elements))
749 `@code{cons}' is used to add an element to a list without modifying the
750 original list. This is what we
751 want: the same list as before, plus the new @code{ArticulationEvent}
752 expression. The order inside the elements property is not important here.
754 Finally, once we have added the @code{MarcatoEvent} to its elements
755 property, we can return @code{result-event-chord}, hence the last line of
758 Now we transform the @code{add-marcato} function into a music
762 addMarcato = #(define-music-function (parser location event-chord)
764 "Add a marcato ArticulationEvent to the elements of `event-chord',
765 which is supposed to be an EventChord expression."
766 (let ((result-event-chord (ly:music-deep-copy event-chord)))
767 (set! (ly:music-property result-event-chord 'elements)
768 (cons (make-music 'ArticulationEvent
769 'articulation-type "marcato")
770 (ly:music-property result-event-chord 'elements)))
774 We may verify that this music function works correctly,
777 \displayMusic \addMarcato c4
781 @node Markup programmer interface
782 @section Markup programmer interface
784 Markups are implemented as special Scheme functions which produce a
785 Stencil object given a number of arguments.
788 * Markup construction in Scheme::
789 * How markups work internally::
790 * New markup command definition::
794 @node Markup construction in Scheme
795 @subsection Markup construction in Scheme
797 @cindex defining markup commands
799 The @code{markup} macro builds markup expressions in Scheme while
800 providing a LilyPond-like syntax. For example,
802 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
803 #:bigger #:line ("foo" "bar" "baz")))
809 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
810 \bigger \line @{ foo bar baz @} @}
814 This example demonstrates the main translation rules between regular
815 LilyPond markup syntax and Scheme markup syntax.
818 @multitable @columnfractions .3 .3
819 @item @b{LilyPond} @tab @b{Scheme}
820 @item @code{\markup markup1} @tab @code{(markup markup1)}
821 @item @code{\markup @{ markup1 markup2 ... @}} @tab
822 @code{(markup markup1 markup2 ... )}
823 @item @code{\command} @tab @code{#:command}
824 @item @code{\variable} @tab @code{variable}
825 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
826 @item @code{string} @tab @code{"string"}
827 @item @code{#scheme-arg} @tab @code{scheme-arg}
831 The whole Scheme language is accessible inside the
832 @code{markup} macro. For example, You may use function calls inside
833 @code{markup} in order to manipulate character strings. This is
834 useful when defining new markup commands (see
835 @ref{New markup command definition}).
840 The markup-list argument of commands such as @code{#:line},
841 @code{#:center}, and @code{#:column} cannot be a variable or
842 the result of a function call.
845 (markup #:line (function-that-returns-markups))
849 is invalid. One should use the @code{make-line-markup},
850 @code{make-center-markup}, or @code{make-column-markup} functions
854 (markup (make-line-markup (function-that-returns-markups)))
858 @node How markups work internally
859 @subsection How markups work internally
864 \raise #0.5 "text example"
868 @code{\raise} is actually represented by the @code{raise-markup}
869 function. The markup expression is stored as
872 (list raise-markup 0.5 (list simple-markup "text example"))
875 When the markup is converted to printable objects (Stencils), the
876 @code{raise-markup} function is called as
881 @var{list of property alists}
883 @var{the "text example" markup})
886 The @code{raise-markup} function first creates the stencil for the
887 @code{text example} string, and then it raises that Stencil by 0.5
888 staff space. This is a rather simple example; more complex examples
890 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
893 @node New markup command definition
894 @subsection New markup command definition
896 New markup commands can be defined
897 with the @code{define-markup-command} Scheme macro.
900 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
901 (@var{arg1-type?} @var{arg2-type?} ...)
909 @var{i}th command argument
911 a type predicate for the i@var{th} argument
913 the `layout' definition
915 a list of alists, containing all active properties.
918 As a simple example, we show how to add a @code{\smallcaps} command,
919 which selects a small caps font. Normally we could select the
923 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
927 This selects the caps font by setting the @code{font-shape} property to
928 @code{#'caps} for interpreting @code{Text-in-caps}.
930 To make the above available as @code{\smallcaps} command, we must
931 define a function using @code{define-markup-command}. The command should
932 take a single argument of type @code{markup}. Therefore the start of the
933 definition should read
936 (define-markup-command (smallcaps layout props argument) (markup?)
941 What follows is the content of the command: we should interpret
942 the @code{argument} as a markup, i.e.,
945 (interpret-markup layout @dots{} argument)
949 This interpretation should add @code{'(font-shape . caps)} to the active
950 properties, so we substitute the following for the @dots{} in the
954 (cons (list '(font-shape . caps) ) props)
958 The variable @code{props} is a list of alists, and we prepend to it by
959 cons'ing a list with the extra setting.
962 Suppose that we are typesetting a recitative in an opera and
963 we would like to define a command that will show character names in a
964 custom manner. Names should be printed with small caps and moved a
965 bit to the left and top. We will define a @code{\character} command
966 which takes into account the necessary translation and uses the newly
967 defined @code{\smallcaps} command:
970 #(define-markup-command (character layout props name) (string?)
971 "Print the character name in small caps, translated to the left and
972 top. Syntax: \\character #\"name\""
973 (interpret-markup layout props
974 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
977 There is one complication that needs explanation: texts above and below
978 the staff are moved vertically to be at a certain distance (the
979 @code{padding} property) from the staff and the notes. To make sure
980 that this mechanism does not annihilate the vertical effect of our
981 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
982 translated text. Now the @code{#:hspace 0} will be put above the notes,
984 @code{name} is moved in relation to that empty string. The net effect is
985 that the text is moved to the upper left.
987 The final result is as follows:
991 c''^\markup \character #"Cleopatra"
992 e'^\markup \character #"Giulio Cesare"
996 @lilypond[quote,ragged-right]
997 #(define-markup-command (smallcaps layout props str) (string?)
998 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
999 (interpret-markup layout props
1002 (if (= (string-length s) 0)
1004 (markup #:large (string-upcase (substring s 0 1))
1005 #:translate (cons -0.6 0)
1006 #:tiny (string-upcase (substring s 1)))))
1007 (string-split str #\Space)))))
1009 #(define-markup-command (character layout props name) (string?)
1010 "Print the character name in small caps, translated to the left and
1011 top. Syntax: \\character #\"name\""
1012 (interpret-markup layout props
1013 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1016 c''^\markup \character #"Cleopatra" c'' c'' c''
1017 e'^\markup \character #"Giulio Cesare" e' e' e'
1021 We have used the @code{caps} font shape, but suppose that our font
1022 does not have a small-caps variant. In that case we have to fake
1023 the small caps font by setting a string in upcase with the first
1024 letter a little larger:
1027 #(define-markup-command (smallcaps layout props str) (string?)
1028 "Print the string argument in small caps."
1029 (interpret-markup layout props
1032 (if (= (string-length s) 0)
1034 (markup #:large (string-upcase (substring s 0 1))
1035 #:translate (cons -0.6 0)
1036 #:tiny (string-upcase (substring s 1)))))
1037 (string-split str #\Space)))))
1040 The @code{smallcaps} command first splits its string argument into
1041 tokens separated by spaces (@code{(string-split str #\Space)}); for
1042 each token, a markup is built with the first letter made large and
1043 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1044 second markup built with the following letters made tiny and upcased
1045 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1046 introduces a space between markups on a line, the second markup is
1047 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1048 the markups built for each token are put in a line by
1049 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1050 to the @code{interpret-markup} function, with the @code{layout} and
1051 @code{props} arguments.
1053 Note: there is now an internal command @code{\smallCaps} which can
1054 be used to set text in small caps. See
1055 @ref{Overview of text markup commands} for details.
1059 @node Contexts for programmers
1060 @section Contexts for programmers
1063 * Context evaluation::
1064 * Running a function on all layout objects::
1067 @node Context evaluation
1068 @subsection Context evaluation
1070 @cindex calling code during interpreting
1071 @funindex \applyContext
1073 Contexts can be modified during interpretation with Scheme code. The
1076 \applyContext @var{function}
1079 @var{function} should be a Scheme function taking a single argument,
1080 being the context to apply it to. The following code will print the
1081 current bar number on the standard output during the compile:
1086 (format #t "\nWe were called in barnumber ~a.\n"
1087 (ly:context-property x 'currentBarNumber)))
1092 @node Running a function on all layout objects
1093 @subsection Running a function on all layout objects
1096 @cindex calling code on layout objects
1097 @funindex \applyOutput
1100 The most versatile way of tuning an object is @code{\applyOutput}. Its
1103 \applyOutput @var{context} @var{proc}
1107 where @var{proc} is a Scheme function, taking three arguments.
1109 When interpreted, the function @var{proc} is called for every layout
1110 object found in the context @var{context}, with the following
1113 @item the layout object itself,
1114 @item the context where the layout object was created, and
1115 @item the context where @code{\applyOutput} is processed.
1119 In addition, the cause of the layout object, i.e., the music
1120 expression or object that was responsible for creating it, is in the
1121 object property @code{cause}. For example, for a note head, this is a
1122 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1123 this is a @internalsref{NoteHead} object.
1125 Here is a function to use for @code{\applyOutput}; it blanks
1126 note-heads on the center-line:
1129 (define (blanker grob grob-origin context)
1130 (if (and (memq (ly:grob-property grob 'interfaces)
1131 note-head-interface)
1132 (eq? (ly:grob-property grob 'staff-position) 0))
1133 (set! (ly:grob-property grob 'transparent) #t)))
1137 @node Scheme procedures as properties
1138 @section Scheme procedures as properties
1140 Properties (like thickness, direction, etc.) can be set at fixed values
1141 with \override, e.g.
1144 \override Stem #'thickness = #2.0
1147 Properties can also be set to a Scheme procedure,
1149 @lilypond[fragment,verbatim,quote,relative=2]
1150 \override Stem #'thickness = #(lambda (grob)
1151 (if (= UP (ly:grob-property grob 'direction))
1157 Procedures may also be combined like that with
1158 "grob closure". Here is a setting from
1159 @code{AccidentalSuggestion},
1163 ,(ly:make-simple-closure
1165 ,(ly:make-simple-closure
1166 (list ly:self-alignment-interface::centered-on-x-parent))
1167 ,(ly:make-simple-closure
1168 (list ly:self-alignment-interface::x-aligned-on-self)))))