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.
12 @node Interfaces for programmers
13 @chapter Interfaces for programmers
15 Advanced tweaks may be performed by using Scheme. If you are
16 not familiar with Scheme, you may wish to read our
17 @rlearning{Scheme tutorial}.
21 * Programmer interfaces::
22 * Building complicated functions::
23 * Markup programmer interface::
24 * Contexts for programmers::
25 * Scheme procedures as properties::
30 @section Music functions
32 This section discusses how to create music functions within LilyPond.
35 * Overview of music functions::
36 * Simple substitution functions::
37 * Paired substitution functions::
38 * Mathematics in functions::
40 * Functions without arguments::
41 * Overview of available music functions::
44 @node Overview of music functions
45 @subsection Overview of music functions
47 Making a function which substitutes a variable into LilyPond
48 code is easy. The general form of these functions is
52 #(define-music-function (parser location @var{var1} @var{var2}... )
53 (@var{var1-type?} @var{var2-type?}...)
62 @multitable @columnfractions .33 .66
63 @item @var{argi} @tab @var{i}th variable
64 @item @var{argi-type?} @tab type of variable
65 @item @var{...music...} @tab normal LilyPond input, using
66 variables as @code{#$var1}.
69 There following input types may be used as variables
70 in a music function. This list is not exhaustive; see
71 other documentation specifically about Scheme for more
74 @multitable @columnfractions .33 .66
75 @headitem Input type @tab @var{argi-type?} notation
76 @item Integer @tab @code{integer?}
77 @item Float (decimal number) @tab @code{number?}
78 @item Text string @tab @code{string?}
79 @item Markup @tab @code{markup?}
80 @item Music expression @tab @code{ly:music?}
81 @item A pair of variables @tab @code{pair?}
84 The @code{parser} and @code{location} argument are mandatory,
85 and are used in some advanced situations. The @code{parser}
86 argument is used to access to the value of another LilyPond
87 variable. The @code{location} argument
88 is used to set the @q{origin} of the music expression that is built
89 by the music function, so that in case of a syntax error LilyPond
90 can tell the user an appropriate place to look in the input file.
93 @node Simple substitution functions
94 @subsection Simple substitution functions
96 Here is a simple example,
98 @lilypond[quote,verbatim,ragged-right]
99 padText = #(define-music-function (parser location padding) (number?)
101 \once \override TextScript #'padding = #$padding
109 c4^"piu mosso" fis a g
113 Music expressions may be substituted as well,
115 @lilypond[quote,verbatim,ragged-right]
116 custosNote = #(define-music-function (parser location note)
119 \once \override Voice.NoteHead #'stencil =
120 #ly:text-interface::print
121 \once \override Voice.NoteHead #'text =
122 \markup \musicglyph #"custodes.mensural.u0"
123 \once \override Voice.Stem #'stencil = ##f
127 { c' d' e' f' \custosNote g' }
130 Multiple variables may be used,
132 @lilypond[quote,verbatim,ragged-right]
133 tempoMark = #(define-music-function (parser location padding marktext)
136 \once \override Score . RehearsalMark #'padding = $padding
137 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
138 \mark \markup { \bold $marktext }
143 \tempoMark #3.0 #"Allegro"
149 @node Paired substitution functions
150 @subsection Paired substitution functions
152 Some @code{\override} commands require a pair of numbers
153 (called a @code{cons cell} in Scheme). To pass these numbers
154 into a function, either use a @code{pair?} variable, or
155 insert the @code{cons} into the music function.
160 #(define-music-function (parser location beg-end)
163 \once \override Beam #'positions = #$beg-end
167 \manualBeam #'(3 . 6) c8 d e f
175 @lilypond[quote,verbatim,ragged-right]
177 #(define-music-function (parser location beg end)
180 \once \override Beam #'positions = #(cons $beg $end)
184 \manualBeam #3 #6 c8 d e f
189 @node Mathematics in functions
190 @subsection Mathematics in functions
192 Music functions can involve Scheme programming in
193 addition to simple substitution,
195 @lilypond[quote,verbatim,ragged-right]
196 AltOn = #(define-music-function (parser location mag) (number?)
197 #{ \override Stem #'length = #$(* 7.0 mag)
198 \override NoteHead #'font-size =
199 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
202 \revert Stem #'length
203 \revert NoteHead #'font-size
206 { c'2 \AltOn #0.5 c'4 c'
207 \AltOn #1.5 c' c' \AltOff c'2 }
211 This example may be rewritten to pass in music expressions,
213 @lilypond[quote,verbatim,ragged-right]
214 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
215 #{ \override Stem #'length = #$(* 7.0 mag)
216 \override NoteHead #'font-size =
217 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
219 \revert Stem #'length
220 \revert NoteHead #'font-size #})
222 { c'2 \withAlt #0.5 {c'4 c'}
223 \withAlt #1.5 {c' c'} c'2 }
227 @subsection Void functions
229 A music function must return a music expression, but sometimes we
230 may want to have a function which does not involve music (such as
231 turning off Point and Click). To do this, we return a @code{void}
235 that is returned is the @code{(make-music ...)}. With the
236 @code{'void} property set to @code{#t}, the parser is told to
237 actually disregard this returned music
238 expression. Thus the important part of the void music function is the
239 processing done by the function, not the music expression that is
244 #(define-music-function (parser location) ()
245 (ly:set-option 'point-and-click #f)
246 (make-music 'SequentialMusic 'void #t))
248 \noPointAndClick % disable point and click
252 @node Functions without arguments
253 @subsection Functions without arguments
255 In most cases a function without arguments should be written
259 dolce = \markup@{ \italic \bold dolce @}
262 However, in rare cases it may be useful to create a music function
267 #(define-music-function (parser location) ()
268 (if (eq? #t (ly:get-option 'display-bar-numbers))
269 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
273 To actually display bar numbers where this function is called,
274 invoke @command{lilypond} with
277 lilypond -d display-bar-numbers FILENAME.ly
281 @node Overview of available music functions
282 @subsection Overview of available music functions
284 @c fixme ; this should be move somewhere else?
285 The following commands are music functions
287 @include identifiers.tely
291 @node Programmer interfaces
292 @section Programmer interfaces
294 This section contains information about mixing LilyPond
298 * Input variables and Scheme::
299 * Internal music representation::
303 @node Input variables and Scheme
304 @subsection Input variables and Scheme
306 The input format supports the notion of variables: in the following
307 example, a music expression is assigned to a variable with the name
311 traLaLa = @{ c'4 d'4 @}
316 There is also a form of scoping: in the following example, the
317 @code{\layout} block also contains a @code{traLaLa} variable, which is
318 independent of the outer @code{\traLaLa}.
320 traLaLa = @{ c'4 d'4 @}
321 \layout @{ traLaLa = 1.0 @}
324 In effect, each input file is a scope, and all @code{\header},
325 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
328 Both variables and scoping are implemented in the GUILE module system.
329 An anonymous Scheme module is attached to each scope. An assignment of
332 traLaLa = @{ c'4 d'4 @}
336 is internally converted to a Scheme definition
338 (define traLaLa @var{Scheme value of `@code{... }'})
341 This means that input variables and Scheme variables may be freely
342 mixed. In the following example, a music fragment is stored in the
343 variable @code{traLaLa}, and duplicated using Scheme. The result is
344 imported in a @code{\score} block by means of a second variable
348 traLaLa = { c'4 d'4 }
350 %% dummy action to deal with parser lookahead
351 #(display "this needs to be here, sorry!")
353 #(define newLa (map ly:music-deep-copy
354 (list traLaLa traLaLa)))
356 (make-sequential-music newLa))
361 Due to parser lookahead
363 In this example, the assignment happens after parser has verified that
364 nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
365 the dummy statement in the above example, the @code{newLa} definition
366 is executed before @code{traLaLa} is defined, leading to a syntax
369 The above example shows how to @q{export} music expressions from the
370 input to the Scheme interpreter. The opposite is also possible. By
371 wrapping a Scheme value in the function @code{ly:export}, a Scheme
372 value is interpreted as if it were entered in LilyPond syntax.
373 Instead of defining @code{\twice}, the example above could also have
377 @{ #(ly:export (make-sequential-music (list newLa))) @}
380 Scheme code is evaluated as soon as the parser encounters it. To
381 define some Scheme code in a macro (to be called later), use
382 @ref{Void functions}, or
386 (ly:set-option 'point-and-click #f))
396 Mixing Scheme and LilyPond variables is not possible with the
397 @code{--safe} option.
400 @node Internal music representation
401 @subsection Internal music representation
403 When a music expression is parsed, it is converted into a set of
404 Scheme music objects. The defining property of a music object is that
405 it takes up time. Time is a rational number that measures the length
406 of a piece of music in whole notes.
408 A music object has three kinds of types:
411 music name: Each music expression has a name. For example, a note
412 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
413 a @internalsref{SimultaneousMusic}. A list of all expressions
414 available is in the Internals Reference manual, under
415 @internalsref{Music expressions}.
418 @q{type} or interface: Each music name has several @q{types} or
419 interfaces, for example, a note is an @code{event}, but it is also a
420 @code{note-event}, a @code{rhythmic-event}, and a
421 @code{melodic-event}. All classes of music are listed in the
422 Internals Reference, under
423 @internalsref{Music classes}.
426 C++ object: Each music object is represented by an object of the C++
430 The actual information of a music expression is stored in properties.
431 For example, a @internalsref{NoteEvent} has @code{pitch} and
432 @code{duration} properties that store the pitch and duration of that
433 note. A list of all properties available is in the internals manual,
434 under @internalsref{Music properties}.
436 A compound music expression is a music object that contains other
437 music objects in its properties. A list of objects can be stored in
438 the @code{elements} property of a music object, or a single @q{child}
439 music object in the @code{element} object. For example,
440 @internalsref{SequentialMusic} has its children in @code{elements},
441 and @internalsref{GraceMusic} has its single argument in
442 @code{element}. The body of a repeat is stored in the @code{element}
443 property of @internalsref{RepeatedMusic}, and the alternatives in
448 @node Building complicated functions
449 @section Building complicated functions
451 This section explains how to gather the information necessary
452 to create complicated music functions.
455 * Displaying music expressions::
457 * Doubling a note with slurs (example)::
458 * Adding articulation to notes (example)::
462 @node Displaying music expressions
463 @subsection Displaying music expressions
465 @cindex internal storage
466 @funindex \displayMusic
467 @funindex \displayLilyMusic
469 When writing a music function it is often instructive to inspect how
470 a music expression is stored internally. This can be done with the
471 music function @code{\displayMusic}
475 \displayMusic @{ c'4\f @}
492 (ly:make-duration 2 0 1 1)
494 (ly:make-pitch 0 0 0))
496 'AbsoluteDynamicEvent
501 By default, LilyPond will print these messages to the console along
502 with all the other messages. To split up these messages and save
503 the results of @code{\display@{STUFF@}}, redirect the output to
507 lilypond file.ly >display.txt
510 With a bit of reformatting, the above information is
514 (make-music 'SequentialMusic
515 'elements (list (make-music 'EventChord
516 'elements (list (make-music 'NoteEvent
517 'duration (ly:make-duration 2 0 1 1)
518 'pitch (ly:make-pitch 0 0 0))
519 (make-music 'AbsoluteDynamicEvent
523 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
524 and its inner expressions are stored as a list in its @code{'elements}
525 property. A note is represented as an @code{EventChord} expression,
526 containing a @code{NoteEvent} object (storing the duration and
527 pitch properties) and any extra information (in this case, an
528 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
531 @node Music properties
532 @subsection Music properties
534 The @code{NoteEvent} object is the first object of the
535 @code{'elements} property of @code{someNote}.
539 \displayMusic \someNote
547 (ly:make-duration 2 0 1 1)
549 (ly:make-pitch 0 0 0))))
552 The @code{display-scheme-music} function is the function used by
553 @code{\displayMusic} to display the Scheme representation of a music
557 #(display-scheme-music (first (ly:music-property someNote 'elements)))
562 (ly:make-duration 2 0 1 1)
564 (ly:make-pitch 0 0 0))
567 Then the note pitch is accessed through the @code{'pitch} property
568 of the @code{NoteEvent} object,
571 #(display-scheme-music
572 (ly:music-property (first (ly:music-property someNote 'elements))
575 (ly:make-pitch 0 0 0)
578 The note pitch can be changed by setting this 'pitch property,
581 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
583 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
584 \displayLilyMusic \someNote
590 @node Doubling a note with slurs (example)
591 @subsection Doubling a note with slurs (example)
593 Suppose we want to create a function which translates
594 input like @code{a} into @code{a( a)}. We begin
595 by examining the internal representation of the music
596 we want to end up with.
599 \displayMusic@{ a'( a') @}
610 (ly:make-duration 2 0 1 1)
612 (ly:make-pitch 0 5 0))
623 (ly:make-duration 2 0 1 1)
625 (ly:make-pitch 0 5 0))
632 The bad news is that the @code{SlurEvent} expressions
633 must be added @q{inside} the note (or more precisely,
634 inside the @code{EventChord} expression).
636 Now we examine the input,
648 (ly:make-duration 2 0 1 1)
650 (ly:make-pitch 0 5 0))))))
653 So in our function, we need to clone this expression (so that we
654 have two notes to build the sequence), add @code{SlurEvents} to the
655 @code{'elements} property of each one, and finally make a
656 @code{SequentialMusic} with the two @code{EventChords}.
659 doubleSlur = #(define-music-function (parser location note) (ly:music?)
660 "Return: @{ note ( note ) @}.
661 `note' is supposed to be an EventChord."
662 (let ((note2 (ly:music-deep-copy note)))
663 (set! (ly:music-property note 'elements)
664 (cons (make-music 'SlurEvent 'span-direction -1)
665 (ly:music-property note 'elements)))
666 (set! (ly:music-property note2 'elements)
667 (cons (make-music 'SlurEvent 'span-direction 1)
668 (ly:music-property note2 'elements)))
669 (make-music 'SequentialMusic 'elements (list note note2))))
673 @node Adding articulation to notes (example)
674 @subsection Adding articulation to notes (example)
676 The easy way to add articulation to notes is to merge two music
677 expressions into one context, as explained in
678 @ref{Creating contexts}. However, suppose that we want to write
679 a music function which does this.
681 A @code{$variable} inside the @code{#@{...#@}} notation is like
682 using a regular @code{\variable} in classical LilyPond
683 notation. We know that
690 will not work in LilyPond. We could avoid this problem by attaching
691 the articulation to a fake note,
694 @{ << \music s1*0-.-> @}
698 but for the sake of this example, we will learn how to do this in
699 Scheme. We begin by examining our input and desired output,
711 (ly:make-duration 2 0 1 1)
713 (ly:make-pitch -1 0 0))))
724 (ly:make-duration 2 0 1 1)
726 (ly:make-pitch -1 0 0))
733 We see that a note (@code{c4}) is represented as an @code{EventChord}
734 expression, with a @code{NoteEvent} expression in its elements list. To
735 add a marcato articulation, an @code{ArticulationEvent} expression must
736 be added to the elements property of the @code{EventChord}
739 To build this function, we begin with
742 (define (add-marcato event-chord)
743 "Add a marcato ArticulationEvent to the elements of `event-chord',
744 which is supposed to be an EventChord expression."
745 (let ((result-event-chord (ly:music-deep-copy event-chord)))
746 (set! (ly:music-property result-event-chord 'elements)
747 (cons (make-music 'ArticulationEvent
748 'articulation-type "marcato")
749 (ly:music-property result-event-chord 'elements)))
753 The first line is the way to define a function in Scheme: the function
754 name is @code{add-marcato}, and has one variable called
755 @code{event-chord}. In Scheme, the type of variable is often clear
756 from its name. (this is good practice in other programming languages,
764 is a description of what the function does. This is not strictly
765 necessary, but just like clear variable names, it is good practice.
768 (let ((result-event-chord (ly:music-deep-copy event-chord)))
771 @code{let} is used to declare local variables. Here we use one local
772 variable, named @code{result-event-chord}, to which we give the value
773 @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
774 a function specific to LilyPond, like all functions prefixed by
775 @code{ly:}. It is use to make a copy of a music
776 expression. Here we copy @code{event-chord} (the parameter of the
777 function). Recall that our purpose is to add a marcato to an
778 @code{EventChord} expression. It is better to not modify the
779 @code{EventChord} which was given as an argument, because it may be
782 Now we have a @code{result-event-chord}, which is a
783 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
784 add the marcato to its elements list property.
787 (set! place new-value)
790 Here, what we want to set (the @q{place}) is the @q{elements} property of
791 @code{result-event-chord} expression.
794 (ly:music-property result-event-chord 'elements)
797 @code{ly:music-property} is the function used to access music properties
798 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
799 see in the @code{\displayMusic} output above). The new value is the
800 former elements property, with an extra item: the
801 @code{ArticulationEvent} expression, which we copy from the
802 @code{\displayMusic} output,
805 (cons (make-music 'ArticulationEvent
806 'articulation-type "marcato")
807 (ly:music-property result-event-chord 'elements))
810 @code{cons} is used to add an element to a list without modifying the
811 original list. This is what we
812 want: the same list as before, plus the new @code{ArticulationEvent}
813 expression. The order inside the elements property is not important here.
815 Finally, once we have added the marcato articulation to its @code{elements}
816 property, we can return @code{result-event-chord}, hence the last line of
819 Now we transform the @code{add-marcato} function into a music
823 addMarcato = #(define-music-function (parser location event-chord)
825 "Add a marcato ArticulationEvent to the elements of `event-chord',
826 which is supposed to be an EventChord expression."
827 (let ((result-event-chord (ly:music-deep-copy event-chord)))
828 (set! (ly:music-property result-event-chord 'elements)
829 (cons (make-music 'ArticulationEvent
830 'articulation-type "marcato")
831 (ly:music-property result-event-chord 'elements)))
835 We may verify that this music function works correctly,
838 \displayMusic \addMarcato c4
842 @node Markup programmer interface
843 @section Markup programmer interface
845 Markups are implemented as special Scheme functions which produce a
846 Stencil object given a number of arguments.
849 * Markup construction in Scheme::
850 * How markups work internally::
851 * New markup command definition::
852 * New markup list command definition::
856 @node Markup construction in Scheme
857 @subsection Markup construction in Scheme
859 @cindex defining markup commands
861 The @code{markup} macro builds markup expressions in Scheme while
862 providing a LilyPond-like syntax. For example,
864 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
865 #:bigger #:line ("foo" "bar" "baz")))
871 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
872 \bigger \line @{ foo bar baz @} @}
876 This example demonstrates the main translation rules between regular
877 LilyPond markup syntax and Scheme markup syntax.
880 @multitable @columnfractions .3 .3
881 @item @b{LilyPond} @tab @b{Scheme}
882 @item @code{\markup markup1} @tab @code{(markup markup1)}
883 @item @code{\markup @{ markup1 markup2 ... @}} @tab
884 @code{(markup markup1 markup2 ... )}
885 @item @code{\command} @tab @code{#:command}
886 @item @code{\variable} @tab @code{variable}
887 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
888 @item @code{string} @tab @code{"string"}
889 @item @code{#scheme-arg} @tab @code{scheme-arg}
893 The whole Scheme language is accessible inside the
894 @code{markup} macro. For example, You may use function calls inside
895 @code{markup} in order to manipulate character strings. This is
896 useful when defining new markup commands (see
897 @ref{New markup command definition}).
902 The markup-list argument of commands such as @code{#:line},
903 @code{#:center}, and @code{#:column} cannot be a variable or
904 the result of a function call.
907 (markup #:line (function-that-returns-markups))
911 is invalid. One should use the @code{make-line-markup},
912 @code{make-center-markup}, or @code{make-column-markup} functions
916 (markup (make-line-markup (function-that-returns-markups)))
920 @node How markups work internally
921 @subsection How markups work internally
926 \raise #0.5 "text example"
930 @code{\raise} is actually represented by the @code{raise-markup}
931 function. The markup expression is stored as
934 (list raise-markup 0.5 (list simple-markup "text example"))
937 When the markup is converted to printable objects (Stencils), the
938 @code{raise-markup} function is called as
943 @var{list of property alists}
945 @var{the "text example" markup})
948 The @code{raise-markup} function first creates the stencil for the
949 @code{text example} string, and then it raises that Stencil by 0.5
950 staff space. This is a rather simple example; more complex examples
952 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
955 @node New markup command definition
956 @subsection New markup command definition
958 New markup commands can be defined
959 with the @code{define-markup-command} Scheme macro.
962 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
963 (@var{arg1-type?} @var{arg2-type?} ...)
971 @var{i}th command argument
973 a type predicate for the i@var{th} argument
975 the @q{layout} definition
977 a list of alists, containing all active properties.
980 As a simple example, we show how to add a @code{\smallcaps} command,
981 which selects a small caps font. Normally we could select the
985 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
989 This selects the caps font by setting the @code{font-shape} property to
990 @code{#'caps} for interpreting @code{Text-in-caps}.
992 To make the above available as @code{\smallcaps} command, we must
993 define a function using @code{define-markup-command}. The command should
994 take a single argument of type @code{markup}. Therefore the start of the
995 definition should read
998 (define-markup-command (smallcaps layout props argument) (markup?)
1003 What follows is the content of the command: we should interpret
1004 the @code{argument} as a markup, i.e.,
1007 (interpret-markup layout @dots{} argument)
1011 This interpretation should add @code{'(font-shape . caps)} to the active
1012 properties, so we substitute the following for the @dots{} in the
1016 (cons (list '(font-shape . caps) ) props)
1020 The variable @code{props} is a list of alists, and we prepend to it by
1021 cons'ing a list with the extra setting.
1024 Suppose that we are typesetting a recitative in an opera and
1025 we would like to define a command that will show character names in a
1026 custom manner. Names should be printed with small caps and moved a
1027 bit to the left and top. We will define a @code{\character} command
1028 which takes into account the necessary translation and uses the newly
1029 defined @code{\smallcaps} command:
1032 #(define-markup-command (character layout props name) (string?)
1033 "Print the character name in small caps, translated to the left and
1034 top. Syntax: \\character #\"name\""
1035 (interpret-markup layout props
1036 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1039 There is one complication that needs explanation: texts above and below
1040 the staff are moved vertically to be at a certain distance (the
1041 @code{padding} property) from the staff and the notes. To make sure
1042 that this mechanism does not annihilate the vertical effect of our
1043 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
1044 translated text. Now the @code{#:hspace 0} will be put above the notes,
1046 @code{name} is moved in relation to that empty string. The net effect is
1047 that the text is moved to the upper left.
1049 The final result is as follows:
1053 c''^\markup \character #"Cleopatra"
1054 e'^\markup \character #"Giulio Cesare"
1058 @lilypond[quote,ragged-right]
1059 #(define-markup-command (smallcaps layout props str) (string?)
1060 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
1061 (interpret-markup layout props
1064 (if (= (string-length s) 0)
1066 (markup #:large (string-upcase (substring s 0 1))
1067 #:translate (cons -0.6 0)
1068 #:tiny (string-upcase (substring s 1)))))
1069 (string-split str #\Space)))))
1071 #(define-markup-command (character layout props name) (string?)
1072 "Print the character name in small caps, translated to the left and
1073 top. Syntax: \\character #\"name\""
1074 (interpret-markup layout props
1075 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1078 c''^\markup \character #"Cleopatra" c'' c'' c''
1079 e'^\markup \character #"Giulio Cesare" e' e' e'
1083 We have used the @code{caps} font shape, but suppose that our font
1084 does not have a small-caps variant. In that case we have to fake
1085 the small caps font by setting a string in upcase with the first
1086 letter a little larger:
1089 #(define-markup-command (smallcaps layout props str) (string?)
1090 "Print the string argument in small caps."
1091 (interpret-markup layout props
1094 (if (= (string-length s) 0)
1096 (markup #:large (string-upcase (substring s 0 1))
1097 #:translate (cons -0.6 0)
1098 #:tiny (string-upcase (substring s 1)))))
1099 (string-split str #\Space)))))
1102 The @code{smallcaps} command first splits its string argument into
1103 tokens separated by spaces (@code{(string-split str #\Space)}); for
1104 each token, a markup is built with the first letter made large and
1105 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1106 second markup built with the following letters made tiny and upcased
1107 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1108 introduces a space between markups on a line, the second markup is
1109 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1110 the markups built for each token are put in a line by
1111 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1112 to the @code{interpret-markup} function, with the @code{layout} and
1113 @code{props} arguments.
1115 Note: there is now an internal command @code{\smallCaps} which can
1116 be used to set text in small caps. See
1117 @ref{Text markup commands}, for details.
1120 @node New markup list command definition
1121 @subsection New markup list command definition
1122 Markup list commands are defined with the
1123 @code{define-markup-list-command} Scheme macro, which is similar to the
1124 @code{define-markup-command} macro described in
1125 @ref{New markup command definition}, except that where the later returns
1126 a single stencil, the former returns a list stencils.
1128 In the following example, a @code{\paragraph} markup list command is
1129 defined, which returns a list of justified lines, the first one being
1130 indented. The indent width is taken from the @code{props} argument.
1132 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1133 (let ((indent (chain-assoc-get 'par-indent props 2)))
1134 (interpret-markup-list layout props
1135 (make-justified-lines-markup-list (cons (make-hspace-markup indent)
1139 Besides the usual @code{layout} and @code{props} arguments, the
1140 @code{paragraph} markup list command takes a markup list argument, named
1141 @code{args}. The predicate for markup lists is @code{markup-list?}.
1143 First, the function gets the indent width, a property here named
1144 @code{par-indent}, from the property list @code{props} If the property
1145 is not found, the default value is @code{2}. Then, a list of justified
1146 lines is made using the @code{make-justified-lines-markup-list}
1147 function, which is related to the @code{\justified-lines}
1148 built-in markup list command. An horizontal space is added at the
1149 beginning using the @code{make-hspace-markup} function. Finally, the
1150 markup list is interpreted using the @code{interpret-markup-list}
1153 This new markup list command can be used as follows:
1157 The art of music typography is called \italic @{(plate) engraving.@}
1158 The term derives from the traditional process of music printing.
1159 Just a few decades ago, sheet music was made by cutting and stamping
1160 the music into a zinc or pewter plate in mirror image.
1162 \override-lines #'(par-indent . 4) \paragraph @{
1163 The plate would be inked, the depressions caused by the cutting
1164 and stamping would hold ink. An image was formed by pressing paper
1165 to the plate. The stamping and cutting was completely done by
1171 @node Contexts for programmers
1172 @section Contexts for programmers
1175 * Context evaluation::
1176 * Running a function on all layout objects::
1179 @node Context evaluation
1180 @subsection Context evaluation
1182 @cindex calling code during interpreting
1183 @funindex \applyContext
1185 Contexts can be modified during interpretation with Scheme code. The
1188 \applyContext @var{function}
1191 @var{function} should be a Scheme function taking a single argument,
1192 being the context to apply it to. The following code will print the
1193 current bar number on the standard output during the compile:
1198 (format #t "\nWe were called in barnumber ~a.\n"
1199 (ly:context-property x 'currentBarNumber)))
1204 @node Running a function on all layout objects
1205 @subsection Running a function on all layout objects
1208 @cindex calling code on layout objects
1209 @funindex \applyOutput
1212 The most versatile way of tuning an object is @code{\applyOutput}. Its
1215 \applyOutput @var{context} @var{proc}
1219 where @var{proc} is a Scheme function, taking three arguments.
1221 When interpreted, the function @var{proc} is called for every layout
1222 object found in the context @var{context}, with the following
1225 @item the layout object itself,
1226 @item the context where the layout object was created, and
1227 @item the context where @code{\applyOutput} is processed.
1231 In addition, the cause of the layout object, i.e., the music
1232 expression or object that was responsible for creating it, is in the
1233 object property @code{cause}. For example, for a note head, this is a
1234 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
1235 this is a @internalsref{NoteHead} object.
1237 Here is a function to use for @code{\applyOutput}; it blanks
1238 note-heads on the center-line:
1241 (define (blanker grob grob-origin context)
1242 (if (and (memq (ly:grob-property grob 'interfaces)
1243 note-head-interface)
1244 (eq? (ly:grob-property grob 'staff-position) 0))
1245 (set! (ly:grob-property grob 'transparent) #t)))
1249 @node Scheme procedures as properties
1250 @section Scheme procedures as properties
1252 Properties (like thickness, direction, etc.) can be set at fixed values
1253 with \override, e.g.
1256 \override Stem #'thickness = #2.0
1259 Properties can also be set to a Scheme procedure,
1261 @lilypond[fragment,verbatim,quote,relative=2]
1262 \override Stem #'thickness = #(lambda (grob)
1263 (if (= UP (ly:grob-property grob 'direction))
1270 In this case, the procedure is executed as soon as the value of the
1271 property is requested during the formatting process.
1273 Most of the typesetting engine is driven by such callbacks.
1274 Properties that typically use callbacks include
1278 The printing routine, that constructs a drawing for the symbol
1280 The routine that sets the horizontal position
1282 The routine that computes the width of an object
1285 The procedure always takes a single argument, being the grob.
1287 If routines with multiple arguments must be called, the current grob
1288 can be inserted with a grob closure. Here is a setting from
1289 @code{AccidentalSuggestion},
1293 ,(ly:make-simple-closure
1295 ,(ly:make-simple-closure
1296 (list ly:self-alignment-interface::centered-on-x-parent))
1297 ,(ly:make-simple-closure
1298 (list ly:self-alignment-interface::x-aligned-on-self)))))
1302 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1303 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1304 with the grob as argument. The results are added with the @code{+}
1305 function. To ensure that this addition is properly executed, the whole
1306 thing is enclosed in @code{ly:make-simple-closure}.
1308 In fact, using a single procedure as property value is equivalent to
1311 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1315 The inner @code{ly:make-simple-closure} supplies the grob as argument
1316 to @var{proc}, the outer ensures that result of the function is
1317 returned, rather than the @code{simple-closure} object.