1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @node Interfaces for programmers
11 @chapter Interfaces for programmers
13 Advanced tweaks may be performed by using Scheme. If you are
14 not familiar with Scheme, you may wish to read our
15 @ref{Scheme tutorial}.
19 * Programmer interfaces::
20 * Building complicated functions::
21 * Markup programmer interface::
22 * Contexts for programmers::
23 * Scheme procedures as properties::
28 @section Music functions
30 This section discusses how to create music functions within LilyPond.
33 * Overview of music functions::
34 * Simple substitution functions::
35 * Paired substitution functions::
36 * Mathematics in functions::
38 * Functions without arguments::
39 * Overview of available music functions::
42 @node Overview of music functions
43 @subsection Overview of music functions
45 Making a function which substitutes a variable into LilyPond
46 code is easy. The general form of these functions is
50 #(define-music-function (parser location @var{var1} @var{var2}... )
51 (@var{var1-type?} @var{var2-type?}...)
60 @multitable @columnfractions .33 .66
61 @item @var{argi} @tab @var{i}th variable
62 @item @var{argi-type?} @tab type of variable
63 @item @var{...music...} @tab normal LilyPond input, using
64 variables as @code{#$var1}.
67 There following input types may be used as variables
68 in a music function. This list is not exhaustive; see
69 other documentation specifically about Scheme for more
72 @multitable @columnfractions .33 .66
73 @headitem Input type @tab @var{argi-type?} notation
74 @item Integer @tab @code{integer?}
75 @item Float (decimal number) @tab @code{number?}
76 @item Text string @tab @code{string?}
77 @item Markup @tab @code{markup?}
78 @item Music expression @tab @code{ly:music?}
79 @item A pair of variables @tab @code{pair?}
82 The @code{parser} and @code{location} argument are mandatory,
83 and are used in some advanced situations. The @code{parser}
84 argument is used to access to the value of another LilyPond
85 variable. The @code{location} argument
86 is used to set the ``origin'' of the music expression that is built
87 by the music function, so that in case of a syntax error LilyPond
88 can tell the user an appropriate place to look in the input file.
91 @node Simple substitution functions
92 @subsection Simple substitution functions
94 Here is a simple example,
96 @lilypond[quote,verbatim,ragged-right]
97 padText = #(define-music-function (parser location padding) (number?)
99 \once \override TextScript #'padding = #$padding
107 c4^"piu mosso" fis a g
111 Music expressions may be substituted as well,
113 @lilypond[quote,verbatim,ragged-right]
114 custosNote = #(define-music-function (parser location note)
117 \once \override Voice.NoteHead #'stencil =
118 #ly:text-interface::print
119 \once \override Voice.NoteHead #'text =
120 \markup \musicglyph #"custodes.mensural.u0"
121 \once \override Voice.Stem #'stencil = ##f
125 { c' d' e' f' \custosNote g' }
128 Multiple variables may be used,
130 @lilypond[quote,verbatim,ragged-right]
131 tempoMark = #(define-music-function (parser location padding marktext)
134 \once \override Score . RehearsalMark #'padding = $padding
135 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
136 \mark \markup { \bold $marktext }
141 \tempoMark #3.0 #"Allegro"
147 @node Paired substitution functions
148 @subsection Paired substitution functions
150 Some @code{\override} commands require a pair of numbers
151 (called a @code{cons cell} in Scheme). To pass these numbers
152 into a function, either use a @code{pair?} variable, or
153 insert the @code{cons} into the music function.
158 #(define-music-function (parser location beg-end)
161 \once \override Beam #'positions = #$beg-end
165 \manualBeam #'(3 . 6) c8 d e f
173 @lilypond[quote,verbatim,ragged-right]
175 #(define-music-function (parser location beg end)
178 \once \override Beam #'positions = #(cons $beg $end)
182 \manualBeam #3 #6 c8 d e f
187 @node Mathematics in functions
188 @subsection Mathematics in functions
190 Music functions can involve Scheme programming in
191 addition to simple substitution,
193 @lilypond[quote,verbatim,ragged-right]
194 AltOn = #(define-music-function (parser location mag) (number?)
195 #{ \override Stem #'length = #$(* 7.0 mag)
196 \override NoteHead #'font-size =
197 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
200 \revert Stem #'length
201 \revert NoteHead #'font-size
204 { c'2 \AltOn #0.5 c'4 c'
205 \AltOn #1.5 c' c' \AltOff c'2 }
209 This example may be rewritten to pass in music expressions,
211 @lilypond[quote,verbatim,ragged-right]
212 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
213 #{ \override Stem #'length = #$(* 7.0 mag)
214 \override NoteHead #'font-size =
215 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
217 \revert Stem #'length
218 \revert NoteHead #'font-size #})
220 { c'2 \withAlt #0.5 {c'4 c'}
221 \withAlt #1.5 {c' c'} c'2 }
225 @subsection Void functions
227 A music function must return a music expression, but sometimes we
228 may want to have a function which does not involve music (such as
229 turning off Point and Click). To do this, we return a @code{void}
233 that is returned is the @code{(make-music ...)}. With the
234 @code{'void} property set to @code{#t}, the parser is told to
235 actually disregard this returned music
236 expression. Thus the important part of the void music function is the
237 processing done by the function, not the music expression that is
242 #(define-music-function (parser location) ()
243 (ly:set-option 'point-and-click #f)
244 (make-music 'SequentialMusic 'void #t))
246 \noPointAndClick % disable point and click
250 @node Functions without arguments
251 @subsection Functions without arguments
253 In most cases a function without arguments should be written
257 dolce = \markup@{ \italic \bold dolce @}
260 However, in rare cases it may be useful to create a music function
265 #(define-music-function (parser location) ()
266 (if (eq? #t (ly:get-option display-bar-numbers))
267 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
271 To actually display bar numbers where this function is called,
275 lilypond -d display-bar-numbers FILENAME.ly
279 @node Overview of available music functions
280 @subsection Overview of available music functions
282 @c fixme ; this should be move somewhere else?
283 The following commands are music functions
285 @include identifiers.tely
289 @node Programmer interfaces
290 @section Programmer interfaces
292 This section contains information about mixing LilyPond
296 * Input variables and Scheme::
297 * Internal music representation::
301 @node Input variables and Scheme
302 @subsection Input variables and Scheme
304 The input format supports the notion of variables: in the following
305 example, a music expression is assigned to a variable with the name
309 traLaLa = @{ c'4 d'4 @}
314 There is also a form of scoping: in the following example, the
315 @code{\layout} block also contains a @code{traLaLa} variable, which is
316 independent of the outer @code{\traLaLa}.
318 traLaLa = @{ c'4 d'4 @}
319 \layout @{ traLaLa = 1.0 @}
322 In effect, each input file is a scope, and all @code{\header},
323 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
326 Both variables and scoping are implemented in the GUILE module system.
327 An anonymous Scheme module is attached to each scope. An assignment of
330 traLaLa = @{ c'4 d'4 @}
334 is internally converted to a Scheme definition
336 (define traLaLa @var{Scheme value of ``@code{... }''})
339 This means that input variables and Scheme variables may be freely
340 mixed. In the following example, a music fragment is stored in the
341 variable @code{traLaLa}, and duplicated using Scheme. The result is
342 imported in a @code{\score} block by means of a second variable
346 traLaLa = { c'4 d'4 }
348 %% dummy action to deal with parser lookahead
349 #(display "this needs to be here, sorry!")
351 #(define newLa (map ly:music-deep-copy
352 (list traLaLa traLaLa)))
354 (make-sequential-music newLa))
359 Due to parser lookahead
361 In this example, the assignment happens after parser has verified that
362 nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
363 the dummy statement in the above example, the @code{newLa} definition
364 is executed before @code{traLaLa} is defined, leading to a syntax
367 The above example shows how to `export' music expressions from the
368 input to the Scheme interpreter. The opposite is also possible. By
369 wrapping a Scheme value in the function @code{ly:export}, a Scheme
370 value is interpreted as if it were entered in LilyPond syntax.
371 Instead of defining @code{\twice}, the example above could also have
375 @{ #(ly:export (make-sequential-music (list newLa))) @}
378 Scheme code is evaluated as soon as the parser encounters it. To
379 define some Scheme code in a macro (to be called later), use
380 @ref{Void functions} or
384 (ly:set-option 'point-and-click #f))
394 Mixing Scheme and LilyPond identifiers is not possible with the
395 @code{--safe} option.
398 @node Internal music representation
399 @subsection Internal music representation
401 When a music expression is parsed, it is converted into a set of
402 Scheme music objects. The defining property of a music object is that
403 it takes up time. Time is a rational number that measures the length
404 of a piece of music in whole notes.
406 A music object has three kinds of types:
409 music name: Each music expression has a name. For example, a note
410 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
411 a @internalsref{SimultaneousMusic}. A list of all expressions
412 available is in the Program reference manual, under
413 @internalsref{Music expressions}.
416 `type' or interface: Each music name has several `types' or
417 interfaces, for example, a note is an @code{event}, but it is also a
418 @code{note-event}, a @code{rhythmic-event}, and a
419 @code{melodic-event}. All classes of music are listed in the
420 Program reference, under
421 @internalsref{Music classes}.
424 C++ object: Each music object is represented by an object of the C++
428 The actual information of a music expression is stored in properties.
429 For example, a @internalsref{NoteEvent} has @code{pitch} and
430 @code{duration} properties that store the pitch and duration of that
431 note. A list of all properties available is in the internals manual,
432 under @internalsref{Music properties}.
434 A compound music expression is a music object that contains other
435 music objects in its properties. A list of objects can be stored in
436 the @code{elements} property of a music object, or a single `child'
437 music object in the @code{element} object. For example,
438 @internalsref{SequentialMusic} has its children in @code{elements},
439 and @internalsref{GraceMusic} has its single argument in
440 @code{element}. The body of a repeat is stored in the @code{element}
441 property of @internalsref{RepeatedMusic}, and the alternatives in
446 @node Building complicated functions
447 @section Building complicated functions
449 This section explains how to gather the information necessary
450 to create complicated music functions.
453 * Displaying music expressions::
455 * Doubling a note with slurs (example)::
456 * Adding articulation to notes (example)::
460 @node Displaying music expressions
461 @subsection Displaying music expressions
463 @cindex internal storage
464 @funindex \displayMusic
465 @funindex \displayLilyMusic
467 When writing a music function it is often instructive to inspect how
468 a music expression is stored internally. This can be done with the
469 music function @code{\displayMusic}
473 \displayMusic @{ c'4\f @}
490 (ly:make-duration 2 0 1 1)
492 (ly:make-pitch 0 0 0))
494 'AbsoluteDynamicEvent
499 By default, LilyPond will print these messages to the console along
500 with all the other messages. To split up these messages and save
501 the results of @code{\display@{STUFF@}}, redirect the output to
505 lilypond file.ly >display.txt
508 With a bit of reformatting, the above information is
512 (make-music 'SequentialMusic
513 'elements (list (make-music 'EventChord
514 'elements (list (make-music 'NoteEvent
515 'duration (ly:make-duration 2 0 1 1)
516 'pitch (ly:make-pitch 0 0 0))
517 (make-music 'AbsoluteDynamicEvent
521 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
522 and its inner expressions are stored as a list in its @code{'elements}
523 property. A note is represented as an @code{EventChord} expression,
524 containing a @code{NoteEvent} object (storing the duration and
525 pitch properties) and any extra information (in this case, an
526 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
529 @node Music properties
530 @subsection Music properties
532 The @code{NoteEvent} object is the first object of the
533 @code{'elements} property of @code{someNote}.
537 \displayMusic \someNote
545 (ly:make-duration 2 0 1 1)
547 (ly:make-pitch 0 0 0))))
550 The @code{display-scheme-music} function is the function used by
551 @code{\displayMusic} to display the Scheme representation of a music
555 #(display-scheme-music (first (ly:music-property someNote 'elements)))
560 (ly:make-duration 2 0 1 1)
562 (ly:make-pitch 0 0 0))
565 Then the note pitch is accessed through the @code{'pitch} property
566 of the @code{NoteEvent} object,
569 #(display-scheme-music
570 (ly:music-property (first (ly:music-property someNote 'elements))
573 (ly:make-pitch 0 0 0)
576 The note pitch can be changed by setting this 'pitch property,
579 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
581 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
582 \displayLilyMusic \someNote
588 @node Doubling a note with slurs (example)
589 @subsection Doubling a note with slurs (example)
591 Suppose we want to create a function which translates
592 input like ``@code{a}'' into ``@code{a( a)}''. We begin
593 by examining the internal representation of the music
594 we want to end up with.
597 \displayMusic@{ a'( a') @}
608 (ly:make-duration 2 0 1 1)
610 (ly:make-pitch 0 5 0))
621 (ly:make-duration 2 0 1 1)
623 (ly:make-pitch 0 5 0))
630 The bad news is that the @code{SlurEvent} expressions
631 must be added ``inside'' the note (or more precisely,
632 inside the @code{EventChord} expression).
634 Now we examine the input,
646 (ly:make-duration 2 0 1 1)
648 (ly:make-pitch 0 5 0))))))
651 So in our function, we need to clone this expression (so that we
652 have two notes to build the sequence), add @code{SlurEvents} to the
653 @code{'elements} property of each one, and finally make a
654 @code{SequentialMusic} with the two @code{EventChords}.
657 doubleSlur = #(define-music-function (parser location note) (ly:music?)
658 "Return: @{ note ( note ) @}.
659 `note' is supposed to be an EventChord."
660 (let ((note2 (ly:music-deep-copy note)))
661 (set! (ly:music-property note 'elements)
662 (cons (make-music 'SlurEvent 'span-direction -1)
663 (ly:music-property note 'elements)))
664 (set! (ly:music-property note2 'elements)
665 (cons (make-music 'SlurEvent 'span-direction 1)
666 (ly:music-property note2 'elements)))
667 (make-music 'SequentialMusic 'elements (list note note2))))
671 @node Adding articulation to notes (example)
672 @subsection Adding articulation to notes (example)
674 The easy way to add articulation to notes is to merge two music
675 expressions into one context, as explained in
676 @ref{Creating contexts}. However, suppose that we want to write
677 a music function which does this.
679 A @code{$variable} inside the @code{#@{...#@}} notation is like
680 using a regular @code{\variable} in classical LilyPond
681 notation. We know that
688 will not work in LilyPond. We could avoid this problem by attaching
689 the articulation to a fake note,
692 @{ << \music s1*0-.-> @}
696 but for the sake of this example, we will learn how to do this in
697 Scheme. We begin by examining our input and desired output,
709 (ly:make-duration 2 0 1 1)
711 (ly:make-pitch -1 0 0))))
722 (ly:make-duration 2 0 1 1)
724 (ly:make-pitch -1 0 0))
731 We see that a note (@code{c4}) is represented as an @code{EventChord}
732 expression, with a @code{NoteEvent} expression in its elements list. To
733 add a marcato articulation, an @code{ArticulationEvent} expression must
734 be added to the elements property of the @code{EventChord}
737 To build this function, we begin with
740 (define (add-marcato event-chord)
741 "Add a marcato ArticulationEvent to the elements of `event-chord',
742 which is supposed to be an EventChord expression."
743 (let ((result-event-chord (ly:music-deep-copy event-chord)))
744 (set! (ly:music-property result-event-chord 'elements)
745 (cons (make-music 'ArticulationEvent
746 'articulation-type "marcato")
747 (ly:music-property result-event-chord 'elements)))
751 The first line is the way to define a function in Scheme: the function
752 name is @code{add-marcato}, and has one variable called
753 @code{event-chord}. In Scheme, the type of variable is often clear
754 from its name. (this is good practice in other programming languages,
762 is a description of what the function does. This is not strictly
763 necessary, but just like clear variable names, it is good practice.
766 (let ((result-event-chord (ly:music-deep-copy event-chord)))
769 `@code{let}' is used to declare local variables. Here we use one local
770 variable, named `@code{result-event-chord}', to which we give the value
771 @code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
772 a function specific to LilyPond, like all functions prefixed by
773 `@code{ly:}'. It is use to make a copy of a music
774 expression. Here we copy `@code{event-chord} (the parameter of the
775 function). Recall that our purpose is to add a marcato to an
776 @code{EventChord} expression. It is better to not modify the
777 @code{EventChord} which was given as an argument, because it may be
780 Now we have a @code{result-event-chord}, which is a
781 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
782 add the marcato to its elements list property.
785 (set! place new-value)
788 Here, what we want to set (the "place") is the "elements" property of
789 @code{result-event-chord} expression
792 (ly:music-property result-event-chord 'elements)
795 @code{ly:music-property} is the function used to access music properties
796 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
797 see in the @code{\displayMusic} output above). The new value is the
798 former elements property, with an extra item: the
799 @code{MarcatoEvent} expression, which we copy from the
800 @code{\displayMusic} output,
803 (cons (make-music 'ArticulationEvent
804 'articulation-type "marcato")
805 (ly:music-property result-event-chord 'elements))
808 `@code{cons}' is used to add an element to a list without modifying the
809 original list. This is what we
810 want: the same list as before, plus the new @code{ArticulationEvent}
811 expression. The order inside the elements property is not important here.
813 Finally, once we have added the @code{MarcatoEvent} to its elements
814 property, we can return @code{result-event-chord}, hence the last line of
817 Now we transform the @code{add-marcato} function into a music
821 addMarcato = #(define-music-function (parser location event-chord)
823 "Add a marcato ArticulationEvent to the elements of `event-chord',
824 which is supposed to be an EventChord expression."
825 (let ((result-event-chord (ly:music-deep-copy event-chord)))
826 (set! (ly:music-property result-event-chord 'elements)
827 (cons (make-music 'ArticulationEvent
828 'articulation-type "marcato")
829 (ly:music-property result-event-chord 'elements)))
833 We may verify that this music function works correctly,
836 \displayMusic \addMarcato c4
840 @node Markup programmer interface
841 @section Markup programmer interface
843 Markups are implemented as special Scheme functions which produce a
844 Stencil object given a number of arguments.
847 * Markup construction in Scheme::
848 * How markups work internally::
849 * New markup command definition::
853 @node Markup construction in Scheme
854 @subsection Markup construction in Scheme
856 @cindex defining markup commands
858 The @code{markup} macro builds markup expressions in Scheme while
859 providing a LilyPond-like syntax. For example,
861 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
862 #:bigger #:line ("foo" "bar" "baz")))
868 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
869 \bigger \line @{ foo bar baz @} @}
873 This example demonstrates the main translation rules between regular
874 LilyPond markup syntax and Scheme markup syntax.
877 @multitable @columnfractions .3 .3
878 @item @b{LilyPond} @tab @b{Scheme}
879 @item @code{\markup markup1} @tab @code{(markup markup1)}
880 @item @code{\markup @{ markup1 markup2 ... @}} @tab
881 @code{(markup markup1 markup2 ... )}
882 @item @code{\command} @tab @code{#:command}
883 @item @code{\variable} @tab @code{variable}
884 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
885 @item @code{string} @tab @code{"string"}
886 @item @code{#scheme-arg} @tab @code{scheme-arg}
890 The whole Scheme language is accessible inside the
891 @code{markup} macro. For example, You may use function calls inside
892 @code{markup} in order to manipulate character strings. This is
893 useful when defining new markup commands (see
894 @ref{New markup command definition}).
899 The markup-list argument of commands such as @code{#:line},
900 @code{#:center}, and @code{#:column} cannot be a variable or
901 the result of a function call.
904 (markup #:line (function-that-returns-markups))
908 is invalid. One should use the @code{make-line-markup},
909 @code{make-center-markup}, or @code{make-column-markup} functions
913 (markup (make-line-markup (function-that-returns-markups)))
917 @node How markups work internally
918 @subsection How markups work internally
923 \raise #0.5 "text example"
927 @code{\raise} is actually represented by the @code{raise-markup}
928 function. The markup expression is stored as
931 (list raise-markup 0.5 (list simple-markup "text example"))
934 When the markup is converted to printable objects (Stencils), the
935 @code{raise-markup} function is called as
940 @var{list of property alists}
942 @var{the "text example" markup})
945 The @code{raise-markup} function first creates the stencil for the
946 @code{text example} string, and then it raises that Stencil by 0.5
947 staff space. This is a rather simple example; more complex examples
949 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
952 @node New markup command definition
953 @subsection New markup command definition
955 New markup commands can be defined
956 with the @code{define-markup-command} Scheme macro.
959 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
960 (@var{arg1-type?} @var{arg2-type?} ...)
968 @var{i}th command argument
970 a type predicate for the i@var{th} argument
972 the `layout' definition
974 a list of alists, containing all active properties.
977 As a simple example, we show how to add a @code{\smallcaps} command,
978 which selects a small caps font. Normally we could select the
982 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
986 This selects the caps font by setting the @code{font-shape} property to
987 @code{#'caps} for interpreting @code{Text-in-caps}.
989 To make the above available as @code{\smallcaps} command, we must
990 define a function using @code{define-markup-command}. The command should
991 take a single argument of type @code{markup}. Therefore the start of the
992 definition should read
995 (define-markup-command (smallcaps layout props argument) (markup?)
1000 What follows is the content of the command: we should interpret
1001 the @code{argument} as a markup, i.e.,
1004 (interpret-markup layout @dots{} argument)
1008 This interpretation should add @code{'(font-shape . caps)} to the active
1009 properties, so we substitute the following for the @dots{} in the
1013 (cons (list '(font-shape . caps) ) props)
1017 The variable @code{props} is a list of alists, and we prepend to it by
1018 cons'ing a list with the extra setting.
1021 Suppose that we are typesetting a recitative in an opera and
1022 we would like to define a command that will show character names in a
1023 custom manner. Names should be printed with small caps and moved a
1024 bit to the left and top. We will define a @code{\character} command
1025 which takes into account the necessary translation and uses the newly
1026 defined @code{\smallcaps} command:
1029 #(define-markup-command (character layout props name) (string?)
1030 "Print the character name in small caps, translated to the left and
1031 top. Syntax: \\character #\"name\""
1032 (interpret-markup layout props
1033 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1036 There is one complication that needs explanation: texts above and below
1037 the staff are moved vertically to be at a certain distance (the
1038 @code{padding} property) from the staff and the notes. To make sure
1039 that this mechanism does not annihilate the vertical effect of our
1040 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
1041 translated text. Now the @code{#:hspace 0} will be put above the notes,
1043 @code{name} is moved in relation to that empty string. The net effect is
1044 that the text is moved to the upper left.
1046 The final result is as follows:
1050 c''^\markup \character #"Cleopatra"
1051 e'^\markup \character #"Giulio Cesare"
1055 @lilypond[quote,ragged-right]
1056 #(define-markup-command (smallcaps layout props str) (string?)
1057 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
1058 (interpret-markup layout props
1061 (if (= (string-length s) 0)
1063 (markup #:large (string-upcase (substring s 0 1))
1064 #:translate (cons -0.6 0)
1065 #:tiny (string-upcase (substring s 1)))))
1066 (string-split str #\Space)))))
1068 #(define-markup-command (character layout props name) (string?)
1069 "Print the character name in small caps, translated to the left and
1070 top. Syntax: \\character #\"name\""
1071 (interpret-markup layout props
1072 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1075 c''^\markup \character #"Cleopatra" c'' c'' c''
1076 e'^\markup \character #"Giulio Cesare" e' e' e'
1080 We have used the @code{caps} font shape, but suppose that our font
1081 does not have a small-caps variant. In that case we have to fake
1082 the small caps font by setting a string in upcase with the first
1083 letter a little larger:
1086 #(define-markup-command (smallcaps layout props str) (string?)
1087 "Print the string argument in small caps."
1088 (interpret-markup layout props
1091 (if (= (string-length s) 0)
1093 (markup #:large (string-upcase (substring s 0 1))
1094 #:translate (cons -0.6 0)
1095 #:tiny (string-upcase (substring s 1)))))
1096 (string-split str #\Space)))))
1099 The @code{smallcaps} command first splits its string argument into
1100 tokens separated by spaces (@code{(string-split str #\Space)}); for
1101 each token, a markup is built with the first letter made large and
1102 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1103 second markup built with the following letters made tiny and upcased
1104 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1105 introduces a space between markups on a line, the second markup is
1106 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1107 the markups built for each token are put in a line by
1108 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1109 to the @code{interpret-markup} function, with the @code{layout} and
1110 @code{props} arguments.
1112 Note: there is now an internal command @code{\smallCaps} which can
1113 be used to set text in small caps. See
1114 @ref{Overview of text markup commands} for details.
1118 @node Contexts for programmers
1119 @section Contexts for programmers
1122 * Context evaluation::
1123 * Running a function on all layout objects::
1126 @node Context evaluation
1127 @subsection Context evaluation
1129 @cindex calling code during interpreting
1130 @funindex \applyContext
1132 Contexts can be modified during interpretation with Scheme code. The
1135 \applyContext @var{function}
1138 @var{function} should be a Scheme function taking a single argument,
1139 being the context to apply it to. The following code will print the
1140 current bar number on the standard output during the compile:
1145 (format #t "\nWe were called in barnumber ~a.\n"
1146 (ly:context-property x 'currentBarNumber)))
1151 @node Running a function on all layout objects
1152 @subsection Running a function on all layout objects
1155 @cindex calling code on layout objects
1156 @funindex \applyOutput
1159 The most versatile way of tuning an object is @code{\applyOutput}. Its
1162 \applyOutput @var{context} @var{proc}
1166 where @var{proc} is a Scheme function, taking three arguments.
1168 When interpreted, the function @var{proc} is called for every layout
1169 object found in the context @var{context}, with the following
1172 @item the layout object itself,
1173 @item the context where the layout object was created, and
1174 @item the context where @code{\applyOutput} is processed.
1178 In addition, the cause of the layout object, i.e., the music
1179 expression or object that was responsible for creating it, is in the
1180 object property @code{cause}. For example, for a note head, this is a
1181 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1182 this is a @internalsref{NoteHead} object.
1184 Here is a function to use for @code{\applyOutput}; it blanks
1185 note-heads on the center-line:
1188 (define (blanker grob grob-origin context)
1189 (if (and (memq (ly:grob-property grob 'interfaces)
1190 note-head-interface)
1191 (eq? (ly:grob-property grob 'staff-position) 0))
1192 (set! (ly:grob-property grob 'transparent) #t)))
1196 @node Scheme procedures as properties
1197 @section Scheme procedures as properties
1199 Properties (like thickness, direction, etc.) can be set at fixed values
1200 with \override, e.g.
1203 \override Stem #'thickness = #2.0
1206 Properties can also be set to a Scheme procedure,
1208 @lilypond[fragment,verbatim,quote,relative=2]
1209 \override Stem #'thickness = #(lambda (grob)
1210 (if (= UP (ly:grob-property grob 'direction))
1217 In this case, the procedure is executed as soon as the value of the
1218 property is requested during the formatting process.
1220 Most of the typesetting engine is driven by such callbacks.
1221 Properties that typically use callbacks include
1225 The printing routine, that constructs a drawing for the symbol
1227 The routine that sets the horizontal position
1229 The routine that computes the width of an object
1232 The procedure always takes a single argument, being the grob.
1234 If routines with multiple arguments must be called, the current grob
1235 can be inserted with a grob closure. Here is a setting from
1236 @code{AccidentalSuggestion},
1240 ,(ly:make-simple-closure
1242 ,(ly:make-simple-closure
1243 (list ly:self-alignment-interface::centered-on-x-parent))
1244 ,(ly:make-simple-closure
1245 (list ly:self-alignment-interface::x-aligned-on-self)))))
1249 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1250 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1251 with the grob as argument. The results are added with the @code{+}
1252 function. To ensure that this addition is properly executed, the whole
1253 thing is enclosed in @code{ly:make-simple-closure}.
1255 In fact, using a single procedure as property value is equivalent to
1258 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1262 The inner @code{ly:make-simple-closure} supplies the grob as argument
1263 to @var{proc}, the outer ensures that result of the function is
1264 returned, rather than the @code{simple-closure} object.