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 }
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
297 traLaLa = @{ c'4 d'4 @}
299 %% deal with parser lookahead
300 #(display "this needs to be here, sorry!")
302 #(define newLa (map ly:music-deep-copy
303 (list traLaLa traLaLa)))
305 (make-sequential-music newLa))
310 Due to parser lookahead
312 In this example, the assignment happens after parser has verified that
313 nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
314 the dummy statement in the above example, the @code{newLa} definition
315 is executed before @code{traLaLa} is defined, leading to a syntax
318 The above example shows how to `export' music expressions from the
319 input to the Scheme interpreter. The opposite is also possible. By
320 wrapping a Scheme value in the function @code{ly:export}, a Scheme
321 value is interpreted as if it were entered in LilyPond syntax.
322 Instead of defining @code{\twice}, the example above could also have
326 @{ #(ly:export (make-sequential-music (list newLa))) @}
329 Scheme code is evaluated as soon as the parser encounters it. To
330 define some Scheme code in a macro (to be called later), use
331 @ref{Void functions} or
335 (ly:set-option 'point-and-click #f))
345 Mixing Scheme and LilyPond identifiers is not possible with the
346 @code{--safe} option.
349 @node Internal music representation
350 @subsection Internal music representation
352 When a music expression is parsed, it is converted into a set of
353 Scheme music objects. The defining property of a music object is that
354 it takes up time. Time is a rational number that measures the length
355 of a piece of music in whole notes.
357 A music object has three kinds of types:
360 music name: Each music expression has a name. For example, a note
361 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
362 a @internalsref{SimultaneousMusic}. A list of all expressions
363 available is in the Program reference manual, under
364 @internalsref{Music expressions}.
367 `type' or interface: Each music name has several `types' or
368 interfaces, for example, a note is an @code{event}, but it is also a
369 @code{note-event}, a @code{rhythmic-event}, and a
370 @code{melodic-event}. All classes of music are listed in the
371 Program reference, under
372 @internalsref{Music classes}.
375 C++ object: Each music object is represented by an object of the C++
379 The actual information of a music expression is stored in properties.
380 For example, a @internalsref{NoteEvent} has @code{pitch} and
381 @code{duration} properties that store the pitch and duration of that
382 note. A list of all properties available is in the internals manual,
383 under @internalsref{Music properties}.
385 A compound music expression is a music object that contains other
386 music objects in its properties. A list of objects can be stored in
387 the @code{elements} property of a music object, or a single `child'
388 music object in the @code{element} object. For example,
389 @internalsref{SequentialMusic} has its children in @code{elements},
390 and @internalsref{GraceMusic} has its single argument in
391 @code{element}. The body of a repeat is stored in the @code{element}
392 property of @internalsref{RepeatedMusic}, and the alternatives in
397 @node Building complicated functions
398 @section Building complicated functions
400 This section explains how to gather the information necessary
401 to create complicated music functions.
404 * Displaying music expressions::
406 * Doubling a note with slurs (example)::
407 * Adding articulation to notes (example)::
411 @node Displaying music expressions
412 @subsection Displaying music expressions
414 @cindex internal storage
415 @funindex \displayMusic
416 @funindex \displayLilyMusic
418 When writing a music function it is often instructive to inspect how
419 a music expression is stored internally. This can be done with the
420 music function @code{\displayMusic}
424 \displayMusic @{ c'4\f @}
441 (ly:make-duration 2 0 1 1)
443 (ly:make-pitch 0 0 0))
445 'AbsoluteDynamicEvent
450 By default, LilyPond will print these messages to the console along
451 with all the other messages. To split up these messages and save
452 the results of @code{\display@{STUFF@}}, redirect the output to
456 lilypond file.ly >display.txt
459 With a bit of reformatting, the above information is
463 (make-music 'SequentialMusic
464 'elements (list (make-music 'EventChord
465 'elements (list (make-music 'NoteEvent
466 'duration (ly:make-duration 2 0 1 1)
467 'pitch (ly:make-pitch 0 0 0))
468 (make-music 'AbsoluteDynamicEvent
472 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
473 and its inner expressions are stored as a list in its @code{'elements}
474 property. A note is represented as an @code{EventChord} expression,
475 containing a @code{NoteEvent} object (storing the duration and
476 pitch properties) and any extra information (in this case, an
477 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
480 @node Music properties
481 @subsection Music properties
483 The @code{NoteEvent} object is the first object of the
484 @code{'elements} property of @code{someNote}.
488 \displayMusic \someNote
496 (ly:make-duration 2 0 1 1)
498 (ly:make-pitch 0 0 0))))
501 The @code{display-scheme-music} function is the function used by
502 @code{\displayMusic} to display the Scheme representation of a music
506 #(display-scheme-music (first (ly:music-property someNote 'elements)))
511 (ly:make-duration 2 0 1 1)
513 (ly:make-pitch 0 0 0))
516 Then the note pitch is accessed through the @code{'pitch} property
517 of the @code{NoteEvent} object,
520 #(display-scheme-music
521 (ly:music-property (first (ly:music-property someNote 'elements))
524 (ly:make-pitch 0 0 0)
527 The note pitch can be changed by setting this 'pitch property,
530 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
532 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
533 \displayLilyMusic \someNote
539 @node Doubling a note with slurs (example)
540 @subsection Doubling a note with slurs (example)
542 Suppose we want to create a function which translates
543 input like ``@code{a}'' into ``@code{a( a)}''. We begin
544 by examining the internal representation of the music
545 we want to end up with.
548 \displayMusic@{ a'( a') @}
559 (ly:make-duration 2 0 1 1)
561 (ly:make-pitch 0 5 0))
572 (ly:make-duration 2 0 1 1)
574 (ly:make-pitch 0 5 0))
581 The bad news is that the @code{SlurEvent} expressions
582 must be added ``inside'' the note (or more precisely,
583 inside the @code{EventChord} expression).
585 Now we examine the input,
597 (ly:make-duration 2 0 1 1)
599 (ly:make-pitch 0 5 0))))))
602 So in our function, we need to clone this expression (so that we
603 have two notes to build the sequence), add @code{SlurEvents} to the
604 @code{'elements} property of each one, and finally make a
605 @code{SequentialMusic} with the two @code{EventChords}.
608 doubleSlur = #(define-music-function (parser location note) (ly:music?)
609 "Return: @{ note ( note ) @}.
610 `note' is supposed to be an EventChord."
611 (let ((note2 (ly:music-deep-copy note)))
612 (set! (ly:music-property note 'elements)
613 (cons (make-music 'SlurEvent 'span-direction -1)
614 (ly:music-property note 'elements)))
615 (set! (ly:music-property note2 'elements)
616 (cons (make-music 'SlurEvent 'span-direction 1)
617 (ly:music-property note2 'elements)))
618 (make-music 'SequentialMusic 'elements (list note note2))))
622 @node Adding articulation to notes (example)
623 @subsection Adding articulation to notes (example)
625 The easy way to add articulation to notes is to merge two music
626 expressions into one context, as explained in
627 @ref{Creating contexts}. However, suppose that we want to write
628 a music function which does this.
630 A @code{$variable} inside the @code{#@{...#@}} notation is like
631 using a regular @code{\variable} in classical LilyPond
632 notation. We know that
639 will not work in LilyPond. We could avoid this problem by attaching
640 the articulation to a fake note,
643 @{ << \music s1*0-.-> @}
647 but for the sake of this example, we will learn how to do this in
648 Scheme. We begin by examining our input and desired output,
660 (ly:make-duration 2 0 1 1)
662 (ly:make-pitch -1 0 0))))
673 (ly:make-duration 2 0 1 1)
675 (ly:make-pitch -1 0 0))
682 We see that a note (@code{c4}) is represented as an @code{EventChord}
683 expression, with a @code{NoteEvent} expression in its elements list. To
684 add a marcato articulation, an @code{ArticulationEvent} expression must
685 be added to the elements property of the @code{EventChord}
688 To build this function, we begin with
691 (define (add-marcato event-chord)
692 "Add a marcato ArticulationEvent to the elements of `event-chord',
693 which is supposed to be an EventChord expression."
694 (let ((result-event-chord (ly:music-deep-copy event-chord)))
695 (set! (ly:music-property result-event-chord 'elements)
696 (cons (make-music 'ArticulationEvent
697 'articulation-type "marcato")
698 (ly:music-property result-event-chord 'elements)))
702 The first line is the way to define a function in Scheme: the function
703 name is @code{add-marcato}, and has one variable called
704 @code{event-chord}. In Scheme, the type of variable is often clear
705 from its name. (this is good practice in other programming languages,
713 is a description of what the function does. This is not strictly
714 necessary, but just like clear variable names, it is good practice.
717 (let ((result-event-chord (ly:music-deep-copy event-chord)))
720 `@code{let}' is used to declare local variables. Here we use one local
721 variable, named `@code{result-event-chord}', to which we give the value
722 @code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
723 a function specific to LilyPond, like all functions prefixed by
724 `@code{ly:}'. It is use to make a copy of a music
725 expression. Here we copy `@code{event-chord} (the parameter of the
726 function). Recall that our purpose is to add a marcato to an
727 @code{EventChord} expression. It is better to not modify the
728 @code{EventChord} which was given as an argument, because it may be
731 Now we have a @code{result-event-chord}, which is a
732 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
733 add the marcato to its elements list property.
736 (set! place new-value)
739 Here, what we want to set (the "place") is the "elements" property of
740 @code{result-event-chord} expression
743 (ly:music-property result-event-chord 'elements)
746 @code{ly:music-property} is the function used to access music properties
747 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
748 see in the @code{\displayMusic} output above). The new value is the
749 former elements property, with an extra item: the
750 @code{MarcatoEvent} expression, which we copy from the
751 @code{\displayMusic} output,
754 (cons (make-music 'ArticulationEvent
755 'articulation-type "marcato")
756 (ly:music-property result-event-chord 'elements))
759 `@code{cons}' is used to add an element to a list without modifying the
760 original list. This is what we
761 want: the same list as before, plus the new @code{ArticulationEvent}
762 expression. The order inside the elements property is not important here.
764 Finally, once we have added the @code{MarcatoEvent} to its elements
765 property, we can return @code{result-event-chord}, hence the last line of
768 Now we transform the @code{add-marcato} function into a music
772 addMarcato = #(define-music-function (parser location event-chord)
774 "Add a marcato ArticulationEvent to the elements of `event-chord',
775 which is supposed to be an EventChord expression."
776 (let ((result-event-chord (ly:music-deep-copy event-chord)))
777 (set! (ly:music-property result-event-chord 'elements)
778 (cons (make-music 'ArticulationEvent
779 'articulation-type "marcato")
780 (ly:music-property result-event-chord 'elements)))
784 We may verify that this music function works correctly,
787 \displayMusic \addMarcato c4
791 @node Markup programmer interface
792 @section Markup programmer interface
794 Markups are implemented as special Scheme functions which produce a
795 Stencil object given a number of arguments.
798 * Markup construction in Scheme::
799 * How markups work internally::
800 * New markup command definition::
804 @node Markup construction in Scheme
805 @subsection Markup construction in Scheme
807 @cindex defining markup commands
809 The @code{markup} macro builds markup expressions in Scheme while
810 providing a LilyPond-like syntax. For example,
812 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
813 #:bigger #:line ("foo" "bar" "baz")))
819 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
820 \bigger \line @{ foo bar baz @} @}
824 This example demonstrates the main translation rules between regular
825 LilyPond markup syntax and Scheme markup syntax.
828 @multitable @columnfractions .3 .3
829 @item @b{LilyPond} @tab @b{Scheme}
830 @item @code{\markup markup1} @tab @code{(markup markup1)}
831 @item @code{\markup @{ markup1 markup2 ... @}} @tab
832 @code{(markup markup1 markup2 ... )}
833 @item @code{\command} @tab @code{#:command}
834 @item @code{\variable} @tab @code{variable}
835 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
836 @item @code{string} @tab @code{"string"}
837 @item @code{#scheme-arg} @tab @code{scheme-arg}
841 The whole Scheme language is accessible inside the
842 @code{markup} macro. For example, You may use function calls inside
843 @code{markup} in order to manipulate character strings. This is
844 useful when defining new markup commands (see
845 @ref{New markup command definition}).
850 The markup-list argument of commands such as @code{#:line},
851 @code{#:center}, and @code{#:column} cannot be a variable or
852 the result of a function call.
855 (markup #:line (function-that-returns-markups))
859 is invalid. One should use the @code{make-line-markup},
860 @code{make-center-markup}, or @code{make-column-markup} functions
864 (markup (make-line-markup (function-that-returns-markups)))
868 @node How markups work internally
869 @subsection How markups work internally
874 \raise #0.5 "text example"
878 @code{\raise} is actually represented by the @code{raise-markup}
879 function. The markup expression is stored as
882 (list raise-markup 0.5 (list simple-markup "text example"))
885 When the markup is converted to printable objects (Stencils), the
886 @code{raise-markup} function is called as
891 @var{list of property alists}
893 @var{the "text example" markup})
896 The @code{raise-markup} function first creates the stencil for the
897 @code{text example} string, and then it raises that Stencil by 0.5
898 staff space. This is a rather simple example; more complex examples
900 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
903 @node New markup command definition
904 @subsection New markup command definition
906 New markup commands can be defined
907 with the @code{define-markup-command} Scheme macro.
910 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
911 (@var{arg1-type?} @var{arg2-type?} ...)
919 @var{i}th command argument
921 a type predicate for the i@var{th} argument
923 the `layout' definition
925 a list of alists, containing all active properties.
928 As a simple example, we show how to add a @code{\smallcaps} command,
929 which selects a small caps font. Normally we could select the
933 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
937 This selects the caps font by setting the @code{font-shape} property to
938 @code{#'caps} for interpreting @code{Text-in-caps}.
940 To make the above available as @code{\smallcaps} command, we must
941 define a function using @code{define-markup-command}. The command should
942 take a single argument of type @code{markup}. Therefore the start of the
943 definition should read
946 (define-markup-command (smallcaps layout props argument) (markup?)
951 What follows is the content of the command: we should interpret
952 the @code{argument} as a markup, i.e.,
955 (interpret-markup layout @dots{} argument)
959 This interpretation should add @code{'(font-shape . caps)} to the active
960 properties, so we substitute the following for the @dots{} in the
964 (cons (list '(font-shape . caps) ) props)
968 The variable @code{props} is a list of alists, and we prepend to it by
969 cons'ing a list with the extra setting.
972 Suppose that we are typesetting a recitative in an opera and
973 we would like to define a command that will show character names in a
974 custom manner. Names should be printed with small caps and moved a
975 bit to the left and top. We will define a @code{\character} command
976 which takes into account the necessary translation and uses the newly
977 defined @code{\smallcaps} command:
980 #(define-markup-command (character layout props name) (string?)
981 "Print the character name in small caps, translated to the left and
982 top. Syntax: \\character #\"name\""
983 (interpret-markup layout props
984 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
987 There is one complication that needs explanation: texts above and below
988 the staff are moved vertically to be at a certain distance (the
989 @code{padding} property) from the staff and the notes. To make sure
990 that this mechanism does not annihilate the vertical effect of our
991 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
992 translated text. Now the @code{#:hspace 0} will be put above the notes,
994 @code{name} is moved in relation to that empty string. The net effect is
995 that the text is moved to the upper left.
997 The final result is as follows:
1001 c''^\markup \character #"Cleopatra"
1002 e'^\markup \character #"Giulio Cesare"
1006 @lilypond[quote,ragged-right]
1007 #(define-markup-command (smallcaps layout props str) (string?)
1008 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
1009 (interpret-markup layout props
1012 (if (= (string-length s) 0)
1014 (markup #:large (string-upcase (substring s 0 1))
1015 #:translate (cons -0.6 0)
1016 #:tiny (string-upcase (substring s 1)))))
1017 (string-split str #\Space)))))
1019 #(define-markup-command (character layout props name) (string?)
1020 "Print the character name in small caps, translated to the left and
1021 top. Syntax: \\character #\"name\""
1022 (interpret-markup layout props
1023 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1026 c''^\markup \character #"Cleopatra" c'' c'' c''
1027 e'^\markup \character #"Giulio Cesare" e' e' e'
1031 We have used the @code{caps} font shape, but suppose that our font
1032 does not have a small-caps variant. In that case we have to fake
1033 the small caps font by setting a string in upcase with the first
1034 letter a little larger:
1037 #(define-markup-command (smallcaps layout props str) (string?)
1038 "Print the string argument in small caps."
1039 (interpret-markup layout props
1042 (if (= (string-length s) 0)
1044 (markup #:large (string-upcase (substring s 0 1))
1045 #:translate (cons -0.6 0)
1046 #:tiny (string-upcase (substring s 1)))))
1047 (string-split str #\Space)))))
1050 The @code{smallcaps} command first splits its string argument into
1051 tokens separated by spaces (@code{(string-split str #\Space)}); for
1052 each token, a markup is built with the first letter made large and
1053 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1054 second markup built with the following letters made tiny and upcased
1055 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1056 introduces a space between markups on a line, the second markup is
1057 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1058 the markups built for each token are put in a line by
1059 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1060 to the @code{interpret-markup} function, with the @code{layout} and
1061 @code{props} arguments.
1063 Note: there is now an internal command @code{\smallCaps} which can
1064 be used to set text in small caps. See
1065 @ref{Overview of text markup commands} for details.
1069 @node Contexts for programmers
1070 @section Contexts for programmers
1073 * Context evaluation::
1074 * Running a function on all layout objects::
1077 @node Context evaluation
1078 @subsection Context evaluation
1080 @cindex calling code during interpreting
1081 @funindex \applyContext
1083 Contexts can be modified during interpretation with Scheme code. The
1086 \applyContext @var{function}
1089 @var{function} should be a Scheme function taking a single argument,
1090 being the context to apply it to. The following code will print the
1091 current bar number on the standard output during the compile:
1096 (format #t "\nWe were called in barnumber ~a.\n"
1097 (ly:context-property x 'currentBarNumber)))
1102 @node Running a function on all layout objects
1103 @subsection Running a function on all layout objects
1106 @cindex calling code on layout objects
1107 @funindex \applyOutput
1110 The most versatile way of tuning an object is @code{\applyOutput}. Its
1113 \applyOutput @var{context} @var{proc}
1117 where @var{proc} is a Scheme function, taking three arguments.
1119 When interpreted, the function @var{proc} is called for every layout
1120 object found in the context @var{context}, with the following
1123 @item the layout object itself,
1124 @item the context where the layout object was created, and
1125 @item the context where @code{\applyOutput} is processed.
1129 In addition, the cause of the layout object, i.e., the music
1130 expression or object that was responsible for creating it, is in the
1131 object property @code{cause}. For example, for a note head, this is a
1132 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1133 this is a @internalsref{NoteHead} object.
1135 Here is a function to use for @code{\applyOutput}; it blanks
1136 note-heads on the center-line:
1139 (define (blanker grob grob-origin context)
1140 (if (and (memq (ly:grob-property grob 'interfaces)
1141 note-head-interface)
1142 (eq? (ly:grob-property grob 'staff-position) 0))
1143 (set! (ly:grob-property grob 'transparent) #t)))
1147 @node Scheme procedures as properties
1148 @section Scheme procedures as properties
1150 Properties (like thickness, direction, etc.) can be set at fixed values
1151 with \override, e.g.
1154 \override Stem #'thickness = #2.0
1157 Properties can also be set to a Scheme procedure,
1159 @lilypond[fragment,verbatim,quote,relative=2]
1160 \override Stem #'thickness = #(lambda (grob)
1161 (if (= UP (ly:grob-property grob 'direction))
1168 In this case, the procedure is executed as soon as the value of the
1169 property is requested during the formatting process.
1171 Most of the typesetting engine is driven by such callbacks.
1172 Properties that typically use callbacks include
1176 The printing routine, that constructs a drawing for the symbol
1178 The routine that sets the horizontal position
1180 The routine that computes the width of an object
1183 The procedure always takes a single argument, being the grob.
1185 If routines with multiple arguments must be called, the current grob
1186 can be inserted with a grob closure. Here is a setting from
1187 @code{AccidentalSuggestion},
1191 ,(ly:make-simple-closure
1193 ,(ly:make-simple-closure
1194 (list ly:self-alignment-interface::centered-on-x-parent))
1195 ,(ly:make-simple-closure
1196 (list ly:self-alignment-interface::x-aligned-on-self)))))
1200 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1201 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1202 with the grob as argument. The results are added with the @code{+}
1203 function. To ensure that this addition is properly executed, the whole
1204 thing is enclosed in @code{ly:make-simple-closure}.
1206 In fact, using a single procedure as property value is equivalent to
1209 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1213 The inner @code{ly:make-simple-closure} supplies the grob as argument
1214 to @var{proc}, the outer ensures that result of the function is
1215 returned, rather than the @code{simple-closure} object.