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::
26 * Using Scheme code instead of \tweak::
32 @section Music functions
34 This section discusses how to create music functions within LilyPond.
37 * Overview of music functions::
38 * Simple substitution functions::
39 * Paired substitution functions::
40 * Mathematics in functions::
42 * Functions without arguments::
43 * Overview of available music functions::
46 @node Overview of music functions
47 @subsection Overview of music functions
49 Making a function which substitutes a variable into LilyPond
50 code is easy. The general form of these functions is
54 #(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
55 (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
64 @multitable @columnfractions .33 .66
65 @item @var{vari} @tab @var{i}th variable
66 @item @var{vari-type?} @tab type of @var{i}th variable
67 @item @var{...music...} @tab normal LilyPond input, using
68 variables as @code{#$var1}, etc.
71 There following input types may be used as variables
72 in a music function. This list is not exhaustive; see
73 other documentation specifically about Scheme for more
76 @multitable @columnfractions .33 .66
77 @headitem Input type @tab @var{vari-type?} notation
78 @item Integer @tab @code{integer?}
79 @item Float (decimal number) @tab @code{number?}
80 @item Text string @tab @code{string?}
81 @item Markup @tab @code{markup?}
82 @item Music expression @tab @code{ly:music?}
83 @item A pair of variables @tab @code{pair?}
86 The @code{parser} and @code{location} arguments are mandatory,
87 and are used in some advanced situations. The @code{parser}
88 argument is used to gain access to the value of another LilyPond
89 variable. The @code{location} argument
90 is used to set the @q{origin} of the music expression that is built
91 by the music function, so that in case of a syntax error LilyPond
92 can tell the user an appropriate place to look in the input file.
95 @node Simple substitution functions
96 @subsection Simple substitution functions
98 Here is a simple example,
100 @lilypond[quote,verbatim,ragged-right]
101 padText = #(define-music-function (parser location padding) (number?)
103 \once \override TextScript #'padding = #$padding
111 c4^"piu mosso" fis a g
115 Music expressions may be substituted as well,
117 @lilypond[quote,verbatim,ragged-right]
118 custosNote = #(define-music-function (parser location note)
121 \once \override Voice.NoteHead #'stencil =
122 #ly:text-interface::print
123 \once \override Voice.NoteHead #'text =
124 \markup \musicglyph #"custodes.mensural.u0"
125 \once \override Voice.Stem #'stencil = ##f
129 { c' d' e' f' \custosNote g' }
132 Multiple variables may be used,
134 @lilypond[quote,verbatim,ragged-right]
135 tempoMark = #(define-music-function (parser location padding marktext)
138 \once \override Score . RehearsalMark #'padding = $padding
139 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
140 \mark \markup { \bold $marktext }
145 \tempoMark #3.0 #"Allegro"
151 @node Paired substitution functions
152 @subsection Paired substitution functions
154 Some @code{\override} commands require a pair of numbers
155 (called a @code{cons cell} in Scheme). To pass these numbers
156 into a function, either use a @code{pair?} variable, or
157 insert the @code{cons} into the music function.
162 #(define-music-function (parser location beg-end)
165 \once \override Beam #'positions = #$beg-end
169 \manualBeam #'(3 . 6) c8 d e f
177 @lilypond[quote,verbatim,ragged-right]
179 #(define-music-function (parser location beg end)
182 \once \override Beam #'positions = #(cons $beg $end)
186 \manualBeam #3 #6 c8 d e f
191 @node Mathematics in functions
192 @subsection Mathematics in functions
194 Music functions can involve Scheme programming in
195 addition to simple substitution,
197 @lilypond[quote,verbatim,ragged-right]
198 AltOn = #(define-music-function (parser location mag) (number?)
199 #{ \override Stem #'length = #$(* 7.0 mag)
200 \override NoteHead #'font-size =
201 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
204 \revert Stem #'length
205 \revert NoteHead #'font-size
208 { c'2 \AltOn #0.5 c'4 c'
209 \AltOn #1.5 c' c' \AltOff c'2 }
213 This example may be rewritten to pass in music expressions,
215 @lilypond[quote,verbatim,ragged-right]
216 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
217 #{ \override Stem #'length = #$(* 7.0 mag)
218 \override NoteHead #'font-size =
219 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
221 \revert Stem #'length
222 \revert NoteHead #'font-size #})
224 { c'2 \withAlt #0.5 {c'4 c'}
225 \withAlt #1.5 {c' c'} c'2 }
229 @subsection Void functions
231 A music function must return a music expression, but sometimes we
232 may want to have a function which does not involve music (such as
233 turning off Point and Click). To do this, we return a @code{void}
237 that is returned is the @code{(make-music ...)}. With the
238 @code{'void} property set to @code{#t}, the parser is told to
239 actually disregard this returned music
240 expression. Thus the important part of the void music function is the
241 processing done by the function, not the music expression that is
246 #(define-music-function (parser location) ()
247 (ly:set-option 'point-and-click #f)
248 (make-music 'SequentialMusic 'void #t))
250 \noPointAndClick % disable point and click
254 @node Functions without arguments
255 @subsection Functions without arguments
257 In most cases a function without arguments should be written
261 dolce = \markup@{ \italic \bold dolce @}
264 However, in rare cases it may be useful to create a music function
269 #(define-music-function (parser location) ()
270 (if (eq? #t (ly:get-option 'display-bar-numbers))
271 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
275 To actually display bar numbers where this function is called,
276 invoke @command{lilypond} with
279 lilypond -d display-bar-numbers FILENAME.ly
283 @node Overview of available music functions
284 @subsection Overview of available music functions
286 @c fixme ; this should be move somewhere else?
287 The following commands are music functions
289 @include identifiers.tely
293 @node Programmer interfaces
294 @section Programmer interfaces
296 This section contains information about mixing LilyPond
300 * Input variables and Scheme::
301 * Internal music representation::
305 @node Input variables and Scheme
306 @subsection Input variables and Scheme
308 The input format supports the notion of variables: in the following
309 example, a music expression is assigned to a variable with the name
313 traLaLa = @{ c'4 d'4 @}
318 There is also a form of scoping: in the following example, the
319 @code{\layout} block also contains a @code{traLaLa} variable, which is
320 independent of the outer @code{\traLaLa}.
322 traLaLa = @{ c'4 d'4 @}
323 \layout @{ traLaLa = 1.0 @}
326 In effect, each input file is a scope, and all @code{\header},
327 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
330 Both variables and scoping are implemented in the GUILE module system.
331 An anonymous Scheme module is attached to each scope. An assignment of
334 traLaLa = @{ c'4 d'4 @}
338 is internally converted to a Scheme definition
340 (define traLaLa @var{Scheme value of `@code{... }'})
343 This means that input variables and Scheme variables may be freely
344 mixed. In the following example, a music fragment is stored in the
345 variable @code{traLaLa}, and duplicated using Scheme. The result is
346 imported in a @code{\score} block by means of a second variable
350 traLaLa = { c'4 d'4 }
352 %% dummy action to deal with parser lookahead
353 #(display "this needs to be here, sorry!")
355 #(define newLa (map ly:music-deep-copy
356 (list traLaLa traLaLa)))
358 (make-sequential-music newLa))
363 @c Due to parser lookahead
365 In this example, the assignment happens after parser has verified that
366 nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
367 the dummy statement in the above example, the @code{newLa} definition
368 is executed before @code{traLaLa} is defined, leading to a syntax
371 The above example shows how to @q{export} music expressions from the
372 input to the Scheme interpreter. The opposite is also possible. By
373 wrapping a Scheme value in the function @code{ly:export}, a Scheme
374 value is interpreted as if it were entered in LilyPond syntax.
375 Instead of defining @code{\twice}, the example above could also have
380 @{ #(ly:export (make-sequential-music (list newLa))) @}
383 Scheme code is evaluated as soon as the parser encounters it. To
384 define some Scheme code in a macro (to be called later), use
385 @ref{Void functions}, or
389 (ly:set-option 'point-and-click #f))
399 Mixing Scheme and LilyPond variables is not possible with the
400 @code{--safe} option.
403 @node Internal music representation
404 @subsection Internal music representation
406 When a music expression is parsed, it is converted into a set of
407 Scheme music objects. The defining property of a music object is that
408 it takes up time. Time is a rational number that measures the length
409 of a piece of music in whole notes.
411 A music object has three kinds of types:
414 music name: Each music expression has a name. For example, a note
415 leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
416 a @rinternals{SimultaneousMusic}. A list of all expressions
417 available is in the Internals Reference manual, under
418 @rinternals{Music expressions}.
421 @q{type} or interface: Each music name has several @q{types} or
422 interfaces, for example, a note is an @code{event}, but it is also a
423 @code{note-event}, a @code{rhythmic-event}, and a
424 @code{melodic-event}. All classes of music are listed in the
425 Internals Reference, under
426 @rinternals{Music classes}.
429 C++ object: Each music object is represented by an object of the C++
433 The actual information of a music expression is stored in properties.
434 For example, a @rinternals{NoteEvent} has @code{pitch} and
435 @code{duration} properties that store the pitch and duration of that
436 note. A list of all properties available is in the internals manual,
437 under @rinternals{Music properties}.
439 A compound music expression is a music object that contains other
440 music objects in its properties. A list of objects can be stored in
441 the @code{elements} property of a music object, or a single @q{child}
442 music object in the @code{element} property. For example,
443 @rinternals{SequentialMusic} has its children in @code{elements},
444 and @rinternals{GraceMusic} has its single argument in
445 @code{element}. The body of a repeat is stored in the @code{element}
446 property of @rinternals{RepeatedMusic}, and the alternatives in
451 @node Building complicated functions
452 @section Building complicated functions
454 This section explains how to gather the information necessary
455 to create complicated music functions.
458 * Displaying music expressions::
460 * Doubling a note with slurs (example)::
461 * Adding articulation to notes (example)::
465 @node Displaying music expressions
466 @subsection Displaying music expressions
468 @cindex internal storage
469 @funindex \displayMusic
471 When writing a music function it is often instructive to inspect how
472 a music expression is stored internally. This can be done with the
473 music function @code{\displayMusic}
477 \displayMusic @{ c'4\f @}
494 (ly:make-duration 2 0 1 1)
496 (ly:make-pitch 0 0 0))
498 'AbsoluteDynamicEvent
503 By default, LilyPond will print these messages to the console along
504 with all the other messages. To split up these messages and save
505 the results of @code{\display@{STUFF@}}, redirect the output to
509 lilypond file.ly >display.txt
512 With a bit of reformatting, the above information is
516 (make-music 'SequentialMusic
517 'elements (list (make-music 'EventChord
518 'elements (list (make-music 'NoteEvent
519 'duration (ly:make-duration 2 0 1 1)
520 'pitch (ly:make-pitch 0 0 0))
521 (make-music 'AbsoluteDynamicEvent
525 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
526 and its inner expressions are stored as a list in its @code{'elements}
527 property. A note is represented as an @code{EventChord} expression,
528 containing a @code{NoteEvent} object (storing the duration and
529 pitch properties) and any extra information (in this case, an
530 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
533 @node Music properties
534 @subsection Music properties
536 The @code{NoteEvent} object is the first object of the
537 @code{'elements} property of @code{someNote}.
541 \displayMusic \someNote
549 (ly:make-duration 2 0 1 1)
551 (ly:make-pitch 0 0 0))))
554 The @code{display-scheme-music} function is the function used by
555 @code{\displayMusic} to display the Scheme representation of a music
559 #(display-scheme-music (first (ly:music-property someNote 'elements)))
564 (ly:make-duration 2 0 1 1)
566 (ly:make-pitch 0 0 0))
569 Then the note pitch is accessed through the @code{'pitch} property
570 of the @code{NoteEvent} object,
573 #(display-scheme-music
574 (ly:music-property (first (ly:music-property someNote 'elements))
577 (ly:make-pitch 0 0 0)
580 The note pitch can be changed by setting this 'pitch property,
582 @funindex \displayLilyMusic
585 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
587 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
588 \displayLilyMusic \someNote
594 @node Doubling a note with slurs (example)
595 @subsection Doubling a note with slurs (example)
597 Suppose we want to create a function which translates
598 input like @code{a} into @code{a( a)}. We begin
599 by examining the internal representation of the music
600 we want to end up with.
603 \displayMusic@{ a'( a') @}
614 (ly:make-duration 2 0 1 1)
616 (ly:make-pitch 0 5 0))
627 (ly:make-duration 2 0 1 1)
629 (ly:make-pitch 0 5 0))
636 The bad news is that the @code{SlurEvent} expressions
637 must be added @q{inside} the note (or more precisely,
638 inside the @code{EventChord} expression).
640 Now we examine the input,
652 (ly:make-duration 2 0 1 1)
654 (ly:make-pitch 0 5 0))))))
657 So in our function, we need to clone this expression (so that we
658 have two notes to build the sequence), add @code{SlurEvents} to the
659 @code{'elements} property of each one, and finally make a
660 @code{SequentialMusic} with the two @code{EventChords}.
663 doubleSlur = #(define-music-function (parser location note) (ly:music?)
664 "Return: @{ note ( note ) @}.
665 `note' is supposed to be an EventChord."
666 (let ((note2 (ly:music-deep-copy note)))
667 (set! (ly:music-property note 'elements)
668 (cons (make-music 'SlurEvent 'span-direction -1)
669 (ly:music-property note 'elements)))
670 (set! (ly:music-property note2 'elements)
671 (cons (make-music 'SlurEvent 'span-direction 1)
672 (ly:music-property note2 'elements)))
673 (make-music 'SequentialMusic 'elements (list note note2))))
677 @node Adding articulation to notes (example)
678 @subsection Adding articulation to notes (example)
680 The easy way to add articulation to notes is to merge two music
681 expressions into one context, as explained in
682 @ref{Creating contexts}. However, suppose that we want to write
683 a music function which does this.
685 A @code{$variable} inside the @code{#@{...#@}} notation is like
686 using a regular @code{\variable} in classical LilyPond
687 notation. We know that
694 will not work in LilyPond. We could avoid this problem by attaching
695 the articulation to a fake note,
698 @{ << \music s1*0-.-> @}
702 but for the sake of this example, we will learn how to do this in
703 Scheme. We begin by examining our input and desired output,
715 (ly:make-duration 2 0 1 1)
717 (ly:make-pitch -1 0 0))))
728 (ly:make-duration 2 0 1 1)
730 (ly:make-pitch -1 0 0))
737 We see that a note (@code{c4}) is represented as an @code{EventChord}
738 expression, with a @code{NoteEvent} expression in its elements list. To
739 add a marcato articulation, an @code{ArticulationEvent} expression must
740 be added to the elements property of the @code{EventChord}
743 To build this function, we begin with
746 (define (add-marcato event-chord)
747 "Add a marcato ArticulationEvent to the elements of `event-chord',
748 which is supposed to be an EventChord expression."
749 (let ((result-event-chord (ly:music-deep-copy event-chord)))
750 (set! (ly:music-property result-event-chord 'elements)
751 (cons (make-music 'ArticulationEvent
752 'articulation-type "marcato")
753 (ly:music-property result-event-chord 'elements)))
757 The first line is the way to define a function in Scheme: the function
758 name is @code{add-marcato}, and has one variable called
759 @code{event-chord}. In Scheme, the type of variable is often clear
760 from its name. (this is good practice in other programming languages,
768 is a description of what the function does. This is not strictly
769 necessary, but just like clear variable names, it is good practice.
772 (let ((result-event-chord (ly:music-deep-copy event-chord)))
775 @code{let} is used to declare local variables. Here we use one local
776 variable, named @code{result-event-chord}, to which we give the value
777 @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
778 a function specific to LilyPond, like all functions prefixed by
779 @code{ly:}. It is use to make a copy of a music
780 expression. Here we copy @code{event-chord} (the parameter of the
781 function). Recall that our purpose is to add a marcato to an
782 @code{EventChord} expression. It is better to not modify the
783 @code{EventChord} which was given as an argument, because it may be
786 Now we have a @code{result-event-chord}, which is a
787 @code{NoteEventChord} expression and is a copy of @code{event-chord}. We
788 add the marcato to its elements list property.
791 (set! place new-value)
794 Here, what we want to set (the @q{place}) is the @q{elements} property of
795 @code{result-event-chord} expression.
798 (ly:music-property result-event-chord 'elements)
801 @code{ly:music-property} is the function used to access music properties
802 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
803 see in the @code{\displayMusic} output above). The new value is the
804 former elements property, with an extra item: the
805 @code{ArticulationEvent} expression, which we copy from the
806 @code{\displayMusic} output,
809 (cons (make-music 'ArticulationEvent
810 'articulation-type "marcato")
811 (ly:music-property result-event-chord 'elements))
814 @code{cons} is used to add an element to a list without modifying the
815 original list. This is what we
816 want: the same list as before, plus the new @code{ArticulationEvent}
817 expression. The order inside the elements property is not important here.
819 Finally, once we have added the marcato articulation to its @code{elements}
820 property, we can return @code{result-event-chord}, hence the last line of
823 Now we transform the @code{add-marcato} function into a music
827 addMarcato = #(define-music-function (parser location event-chord)
829 "Add a marcato ArticulationEvent to the elements of `event-chord',
830 which is supposed to be an EventChord expression."
831 (let ((result-event-chord (ly:music-deep-copy event-chord)))
832 (set! (ly:music-property result-event-chord 'elements)
833 (cons (make-music 'ArticulationEvent
834 'articulation-type "marcato")
835 (ly:music-property result-event-chord 'elements)))
839 We may verify that this music function works correctly,
842 \displayMusic \addMarcato c4
846 @node Markup programmer interface
847 @section Markup programmer interface
849 Markups are implemented as special Scheme functions which produce a
850 Stencil object given a number of arguments.
853 * Markup construction in Scheme::
854 * How markups work internally::
855 * New markup command definition::
856 * New markup list command definition::
860 @node Markup construction in Scheme
861 @subsection Markup construction in Scheme
863 @cindex defining markup commands
865 The @code{markup} macro builds markup expressions in Scheme while
866 providing a LilyPond-like syntax. For example,
868 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
869 #:larger #:line ("foo" "bar" "baz")))
875 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
876 \larger \line @{ foo bar baz @} @}
880 This example demonstrates the main translation rules between regular
881 LilyPond markup syntax and Scheme markup syntax.
884 @multitable @columnfractions .3 .3
885 @item @b{LilyPond} @tab @b{Scheme}
886 @item @code{\markup markup1} @tab @code{(markup markup1)}
887 @item @code{\markup @{ markup1 markup2 ... @}} @tab
888 @code{(markup markup1 markup2 ... )}
889 @item @code{\command} @tab @code{#:command}
890 @item @code{\variable} @tab @code{variable}
891 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
892 @item @code{string} @tab @code{"string"}
893 @item @code{#scheme-arg} @tab @code{scheme-arg}
897 The whole Scheme language is accessible inside the
898 @code{markup} macro. For example, You may use function calls inside
899 @code{markup} in order to manipulate character strings. This is
900 useful when defining new markup commands (see
901 @ref{New markup command definition}).
906 The markup-list argument of commands such as @code{#:line},
907 @code{#:center}, and @code{#:column} cannot be a variable or
908 the result of a function call.
911 (markup #:line (function-that-returns-markups))
915 is invalid. One should use the @code{make-line-markup},
916 @code{make-center-markup}, or @code{make-column-markup} functions
920 (markup (make-line-markup (function-that-returns-markups)))
924 @node How markups work internally
925 @subsection How markups work internally
930 \raise #0.5 "text example"
934 @code{\raise} is actually represented by the @code{raise-markup}
935 function. The markup expression is stored as
938 (list raise-markup 0.5 (list simple-markup "text example"))
941 When the markup is converted to printable objects (Stencils), the
942 @code{raise-markup} function is called as
947 @var{list of property alists}
949 @var{the "text example" markup})
952 The @code{raise-markup} function first creates the stencil for the
953 @code{text example} string, and then it raises that Stencil by 0.5
954 staff space. This is a rather simple example; more complex examples
956 of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
959 @node New markup command definition
960 @subsection New markup command definition
962 New markup commands can be defined
963 with the @code{define-markup-command} Scheme macro.
966 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
967 (@var{arg1-type?} @var{arg2-type?} ...)
975 @var{i}th command argument
977 a type predicate for the i@var{th} argument
979 the @q{layout} definition
981 a list of alists, containing all active properties.
984 As a simple example, we show how to add a @code{\smallcaps} command,
985 which selects a small caps font. Normally we could select the
989 \markup @{ \override #'(font-shape . caps) Text-in-caps @}
993 This selects the caps font by setting the @code{font-shape} property to
994 @code{#'caps} for interpreting @code{Text-in-caps}.
996 To make the above available as @code{\smallcaps} command, we must
997 define a function using @code{define-markup-command}. The command should
998 take a single argument of type @code{markup}. Therefore the start of the
999 definition should read
1002 (define-markup-command (smallcaps layout props argument) (markup?)
1007 What follows is the content of the command: we should interpret
1008 the @code{argument} as a markup, i.e.,
1011 (interpret-markup layout @dots{} argument)
1015 This interpretation should add @code{'(font-shape . caps)} to the active
1016 properties, so we substitute the following for the @dots{} in the
1020 (cons (list '(font-shape . caps) ) props)
1024 The variable @code{props} is a list of alists, and we prepend to it by
1025 cons'ing a list with the extra setting.
1028 Suppose that we are typesetting a recitative in an opera and
1029 we would like to define a command that will show character names in a
1030 custom manner. Names should be printed with small caps and moved a
1031 bit to the left and top. We will define a @code{\character} command
1032 which takes into account the necessary translation and uses the newly
1033 defined @code{\smallcaps} command:
1036 #(define-markup-command (character layout props name) (string?)
1037 "Print the character name in small caps, translated to the left and
1038 top. Syntax: \\character #\"name\""
1039 (interpret-markup layout props
1040 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1043 There is one complication that needs explanation: texts above and below
1044 the staff are moved vertically to be at a certain distance (the
1045 @code{padding} property) from the staff and the notes. To make sure
1046 that this mechanism does not annihilate the vertical effect of our
1047 @code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
1048 translated text. Now the @code{#:hspace 0} will be put above the notes,
1050 @code{name} is moved in relation to that empty string. The net effect is
1051 that the text is moved to the upper left.
1053 The final result is as follows:
1057 c''^\markup \character #"Cleopatra"
1058 e'^\markup \character #"Giulio Cesare"
1062 @lilypond[quote,ragged-right]
1063 #(define-markup-command (smallcaps layout props str) (string?)
1064 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
1065 (interpret-markup layout props
1068 (if (= (string-length s) 0)
1070 (markup #:large (string-upcase (substring s 0 1))
1071 #:translate (cons -0.6 0)
1072 #:tiny (string-upcase (substring s 1)))))
1073 (string-split str #\Space)))))
1075 #(define-markup-command (character layout props name) (string?)
1076 "Print the character name in small caps, translated to the left and
1077 top. Syntax: \\character #\"name\""
1078 (interpret-markup layout props
1079 (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
1082 c''^\markup \character #"Cleopatra" c'' c'' c''
1083 e'^\markup \character #"Giulio Cesare" e' e' e'
1087 We have used the @code{caps} font shape, but suppose that our font
1088 does not have a small-caps variant. In that case we have to fake
1089 the small caps font by setting a string in upcase with the first
1090 letter a little larger:
1093 #(define-markup-command (smallcaps layout props str) (string?)
1094 "Print the string argument in small caps."
1095 (interpret-markup layout props
1098 (if (= (string-length s) 0)
1100 (markup #:large (string-upcase (substring s 0 1))
1101 #:translate (cons -0.6 0)
1102 #:tiny (string-upcase (substring s 1)))))
1103 (string-split str #\Space)))))
1106 The @code{smallcaps} command first splits its string argument into
1107 tokens separated by spaces (@code{(string-split str #\Space)}); for
1108 each token, a markup is built with the first letter made large and
1109 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
1110 second markup built with the following letters made tiny and upcased
1111 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
1112 introduces a space between markups on a line, the second markup is
1113 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
1114 the markups built for each token are put in a line by
1115 @code{(make-line-markup ...)}. Finally, the resulting markup is passed
1116 to the @code{interpret-markup} function, with the @code{layout} and
1117 @code{props} arguments.
1119 Note: there is now an internal command @code{\smallCaps} which can
1120 be used to set text in small caps. See
1121 @ref{Text markup commands}, for details.
1125 Currently, the available combinations of arguments (after the standard
1126 @var{layout} and @var{props} arguments) to a markup command defined with
1127 @code{define-markup-command} are limited as follows.
1133 @itemx @var{markup markup}
1135 @itemx @var{scm markup}
1136 @itemx @var{scm scm}
1137 @itemx @var{scm scm markup}
1138 @itemx @var{scm scm markup markup}
1139 @itemx @var{scm markup markup}
1140 @itemx @var{scm scm scm}
1144 In the above table, @var{scm} represents native Scheme data types like
1145 @q{number} or @q{string}.
1147 As an example, it is not possible to use a markup command @code{foo} with
1148 four arguments defined as
1151 #(define-markup-command (foo layout props
1152 num1 str1 num2 str2)
1153 (number? string? number? string?)
1158 If you apply it as, say,
1161 \markup \foo #1 #"bar" #2 #"baz"
1164 @cindex Scheme signature
1165 @cindex signature, Scheme
1167 @command{lilypond} complains that it cannot parse @code{foo} due to its
1168 unknown Scheme signature.
1171 @node New markup list command definition
1172 @subsection New markup list command definition
1173 Markup list commands are defined with the
1174 @code{define-markup-list-command} Scheme macro, which is similar to the
1175 @code{define-markup-command} macro described in
1176 @ref{New markup command definition}, except that where the latter returns
1177 a single stencil, the former returns a list stencils.
1179 In the following example, a @code{\paragraph} markup list command is
1180 defined, which returns a list of justified lines, the first one being
1181 indented. The indent width is taken from the @code{props} argument.
1183 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1184 (let ((indent (chain-assoc-get 'par-indent props 2)))
1185 (interpret-markup-list layout props
1186 (make-justified-lines-markup-list (cons (make-hspace-markup indent)
1190 Besides the usual @code{layout} and @code{props} arguments, the
1191 @code{paragraph} markup list command takes a markup list argument, named
1192 @code{args}. The predicate for markup lists is @code{markup-list?}.
1194 First, the function gets the indent width, a property here named
1195 @code{par-indent}, from the property list @code{props} If the property
1196 is not found, the default value is @code{2}. Then, a list of justified
1197 lines is made using the @code{make-justified-lines-markup-list}
1198 function, which is related to the @code{\justified-lines}
1199 built-in markup list command. An horizontal space is added at the
1200 beginning using the @code{make-hspace-markup} function. Finally, the
1201 markup list is interpreted using the @code{interpret-markup-list}
1204 This new markup list command can be used as follows:
1208 The art of music typography is called \italic @{(plate) engraving.@}
1209 The term derives from the traditional process of music printing.
1210 Just a few decades ago, sheet music was made by cutting and stamping
1211 the music into a zinc or pewter plate in mirror image.
1213 \override-lines #'(par-indent . 4) \paragraph @{
1214 The plate would be inked, the depressions caused by the cutting
1215 and stamping would hold ink. An image was formed by pressing paper
1216 to the plate. The stamping and cutting was completely done by
1222 @node Contexts for programmers
1223 @section Contexts for programmers
1226 * Context evaluation::
1227 * Running a function on all layout objects::
1230 @node Context evaluation
1231 @subsection Context evaluation
1233 @cindex calling code during interpreting
1234 @funindex \applyContext
1236 Contexts can be modified during interpretation with Scheme code. The
1239 \applyContext @var{function}
1242 @var{function} should be a Scheme function taking a single argument,
1243 being the context to apply it to. The following code will print the
1244 current bar number on the standard output during the compile:
1249 (format #t "\nWe were called in barnumber ~a.\n"
1250 (ly:context-property x 'currentBarNumber)))
1255 @node Running a function on all layout objects
1256 @subsection Running a function on all layout objects
1259 @cindex calling code on layout objects
1260 @funindex \applyOutput
1263 The most versatile way of tuning an object is @code{\applyOutput}. Its
1266 \applyOutput @var{context} @var{proc}
1270 where @var{proc} is a Scheme function, taking three arguments.
1272 When interpreted, the function @var{proc} is called for every layout
1273 object found in the context @var{context}, with the following
1276 @item the layout object itself,
1277 @item the context where the layout object was created, and
1278 @item the context where @code{\applyOutput} is processed.
1282 In addition, the cause of the layout object, i.e., the music
1283 expression or object that was responsible for creating it, is in the
1284 object property @code{cause}. For example, for a note head, this is a
1285 @rinternals{NoteHead} event, and for a @rinternals{Stem} object,
1286 this is a @rinternals{NoteHead} object.
1288 Here is a function to use for @code{\applyOutput}; it blanks
1289 note-heads on the center-line:
1292 (define (blanker grob grob-origin context)
1293 (if (and (memq (ly:grob-property grob 'interfaces)
1294 note-head-interface)
1295 (eq? (ly:grob-property grob 'staff-position) 0))
1296 (set! (ly:grob-property grob 'transparent) #t)))
1300 @node Scheme procedures as properties
1301 @section Scheme procedures as properties
1303 Properties (like thickness, direction, etc.) can be set at fixed values
1304 with \override, e.g.
1307 \override Stem #'thickness = #2.0
1310 Properties can also be set to a Scheme procedure,
1312 @lilypond[fragment,verbatim,quote,relative=2]
1313 \override Stem #'thickness = #(lambda (grob)
1314 (if (= UP (ly:grob-property grob 'direction))
1321 In this case, the procedure is executed as soon as the value of the
1322 property is requested during the formatting process.
1324 Most of the typesetting engine is driven by such callbacks.
1325 Properties that typically use callbacks include
1329 The printing routine, that constructs a drawing for the symbol
1331 The routine that sets the horizontal position
1333 The routine that computes the width of an object
1336 The procedure always takes a single argument, being the grob.
1338 If routines with multiple arguments must be called, the current grob
1339 can be inserted with a grob closure. Here is a setting from
1340 @code{AccidentalSuggestion},
1344 ,(ly:make-simple-closure
1346 ,(ly:make-simple-closure
1347 (list ly:self-alignment-interface::centered-on-x-parent))
1348 ,(ly:make-simple-closure
1349 (list ly:self-alignment-interface::x-aligned-on-self)))))
1353 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1354 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1355 with the grob as argument. The results are added with the @code{+}
1356 function. To ensure that this addition is properly executed, the whole
1357 thing is enclosed in @code{ly:make-simple-closure}.
1359 In fact, using a single procedure as property value is equivalent to
1362 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1366 The inner @code{ly:make-simple-closure} supplies the grob as argument
1367 to @var{proc}, the outer ensures that result of the function is
1368 returned, rather than the @code{simple-closure} object.
1371 @node Using Scheme code instead of \tweak
1372 @section Using Scheme code instead of @code{\tweak}
1374 The main disadvantage of @code{\tweak} is its syntactical
1375 inflexibility. For example, the following produces a syntax error.
1378 F = \tweak #'font-size #-3 -\flageolet
1386 With other words, @code{\tweak} doesn't behave like an articulation
1387 regarding the syntax; in particular, it can't be attached with
1388 @code{^} and @code{_}.
1390 Using Scheme, this problem can be circumvented. The route to the
1391 result is given in @ref{Adding articulation to notes (example)},
1392 especially how to use @code{\displayMusic} as a helping guide.
1395 F = #(let ((m (make-music 'ArticulationEvent
1396 'articulation-type "flageolet")))
1397 (set! (ly:music-property m 'tweaks)
1398 (acons 'font-size -3
1399 (ly:music-property m 'tweaks)))
1408 Here, the @code{tweaks} properties of the flageolet object
1409 @code{m} (created with @code{make-music}) are extracted with
1410 @code{ly:music-property}, a new key-value pair to change the
1411 font size is prepended to the property list with the
1412 @code{acons} Scheme function, and the result is finally
1413 written back with @code{set!}. The last element of the
1414 @code{let} block is the return value, @code{m} itself.
1418 @node Difficult tweaks
1419 @section Difficult tweaks
1421 There are a few classes of difficult adjustments.
1427 One type of difficult adjustment is the appearance of spanner objects,
1428 such as slur and tie. Initially, only one of these objects is created,
1429 and they can be adjusted with the normal mechanism. However, in some
1430 cases the spanners cross line breaks. If this happens, these objects
1431 are cloned. A separate object is created for every system that it is
1432 in. These are clones of the original object and inherit all
1433 properties, including @code{\override}s.
1436 In other words, an @code{\override} always affects all pieces of a
1437 broken spanner. To change only one part of a spanner at a line break,
1438 it is necessary to hook into the formatting process. The
1439 @code{after-line-breaking} callback contains the Scheme procedure that
1440 is called after the line breaks have been determined, and layout
1441 objects have been split over different systems.
1443 In the following example, we define a procedure
1444 @code{my-callback}. This procedure
1448 determines if we have been split across line breaks
1450 if yes, retrieves all the split objects
1452 checks if we are the last of the split objects
1454 if yes, it sets @code{extra-offset}.
1457 This procedure is installed into @rinternals{Tie}, so the last part
1458 of the broken tie is translated up.
1460 @lilypond[quote,verbatim,ragged-right]
1461 #(define (my-callback grob)
1463 ; have we been split?
1464 (orig (ly:grob-original grob))
1466 ; if yes, get the split pieces (our siblings)
1467 (siblings (if (ly:grob? orig)
1468 (ly:spanner-broken-into orig) '() )))
1470 (if (and (>= (length siblings) 2)
1471 (eq? (car (last-pair siblings)) grob))
1472 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1475 \override Tie #'after-line-breaking =
1482 When applying this trick, the new @code{after-line-breaking} callback
1483 should also call the old one @code{after-line-breaking}, if there is
1484 one. For example, if using this with @code{Hairpin},
1485 @code{ly:hairpin::after-line-breaking} should also be called.
1488 @item Some objects cannot be changed with @code{\override} for
1489 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1490 and @code{PaperColumn}. They can be changed with the
1491 @code{\overrideProperty} function, which works similar to @code{\once
1492 \override}, but uses a different syntax.
1496 #"Score.NonMusicalPaperColumn" % Grob name
1497 #'line-break-system-details % Property name
1498 #'((next-padding . 20)) % Value
1501 Note, however, that @code{\override}, applied to
1502 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1503 expected within @code{\context} blocks.