1 @c -*- coding: utf-8; mode: texinfo; -*-
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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node Interfaces for programmers
14 @chapter Interfaces for programmers
16 Advanced tweaks may be performed by using Scheme. If you are
17 not familiar with Scheme, you may wish to read our
18 @ref{Scheme tutorial}.
21 * LilyPond code blocks::
26 * Contexts for programmers::
27 * Callback functions::
28 * Inline Scheme code::
32 @node LilyPond code blocks
33 @section LilyPond code blocks
35 @cindex LilyPond code blocks
36 @cindex code blocks, LilyPond
37 @funindex #@{ @dots{} #@}
41 Creating music expressions in Scheme can be tedious, as they are
42 heavily nested and the resulting Scheme code is large. For some
43 simple tasks this can be avoided by using LilyPond code blocks,
44 which enable common LilyPond syntax to be used within Scheme.
46 LilyPond code blocks look like
49 #@{ @var{LilyPond code} #@}
52 Here is a trivial example:
54 @lilypond[verbatim,quote]
55 ritpp = #(define-event-function (parser location) ()
62 LilyPond code blocks can be used anywhere where you can write Scheme
63 code. The Scheme reader actually is changed for accommodating
64 LilyPond code blocks and can deal with embedded Scheme expressions
65 starting with @code{$} and@w{ }@code{#}.
67 @cindex parser (function argument)
70 The reader extracts the LilyPond code block and generates a runtime
71 call to the LilyPond @code{parser} to interpret the LilyPond code.
72 Scheme expressions embedded in the LilyPond code are evaluated in the
73 lexical environment of the LilyPond code block, so all local variables
74 and function parameters available at the point the LilyPond code block
75 is written may be accessed. Variables defined in other Scheme modules,
76 like the modules containing @code{\header} and @code{\layout} blocks,
77 are not accessible as Scheme variables, i.e. prefixed
78 with@tie{}@code{#}, but they are accessible as LilyPond variables, i.e.
79 prefixed with@tie{}@code{\}.
81 If @code{location} (see @ref{Scheme functions}) refers to a valid
82 input location (which it usually does inside of music/@/Scheme
83 functions), all music generated inside the code block has its
84 @samp{origin} set to @code{location}.
86 A LilyPond code block may contain anything that you can use on the
87 right side of an assignment. In addition, an empty LilyPond block
88 corresponds to a void music expression, and a LilyPond block
89 containing multiple music events gets turned into a sequential music
92 @node Scheme functions
93 @section Scheme functions
94 @cindex Scheme functions (LilyPond syntax)
96 @emph{Scheme functions} are Scheme procedures that can create Scheme
97 expressions from input written in LilyPond syntax. They can be called
98 in pretty much all places where using @code{#} for specifying a value in
99 Scheme syntax is allowed. While Scheme has functions of its own, this
100 chapter is concerned with @emph{syntactic} functions, functions that
101 receive arguments specified in LilyPond syntax.
104 * Scheme function definitions::
105 * Scheme function usage::
106 * Void scheme functions::
109 @node Scheme function definitions
110 @subsection Scheme function definitions
111 @funindex define-scheme-function
113 The general form for defining scheme functions is:
117 #(define-scheme-function
118 (parser location @var{arg1} @var{arg2} @dots{})
119 (@var{type1?} @var{type2?} @dots{})
126 @multitable @columnfractions .33 .66
128 @tab needs to be literally @code{parser} in order to give LilyPond code
129 blocks (@code{#@{}@dots{}@code{#@}}) access to the parser.
131 @item @code{location}
132 @tab needs to be literally @code{location} in order to provide access
133 to the input location object, which is used to provide error messages
134 with file names and line numbers.
136 @item @code{@var{argN}}
137 @tab @var{n}th argument
139 @item @code{@var{typeN?}}
140 @tab a Scheme @emph{type predicate} for which @code{@var{argN}}
141 must return @code{#t}. There is also a special form
142 @code{(@emph{predicate?} @emph{default})} for specifying optional
143 arguments. If the actual argument is missing when the function is being
144 called, the default value is substituted instead. Default values are
145 evaluated at definition time (including LilyPond code blocks!), so if
146 you need a default calculated at runtime, instead write a special value
147 you can easily recognize. If you write the predicate in parentheses but
148 don't follow it with a default value, @code{#f} is used as the default.
149 Default values are not verified with @emph{predicate?} at either
150 definition or run time: it is your responsibility to deal with the
151 values you specify. Default values that happen to be music expressions
152 are copied while setting @code{origin} to the @code{location} parameter.
154 @item @code{@var{body}}
155 @tab A sequence of Scheme forms evaluated in order, the last one being
156 used as the return value of the scheme function. It may contain
157 LilyPond code blocks enclosed in hashed braces
158 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in
159 @ref{LilyPond code blocks}. Within LilyPond code blocks, use @code{#}
160 to reference function arguments (eg., @samp{#arg1}) or to start an
161 inline Scheme expression containing function arguments (eg.,
162 @w{@samp{#(cons arg1 arg2)}}). Where normal Scheme expressions using
163 @code{#} don't do the trick, you might need to revert to immediate
164 Scheme expressions using @code{$}, for example as @samp{$music}.
166 If your function returns a music expression, it is given a useful value
171 Suitability of arguments for the predicates is determined by
172 actually calling the predicate after LilyPond has already converted them
173 into a Scheme expression. As a consequence, the argument can be
174 specified in Scheme syntax if desired (introduced with @code{#} or as
175 the result of calling a scheme function), but LilyPond will also convert
176 a number of LilyPond constructs into Scheme before actually checking the
177 predicate on them. Currently, those include music, postevents, simple
178 strings (with or without quotes), numbers, full markups and markup
179 lists, score, book, bookpart, context definition and output definition
183 ambiguities LilyPond sorts out by checking with predicate
184 functions: is @samp{-3} a fingering postevent or a negative number? Is
185 @code{"a" 4} in lyric mode a string followed by a number, or a lyric
186 event of duration @code{4}? LilyPond tries the argument
187 predicate on successive interpretations until success, with an
188 order designed to minimize inconsistent interpretations and
191 For example, a predicate accepting both music expressions and
192 pitches will consider @code{c''} to be a pitch rather than a music
193 expression. Immediately following durations or postevents will
194 change that interpretation. It's best to avoid overly
195 permissive predicates like @code{scheme?} when the application
196 rather calls for more specific argument types.
198 For a list of available predefined type predicates, see
199 @ruser{Predefined type predicates}.
204 @ruser{Predefined type predicates}.
207 @file{lily/music-scheme.cc},
211 @node Scheme function usage
212 @subsection Scheme function usage
214 Scheme functions can be called pretty much anywhere where a Scheme
215 expression starting with @code{#} can be written. You call a scheme
216 function by writing its name preceded by @code{\}, followed by its
217 arguments. Once an optional argument predicate does not match an
218 argument, LilyPond skips this and all following optional arguments,
219 replacing them with their specified default, and @q{backs up} the
220 argument that did not match to the place of the next mandatory argument.
221 Since the backed up argument needs to go somewhere, optional arguments
222 are not actually considered optional unless followed by a mandatory
225 There is one exception: if you write @code{\default} in the place of an
226 optional argument, this and all following optional arguments are skipped
227 and replaced by their default. This works even when no mandatory
228 argument follows since @code{\default} does not need to get backed up.
229 The @code{mark} and @code{key} commands make use of that trick to
230 provide their default behavior when just followed by @code{\default}.
232 Apart from places where a Scheme value is required, there are a few
233 places where @code{#} expressions are currently accepted and evaluated
234 for their side effects but otherwise ignored. Mostly those are the
235 places where an assignment would be acceptable as well.
237 Since it is a bad idea to return values that can be misinterpreted in
238 some context, you should use normal scheme functions only for those
239 cases where you always return a useful value, and use void scheme
240 functions (@pxref{Void scheme functions}) otherwise.
242 @node Void scheme functions
243 @subsection Void scheme functions
244 @funindex define-void-function
247 Sometimes a procedure is executed in order to perform an action rather
248 than return a value. Some programming languages (like C and Scheme) use
249 functions for either concept and just discard the returned value
250 (usually by allowing any expression to act as statement, ignoring the
251 result). This is clever but error-prone: most C compilers nowadays
252 offer warnings for various non-``void'' expressions being discarded.
253 For many functions executing an action, the Scheme standards declare the
254 return value to be unspecified. LilyPond's Scheme interpreter Guile has
255 a unique value @code{*unspecified*} that it usually (such when using
256 @code{set!} directly on a variable) but unfortunately not consistently
257 returns in such cases.
259 Defining a LilyPond function with @code{define-void-function} makes
260 sure that this special value (the only value satisfying the predicate
261 @code{void?}) will be returned.
265 #(define-void-function
268 (ly:set-option 'point-and-click #f))
270 \noPointAndClick % disable point and click
273 If you want to evaluate an expression only for its side-effect and
274 don't want any value it may return interpreted, you can do so by
275 prefixing it with @code{\void}:
278 \void #(hashq-set! some-table some-key some-value)
281 That way, you can be sure that LilyPond will not assign meaning to the
282 returned value regardless of where it encounters it. This will also
283 work for music functions such as @code{\displayMusic}.
285 @node Music functions
286 @section Music functions
288 @cindex music functions
290 @emph{Music functions} are Scheme procedures that can create music
291 expressions automatically, and can be used to greatly simplify the
295 * Music function definitions::
296 * Music function usage::
297 * Simple substitution functions::
298 * Intermediate substitution functions::
299 * Mathematics in functions::
300 * Functions without arguments::
301 * Void music functions::
305 @node Music function definitions
306 @subsection Music function definitions
307 @cindex defining music functions
308 @funindex define-music-function
310 The general form for defining music functions is:
314 #(define-music-function
315 (parser location @var{arg1} @var{arg2} @dots{})
316 (@var{type1?} @var{type2?} @dots{})
321 quite in analogy to @ref{Scheme function definitions}. More often than
322 not, @var{body} will be a @ref{LilyPond code blocks, LilyPond code block}.
324 For a list of available type predicates, see
325 @ruser{Predefined type predicates}.
330 @ruser{Predefined type predicates}.
333 @file{lily/music-scheme.cc},
338 @node Music function usage
339 @subsection Music function usage
340 Music functions may currently be used in several places. Depending on
341 where they are used, restrictions apply in order to be able to parse
342 them unambiguously. The result a music function returns must be
343 compatible with the context in which it is called.
347 At top level in a music expression. No restriction apply here.
350 As a post-event, explicitly started with a direction indicator (one of
351 @code{-}, @code{^}, @w{and @code{_}}).
353 In this case, you can't use an @emph{open} music expression as the last
354 argument, one that would end with a music expression able to accept
355 additional postevents.
358 As a chord constituent. The returned expression must be of
359 @code{rhythmic-event} type, most likely a @code{NoteEvent}.
363 The special rules for trailing arguments make it possible to write
364 polymorphic functions like @code{\tweak} that can be applied to
365 different constructs.
367 @node Simple substitution functions
368 @subsection Simple substitution functions
370 Simple substitution functions are music functions whose output
371 music expression is written in LilyPond format and contains
372 function arguments in the output expression. They are described
373 in @ruser{Substitution function examples}.
376 @node Intermediate substitution functions
377 @subsection Intermediate substitution functions
379 Intermediate substitution functions involve a mix of Scheme code
380 and LilyPond code in the music expression to be returned.
382 Some @code{\override} commands require an argument consisting of
383 a pair of numbers (called a @emph{cons cell} in Scheme).
385 The pair can be directly passed into the music function,
386 using a @code{pair?} variable:
390 #(define-music-function
391 (parser location beg-end)
394 \once \override Beam.positions = #beg-end
398 \manualBeam #'(3 . 6) c8 d e f
402 Alternatively, the numbers making up the pair can be
403 passed as separate arguments, and the Scheme code
404 used to create the pair can be included in the
407 @lilypond[quote,verbatim,ragged-right]
409 #(define-music-function
410 (parser location beg end)
413 \once \override Beam.positions = #(cons beg end)
417 \manualBeam #3 #6 c8 d e f
422 @cindex temporary overrides
423 @cindex overrides, temporary
424 @cindex properties, popping previous value
426 Properties are maintained conceptually using one stack per property
427 per grob per context. Music functions may need to override one or
428 several properties for the duration of the function, restoring them
429 to their previous value before exiting. However, normal overrides
430 pop and discard the top of the current property stack before
431 pushing to it, so the previous value of the property is lost when it
432 is overridden. When the previous value must be preserved, prefix the
433 @code{\override} command with @code{\temporary}, like this:
436 \temporary \override @dots{}
439 The use of @code{\temporary} causes the (usually set) @code{pop-first}
440 property in the override to be cleared, so the previous value is not
441 popped off the property stack before pushing the new value onto it.
442 When a subsequent @code{\revert} pops off the temporarily overriden
443 value, the previous value will re-emerge.
445 In other words, calling @code{\temporary \override} and @code{\revert}
446 in succession on the same property will have a net effect of zero.
447 Similarly, pairing @code{\temporary} and @code{\undo} on the same
448 music containing overrides will have a net effect of zero.
450 Here is an example of a music function which makes use of this.
451 The use of @code{\temporary} ensures the values of the
452 @code{cross-staff} and @code{style} properties are restored on exit
453 to whatever values they had when the @code{crossStaff} function was
454 called. Without @code{\temporary} the default values would have been
459 #(define-music-function (parser location notes) (ly:music?)
460 (_i "Create cross-staff stems")
462 \temporary \override Stem.cross-staff = #cross-staff-connect
463 \temporary \override Flag.style = #'no-flag
465 \revert Stem.cross-staff
471 @node Mathematics in functions
472 @subsection Mathematics in functions
474 Music functions can involve Scheme programming in
475 addition to simple substitution,
477 @lilypond[quote,verbatim,ragged-right]
479 #(define-music-function
480 (parser location mag)
483 \override Stem.length = #(* 7.0 mag)
484 \override NoteHead.font-size =
485 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
490 \revert NoteHead.font-size
495 \AltOn #1.5 c c \AltOff c2
500 This example may be rewritten to pass in music expressions,
502 @lilypond[quote,verbatim,ragged-right]
504 #(define-music-function
505 (parser location mag music)
508 \override Stem.length = #(* 7.0 mag)
509 \override NoteHead.font-size =
510 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
513 \revert NoteHead.font-size
517 c2 \withAlt #0.5 { c4 c }
518 \withAlt #1.5 { c c } c2
523 @node Functions without arguments
524 @subsection Functions without arguments
526 In most cases a function without arguments should be written
530 dolce = \markup@{ \italic \bold dolce @}
533 However, in rare cases it may be useful to create a music function
538 #(define-music-function
541 (if (eq? #t (ly:get-option 'display-bar-numbers))
542 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
546 To actually display bar numbers where this function is called,
547 invoke @command{lilypond} with
550 lilypond -d display-bar-numbers FILENAME.ly
554 @node Void music functions
555 @subsection Void music functions
557 A music function must return a music expression. If you want to
558 execute a function only for its side effect, you should use
559 @code{define-void-function}. But there may be cases where you
560 sometimes want to produce a music expression, and sometimes not (like
561 in the previous example). Returning a @code{void} music expression
562 via @code{#@{ #@}} will achieve that.
564 @node Event functions
565 @section Event functions
566 @funindex define-event-function
567 @cindex event functions
569 To use a music function in the place of an event, you need to write a
570 direction indicator before it. But sometimes, this does not quite match
571 the syntax of constructs you want to replace. For example, if you want
572 to write dynamics commands, those are usually attached without direction
573 indicator, like @code{c'\pp}. Here is a way to write arbitrary
575 @lilypond[quote,verbatim,ragged-right]
576 dyn=#(define-event-function (parser location arg) (markup?)
577 (make-dynamic-script arg))
578 \relative c' { c\dyn pfsss }
580 You could do the same using a music function, but then you always would
581 have to write a direction indicator before calling it, like
582 @code{@w{c-\dyn pfsss}}.
585 @node Markup functions
586 @section Markup functions
588 Markups are implemented as special Scheme functions which produce a
589 @code{Stencil} object given a number of arguments.
592 * Markup construction in Scheme::
593 * How markups work internally::
594 * New markup command definition::
595 * New markup list command definition::
599 @node Markup construction in Scheme
600 @subsection Markup construction in Scheme
602 @cindex defining markup commands
603 @funindex \displayScheme
605 Markup expressions are internally represented in Scheme using the
612 To see a markup expression in its Scheme form, use the
613 @code{\displayScheme} command:
619 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
620 \larger \line @{ foo bar baz @}
626 Compiling the code above will send the following to the display
634 (#:bold (#:italic "hello") #:raise 0.4 "world")
637 (#:simple "foo" #:simple "bar" #:simple "baz")))))
640 To prevent the markup from printing on the page, use
641 @w{@samp{\void \displayScheme @var{markup}}}. Also, as with the
642 @code{\displayMusic} command, the output of @code{\displayScheme}
643 can be saved to an external file. See
644 @ref{Displaying music expressions}.
647 This example demonstrates the main translation rules between regular
648 LilyPond markup syntax and Scheme markup syntax. Using @code{#@{
649 @dots{} #@}} for entering in LilyPond syntax will often be most
650 convenient, but we explain how to use the @code{markup} macro to get a
651 Scheme-only solution.
654 @multitable @columnfractions .3 .3
655 @item @b{LilyPond} @tab @b{Scheme}
656 @item @code{\markup markup1} @tab @code{(markup markup1)}
657 @item @code{\markup @{ markup1 markup2 @dots{} @}} @tab
658 @code{(markup markup1 markup2 @dots{} )}
659 @item @code{\markup-command} @tab @code{#:markup-command}
660 @item @code{\variable} @tab @code{variable}
661 @item @code{\center-column @{ @dots{} @}} @tab
662 @code{#:center-column ( @dots{} )}
663 @item @code{string} @tab @code{"string"}
664 @item @code{#scheme-arg} @tab @code{scheme-arg}
668 The whole Scheme language is accessible inside the
669 @code{markup} macro. For example, You may use function calls inside
670 @code{markup} in order to manipulate character strings. This is
671 useful when defining new markup commands (see
672 @ref{New markup command definition}).
677 The markup-list argument of commands such as @code{#:line},
678 @code{#:center}, and @code{#:column} cannot be a variable or
679 the result of a function call.
682 (markup #:line (function-that-returns-markups))
686 is invalid. One should use the @code{make-line-markup},
687 @code{make-center-markup}, or @code{make-column-markup} functions
691 (markup (make-line-markup (function-that-returns-markups)))
695 @node How markups work internally
696 @subsection How markups work internally
701 \raise #0.5 "text example"
705 @code{\raise} is actually represented by the @code{raise-markup}
706 function. The markup expression is stored as
709 (list raise-markup 0.5 (list simple-markup "text example"))
712 When the markup is converted to printable objects (Stencils), the
713 @code{raise-markup} function is called as
718 @var{list of property alists}
720 @var{the "text example" markup})
723 The @code{raise-markup} function first creates the stencil for the
724 @code{text example} string, and then it raises that Stencil by 0.5
725 staff space. This is a rather simple example; more complex examples
727 of this section, and in @file{scm/define-markup-commands.scm}.
730 @node New markup command definition
731 @subsection New markup command definition
733 This section discusses the definition of new markup commands.
736 * Markup command definition syntax::
738 * A complete example::
739 * Adapting builtin commands::
742 @node Markup command definition syntax
743 @unnumberedsubsubsec Markup command definition syntax
745 New markup commands can be defined using the
746 @code{define-markup-command} Scheme macro, at top-level.
749 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} @dots{})
750 (@var{arg1-type?} @var{arg2-type?} @dots{})
751 [ #:properties ((@var{property1} @var{default-value1})
753 @dots{}command body@dots{})
759 @item @var{command-name}
760 the markup command name
762 the @q{layout} definition.
764 a list of associative lists, containing all active properties.
766 @var{i}th command argument
767 @item @var{argi-type?}
768 a type predicate for the i@var{th} argument
771 If the command uses properties from the @code{props} arguments,
772 the @code{#:properties} keyword can be used to specify which
773 properties are used along with their default values.
775 Arguments are distinguished according to their type:
777 @item a markup, corresponding to type predicate @code{markup?};
778 @item a list of markups, corresponding to type predicate
780 @item any other scheme object, corresponding to type predicates such as
781 @code{list?}, @code{number?}, @code{boolean?}, etc.
784 There is no limitation on the order of arguments (after the
785 standard @code{layout} and @code{props} arguments). However,
786 markup functions taking a markup as their last argument are
787 somewhat special as you can apply them to a markup list, and the
788 result is a markup list where the markup function (with the
789 specified leading arguments) has been applied to every element of
790 the original markup list.
792 Since replicating the leading arguments for applying a markup
793 function to a markup list is cheap mostly for Scheme arguments,
794 you avoid performance pitfalls by just using Scheme arguments for
795 the leading arguments of markup functions that take a markup as
800 @funindex interpret-markup
801 Markup commands have a rather complex life cycle. The body of a
802 markup command definition is responsible for converting the
803 arguments of the markup command into a stencil expression which is
804 returned. Quite often this is accomplished by calling the
805 @code{interpret-markup} function on a markup expression, passing
806 the @var{layout} and @var{props} arguments on to it. Those
807 arguments are usually only known at a very late stage in
808 typesetting. Markup expressions have their components assembled
809 into markup expressions already when @code{\markup} in a LilyPond
810 expression or the @code{markup} macro in Scheme is expanded. The
811 evaluation and typechecking of markup command arguments happens at
812 the time @code{\markup}/@code{markup} are interpreted.
814 But the actual conversion of markup expressions into stencil
815 expressions by executing the markup function bodies only happens
816 when @code{interpret-markup} is called on a markup expression.
819 @unnumberedsubsubsec On properties
821 The @code{layout} and @code{props} arguments of markup commands bring a
822 context for the markup interpretation: font size, line width, etc.
824 The @code{layout} argument allows access to properties defined in
825 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
826 For instance, the line width (the same as the one used in scores) is
830 (ly:output-def-lookup layout 'line-width)
833 The @code{props} argument makes some properties accessible to markup
834 commands. For instance, when a book title markup is interpreted, all
835 the variables defined in the @code{\header} block are automatically
836 added to @code{props}, so that the book title markup can access the book
837 title, composer, etc. It is also a way to configure the behaviour of a
838 markup command: for example, when a command uses font size during
839 processing, the font size is read from @code{props} rather than having a
840 @code{font-size} argument. The caller of a markup command may change
841 the value of the font size property in order to change the behaviour.
842 Use the @code{#:properties} keyword of @code{define-markup-command} to
843 specify which properties shall be read from the @code{props} arguments.
845 The example in next section illustrates how to access and override
846 properties in a markup command.
848 @node A complete example
849 @unnumberedsubsubsec A complete example
851 The following example defines a markup command to draw a double box
852 around a piece of text.
854 Firstly, we need to build an approximative result using markups.
855 Consulting the @ruser{Text markup commands} shows us the @code{\box}
858 @lilypond[quote,verbatim,ragged-right]
859 \markup \box \box HELLO
862 Now, we consider that more padding between the text and the boxes is
863 preferable. According to the @code{\box} documentation, this command
864 uses a @code{box-padding} property, which defaults to 0.2. The
865 documentation also mentions how to override it:
867 @lilypond[quote,verbatim,ragged-right]
868 \markup \box \override #'(box-padding . 0.6) \box A
871 Then, the padding between the two boxes is considered too small, so we
874 @lilypond[quote,verbatim,ragged-right]
875 \markup \override #'(box-padding . 0.4) \box
876 \override #'(box-padding . 0.6) \box A
879 Repeating this lengthy markup would be painful. This is where a markup
880 command is needed. Thus, we write a @code{double-box} markup command,
881 taking one argument (the text). This draws the two boxes, with some
885 #(define-markup-command (double-box layout props text) (markup?)
886 "Draw a double box around text."
887 (interpret-markup layout props
888 #@{\markup \override #'(box-padding . 0.4) \box
889 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
895 #(define-markup-command (double-box layout props text) (markup?)
896 "Draw a double box around text."
897 (interpret-markup layout props
898 (markup #:override '(box-padding . 0.4) #:box
899 #:override '(box-padding . 0.6) #:box text)))
902 @code{text} is the name of the command argument, and @code{markup?} its
903 type: it identifies it as a markup. The @code{interpret-markup}
904 function is used in most of markup commands: it builds a stencil, using
905 @code{layout}, @code{props}, and a markup. In the second case, this
906 markup is built using the @code{markup} scheme macro, see @ref{Markup
907 construction in Scheme}. The transformation from @code{\markup}
908 expression to scheme markup expression is straight-forward.
910 The new command can be used as follow:
913 \markup \double-box A
916 It would be nice to make the @code{double-box} command customizable:
917 here, the @code{box-padding} values are hard coded, and cannot be
918 changed by the user. Also, it would be better to distinguish the
919 padding between the two boxes, from the padding between the inner box
920 and the text. So we will introduce a new property,
921 @code{inter-box-padding}, for the padding between the two boxes. The
922 @code{box-padding} will be used for the inner padding. The new code is
926 #(define-markup-command (double-box layout props text) (markup?)
927 #:properties ((inter-box-padding 0.4)
929 "Draw a double box around text."
930 (interpret-markup layout props
931 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
932 \override #`(box-padding . ,box-padding) \box
936 Again, the equivalent version using the markup macro would be:
939 #(define-markup-command (double-box layout props text) (markup?)
940 #:properties ((inter-box-padding 0.4)
942 "Draw a double box around text."
943 (interpret-markup layout props
944 (markup #:override `(box-padding . ,inter-box-padding) #:box
945 #:override `(box-padding . ,box-padding) #:box text)))
948 Here, the @code{#:properties} keyword is used so that the
949 @code{inter-box-padding} and @code{box-padding} properties are read from
950 the @code{props} argument, and default values are given to them if the
951 properties are not defined.
953 Then, these values are used to override the @code{box-padding}
954 properties used by the two @code{\box} commands. Note the backquote and
955 the comma in the @code{\override} argument: they allow you to introduce
956 a variable value into a literal expression.
958 Now, the command can be used in a markup, and the boxes padding be
961 @lilypond[quote,verbatim,ragged-right]
962 #(define-markup-command (double-box layout props text) (markup?)
963 #:properties ((inter-box-padding 0.4)
965 "Draw a double box around text."
966 (interpret-markup layout props
967 #{\markup \override #`(box-padding . ,inter-box-padding) \box
968 \override #`(box-padding . ,box-padding) \box
971 \markup \double-box A
972 \markup \override #'(inter-box-padding . 0.8) \double-box A
973 \markup \override #'(box-padding . 1.0) \double-box A
976 @node Adapting builtin commands
977 @unnumberedsubsubsec Adapting builtin commands
979 A good way to start writing a new markup command, is to take example on
980 a builtin one. Most of the markup commands provided with LilyPond can be
981 found in file @file{scm/define-markup-commands.scm}.
983 For instance, we would like to adapt the @code{\draw-line} command, to
984 draw a double line instead. The @code{\draw-line} command is defined as
985 follow (documentation stripped):
988 (define-markup-command (draw-line layout props dest)
991 #:properties ((thickness 1))
992 "@dots{}documentation@dots{}"
993 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
997 (make-line-stencil th 0 0 x y)))
1000 To define a new command based on an existing one, copy the definition,
1001 and change the command name. The @code{#:category} keyword can be
1002 safely removed, as it is only used for generating LilyPond
1003 documentation, and is of no use for user-defined markup commands.
1006 (define-markup-command (draw-double-line layout props dest)
1008 #:properties ((thickness 1))
1009 "@dots{}documentation@dots{}"
1010 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1014 (make-line-stencil th 0 0 x y)))
1017 Then, a property for setting the gap between two lines is added, called
1018 @code{line-gap}, defaulting e.g. to 0.6:
1021 (define-markup-command (draw-double-line layout props dest)
1023 #:properties ((thickness 1)
1025 "@dots{}documentation@dots{}"
1029 Finally, the code for drawing two lines is added. Two calls to
1030 @code{make-line-stencil} are used to draw the lines, and the resulting
1031 stencils are combined using @code{ly:stencil-add}:
1033 @lilypond[quote,verbatim,ragged-right]
1034 #(define-markup-command (my-draw-line layout props dest)
1036 #:properties ((thickness 1)
1039 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1043 (w (/ line-gap 2.0))
1044 (x (cond ((= dx 0) w)
1046 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1047 (y (* (if (< (* dx dy) 0) 1 -1)
1050 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1051 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1052 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1054 \markup \my-draw-line #'(4 . 3)
1055 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1059 @node New markup list command definition
1060 @subsection New markup list command definition
1061 @funindex define-markup-list-command
1062 @funindex interpret-markup-list
1063 Markup list commands are defined with the
1064 @code{define-markup-list-command} Scheme macro, which is similar to the
1065 @code{define-markup-command} macro described in
1066 @ref{New markup command definition}, except that where the latter returns
1067 a single stencil, the former returns a list of stencils.
1069 In a similar vein, @code{interpret-markup-list} is used instead of
1070 @code{interpret-markup} for converting a markup list into a list
1073 In the following example, a @code{\paragraph} markup list command is
1074 defined, which returns a list of justified lines, the first one being
1075 indented. The indent width is taken from the @code{props} argument.
1078 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1079 #:properties ((par-indent 2))
1080 (interpret-markup-list layout props
1081 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1085 The version using just Scheme is more complex:
1087 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1088 #:properties ((par-indent 2))
1089 (interpret-markup-list layout props
1090 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1094 Besides the usual @code{layout} and @code{props} arguments, the
1095 @code{paragraph} markup list command takes a markup list argument, named
1096 @code{args}. The predicate for markup lists is @code{markup-list?}.
1098 First, the function gets the indent width, a property here named
1099 @code{par-indent}, from the property list @code{props}. If the
1100 property is not found, the default value is @code{2}. Then, a
1101 list of justified lines is made using the built-in markup list command
1102 @code{\justified-lines}, which is related to the
1103 @code{make-justified-lines-markup-list} function. A
1104 horizontal space is added at the beginning using @code{\hspace} (or the
1105 @code{make-hspace-markup} function). Finally, the markup list is
1106 interpreted using the @code{interpret-markup-list} function.
1108 This new markup list command can be used as follows:
1112 The art of music typography is called \italic @{(plate) engraving.@}
1113 The term derives from the traditional process of music printing.
1114 Just a few decades ago, sheet music was made by cutting and stamping
1115 the music into a zinc or pewter plate in mirror image.
1117 \override-lines #'(par-indent . 4) \paragraph @{
1118 The plate would be inked, the depressions caused by the cutting
1119 and stamping would hold ink. An image was formed by pressing paper
1120 to the plate. The stamping and cutting was completely done by
1126 @node Contexts for programmers
1127 @section Contexts for programmers
1130 * Context evaluation::
1131 * Running a function on all layout objects::
1134 @node Context evaluation
1135 @subsection Context evaluation
1137 @cindex calling code during interpreting
1138 @funindex \applyContext
1140 Contexts can be modified during interpretation with Scheme code. The
1143 \applyContext @var{function}
1146 @code{@var{function}} should be a Scheme function that takes a
1147 single argument: the context in which the @code{\applyContext}
1148 command is being called. The following code will print the
1149 current bar number on the standard output during the compile:
1154 (format #t "\nWe were called in barnumber ~a.\n"
1155 (ly:context-property x 'currentBarNumber)))
1160 @node Running a function on all layout objects
1161 @subsection Running a function on all layout objects
1164 @cindex calling code on layout objects
1165 @funindex \applyOutput
1167 The most versatile way of tuning an object is @code{\applyOutput} which
1168 works by inserting an event into the specified context
1169 (@rinternals{ApplyOutputEvent}). Its syntax is
1171 \applyOutput @var{Context} @var{proc}
1175 where @code{@var{proc}} is a Scheme function, taking three arguments.
1177 When interpreted, the function @code{@var{proc}} is called for
1178 every layout object found in the context @code{@var{Context}} at
1179 the current time step, with the following arguments:
1181 @item the layout object itself,
1182 @item the context where the layout object was created, and
1183 @item the context where @code{\applyOutput} is processed.
1187 In addition, the cause of the layout object, i.e., the music
1188 expression or object that was responsible for creating it, is in the
1189 object property @code{cause}. For example, for a note head, this is a
1190 @rinternals{NoteHead} event, and for a stem object,
1191 this is a @rinternals{Stem} object.
1193 Here is a function to use for @code{\applyOutput}; it blanks
1194 note-heads on the center-line and next to it:
1196 @lilypond[quote,verbatim,ragged-right]
1197 #(define (blanker grob grob-origin context)
1198 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1199 (< (abs (ly:grob-property grob 'staff-position)) 2))
1200 (set! (ly:grob-property grob 'transparent) #t)))
1203 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1207 To have @var{function} interpreted at the @code{Score} or @code{Staff}
1208 level use these forms
1211 \applyOutput #'Score #@var{function}
1212 \applyOutput #'Staff #@var{function}
1216 @node Callback functions
1217 @section Callback functions
1219 Properties (like @code{thickness}, @code{direction}, etc.) can be
1220 set at fixed values with @code{\override}, e.g.
1223 \override Stem.thickness = #2.0
1226 Properties can also be set to a Scheme procedure,
1228 @lilypond[fragment,verbatim,quote,relative=2]
1229 \override Stem.thickness = #(lambda (grob)
1230 (if (= UP (ly:grob-property grob 'direction))
1237 In this case, the procedure is executed as soon as the value of the
1238 property is requested during the formatting process.
1240 Most of the typesetting engine is driven by such callbacks.
1241 Properties that typically use callbacks include
1245 The printing routine, that constructs a drawing for the symbol
1247 The routine that sets the horizontal position
1249 The routine that computes the width of an object
1252 The procedure always takes a single argument, being the grob.
1254 If routines with multiple arguments must be called, the current grob
1255 can be inserted with a grob closure. Here is a setting from
1256 @code{AccidentalSuggestion},
1260 ,(ly:make-simple-closure
1262 ,(ly:make-simple-closure
1263 (list ly:self-alignment-interface::centered-on-x-parent))
1264 ,(ly:make-simple-closure
1265 (list ly:self-alignment-interface::x-aligned-on-self)))))
1269 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1270 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1271 with the grob as argument. The results are added with the @code{+}
1272 function. To ensure that this addition is properly executed, the whole
1273 thing is enclosed in @code{ly:make-simple-closure}.
1275 In fact, using a single procedure as property value is equivalent to
1278 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1282 The inner @code{ly:make-simple-closure} supplies the grob as argument
1283 to @var{proc}, the outer ensures that result of the function is
1284 returned, rather than the @code{simple-closure} object.
1286 From within a callback, the easiest method for evaluating a markup is
1287 to use grob-interpret-markup. For example:
1290 my-callback = #(lambda (grob)
1291 (grob-interpret-markup grob (markup "foo")))
1294 @node Inline Scheme code
1295 @section Inline Scheme code
1297 TODO: after this section had been written, LilyPond has improved
1298 to the point that finding a @emph{simple} example where one would
1299 @emph{have} to revert to Scheme has become rather hard.
1301 Until this section gets a rewrite, let's pretend we don't know.
1303 The main disadvantage of @code{\tweak} is its syntactical
1304 inflexibility. For example, the following produces a syntax error
1305 (or rather, it did so at some point in the past).
1308 F = \tweak font-size #-3 -\flageolet
1316 Using Scheme, this problem can be avoided. The route to the
1317 result is given in @ref{Adding articulation to notes (example)},
1318 especially how to use @code{\displayMusic} as a helping guide.
1321 F = #(let ((m (make-music 'ArticulationEvent
1322 'articulation-type "flageolet")))
1323 (set! (ly:music-property m 'tweaks)
1324 (acons 'font-size -3
1325 (ly:music-property m 'tweaks)))
1334 Here, the @code{tweaks} properties of the flageolet object
1335 @code{m} (created with @code{make-music}) are extracted with
1336 @code{ly:music-property}, a new key-value pair to change the
1337 font size is prepended to the property list with the
1338 @code{acons} Scheme function, and the result is finally
1339 written back with @code{set!}. The last element of the
1340 @code{let} block is the return value, @code{m} itself.
1344 @node Difficult tweaks
1345 @section Difficult tweaks
1347 There are a few classes of difficult adjustments.
1353 One type of difficult adjustment involves the appearance of
1354 spanner objects, such as slurs and ties. Usually, only one
1355 spanner object is created at a time, and it can be adjusted with
1356 the normal mechanism. However, occasionally a spanner crosses a
1357 line break. When this happens, the object is cloned. A separate
1358 object is created for every system in which the spanner appears.
1359 The new objects are clones of the original object and inherit all
1360 properties, including @code{\override}s.
1363 In other words, an @code{\override} always affects all pieces of a
1364 broken spanner. To change only one part of a spanner at a line break,
1365 it is necessary to hook into the formatting process. The
1366 @code{after-line-breaking} callback contains the Scheme procedure that
1367 is called after the line breaks have been determined and layout
1368 objects have been split over different systems.
1370 In the following example, we define a procedure
1371 @code{my-callback}. This procedure
1375 determines if the spanner has been split across line breaks
1377 if yes, retrieves all the split objects
1379 checks if this grob is the last of the split objects
1381 if yes, it sets @code{extra-offset}.
1384 This procedure is installed into @rinternals{Tie}, so the last part
1385 of the broken tie is repositioned.
1387 @lilypond[quote,verbatim,ragged-right]
1388 #(define (my-callback grob)
1390 ;; have we been split?
1391 (orig (ly:grob-original grob))
1393 ;; if yes, get the split pieces (our siblings)
1394 (siblings (if (ly:grob? orig)
1395 (ly:spanner-broken-into orig)
1398 (if (and (>= (length siblings) 2)
1399 (eq? (car (last-pair siblings)) grob))
1400 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1403 \override Tie.after-line-breaking =
1411 When applying this trick, the new @code{after-line-breaking} callback
1412 should also call the old one, if such a default exists. For example,
1413 if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
1414 should also be called.
1418 Some objects cannot be changed with @code{\override} for
1419 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1420 and @code{PaperColumn}. They can be changed with the
1421 @code{\overrideProperty} function, which works similar to @code{\once
1422 \override}, but uses a different syntax.
1426 Score.NonMusicalPaperColumn % Grob name
1427 . line-break-system-details % Property name
1428 . next-padding % Optional subproperty name
1432 Note, however, that @code{\override}, applied to
1433 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1434 expected within @code{\context} blocks.
1438 @node LilyPond Scheme interfaces
1439 @chapter LilyPond Scheme interfaces
1441 This chapter covers the various tools provided by LilyPond to help
1442 Scheme programmers get information into and out of the music streams.
1444 TODO -- figure out what goes in here and how to organize it