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::
31 @node LilyPond code blocks
32 @section LilyPond code blocks
34 @cindex LilyPond code blocks
35 @cindex code blocks, LilyPond
36 @funindex #@{ @dots{} #@}
40 Creating music expressions in Scheme can be tedious, as they are
41 heavily nested and the resulting Scheme code is large. For some
42 simple tasks this can be avoided by using LilyPond code blocks,
43 which enable common LilyPond syntax to be used within Scheme.
45 LilyPond code blocks look like
48 #@{ @var{LilyPond code} #@}
51 Here is a trivial example:
53 @lilypond[verbatim,quote]
54 ritpp = #(define-event-function (parser location) ()
61 LilyPond code blocks can be used anywhere where you can write Scheme
62 code. The Scheme reader actually is changed for accommodating
63 LilyPond code blocks and can deal with embedded Scheme expressions
64 starting with @code{$} and@w{ }@code{#}.
66 @cindex parser (function argument)
69 The reader extracts the LilyPond code block and generates a runtime
70 call to the LilyPond @code{parser} to interpret the LilyPond code.
71 Scheme expressions embedded in the LilyPond code are evaluated in the
72 lexical environment of the LilyPond code block, so all local variables
73 and function parameters available at the point the LilyPond code block
74 is written may be accessed. Variables defined in other Scheme modules,
75 like the modules containing @code{\header} and @code{\layout} blocks,
76 are not accessible as Scheme variables, i.e. prefixed
77 with@tie{}@code{#}, but they are accessible as LilyPond variables, i.e.
78 prefixed with@tie{}@code{\}.
80 If @code{location} (see @ref{Scheme functions}) refers to a valid
81 input location (which it usually does inside of music/@/Scheme
82 functions), all music generated inside the code block has its
83 @samp{origin} set to @code{location}.
85 A LilyPond code block may contain anything that you can use on the
86 right side of an assignment. In addition, an empty LilyPond block
87 corresponds to a void music expression, and a LilyPond block
88 containing multiple music events gets turned into a sequential music
91 @node Scheme functions
92 @section Scheme functions
93 @cindex Scheme functions (LilyPond syntax)
95 @emph{Scheme functions} are Scheme procedures that can create Scheme
96 expressions from input written in LilyPond syntax. They can be called
97 in pretty much all places where using @code{#} for specifying a value in
98 Scheme syntax is allowed. While Scheme has functions of its own, this
99 chapter is concerned with @emph{syntactic} functions, functions that
100 receive arguments specified in LilyPond syntax.
103 * Scheme function definitions::
104 * Scheme function usage::
105 * Void scheme functions::
108 @node Scheme function definitions
109 @subsection Scheme function definitions
110 @funindex define-scheme-function
112 The general form for defining scheme functions is:
116 #(define-scheme-function
117 (parser location @var{arg1} @var{arg2} @dots{})
118 (@var{type1?} @var{type2?} @dots{})
125 @multitable @columnfractions .33 .66
127 @tab needs to be literally @code{parser} in order to give LilyPond code
128 blocks (@code{#@{}@dots{}@code{#@}}) access to the parser.
130 @item @code{location}
131 @tab needs to be literally @code{location} in order to provide access
132 to the input location object, which is used to provide error messages
133 with file names and line numbers.
135 @item @code{@var{argN}}
136 @tab @var{n}th argument
138 @item @code{@var{typeN?}}
139 @tab a Scheme @emph{type predicate} for which @code{@var{argN}}
140 must return @code{#t}. There is also a special form
141 @code{(@emph{predicate?} @emph{default})} for specifying optional
142 arguments. If the actual argument is missing when the function is being
143 called, the default value is substituted instead. Default values are
144 evaluated at definition time (including LilyPond code blocks!), so if
145 you need a default calculated at runtime, instead write a special value
146 you can easily recognize. If you write the predicate in parentheses but
147 don't follow it with a default value, @code{#f} is used as the default.
148 Default values are not verified with @emph{predicate?} at either
149 definition or run time: it is your responsibility to deal with the
150 values you specify. Default values that happen to be music expressions
151 are copied while setting @code{origin} to the @code{location} parameter.
153 @item @code{@var{body}}
154 @tab A sequence of Scheme forms evaluated in order, the last one being
155 used as the return value of the scheme function. It may contain
156 LilyPond code blocks enclosed in hashed braces
157 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in
158 @ref{LilyPond code blocks}. Within LilyPond code blocks, use @code{#}
159 to reference function arguments (eg., @samp{#arg1}) or to start an
160 inline Scheme expression containing function arguments (eg.,
161 @w{@samp{#(cons arg1 arg2)}}). Where normal Scheme expressions using
162 @code{#} don't do the trick, you might need to revert to immediate
163 Scheme expressions using @code{$}, for example as @samp{$music}.
165 If your function returns a music expression, it is given a useful value
170 Suitability of arguments for the predicates is determined by
171 actually calling the predicate after LilyPond has already converted them
172 into a Scheme expression. As a consequence, the argument can be
173 specified in Scheme syntax if desired (introduced with @code{#} or as
174 the result of calling a scheme function), but LilyPond will also convert
175 a number of LilyPond constructs into Scheme before actually checking the
176 predicate on them. Currently, those include music, postevents, simple
177 strings (with or without quotes), numbers, full markups and markup
178 lists, score, book, bookpart, context definition and output definition
182 ambiguities LilyPond sorts out by checking with predicate
183 functions: is @samp{-3} a fingering postevent or a negative number? Is
184 @code{"a" 4} in lyric mode a string followed by a number, or a lyric
185 event of duration @code{4}? LilyPond tries the argument
186 predicate on successive interpretations until success, with an
187 order designed to minimize inconsistent interpretations and
190 For example, a predicate accepting both music expressions and
191 pitches will consider @code{c''} to be a pitch rather than a music
192 expression. Immediately following durations or postevents will
193 change that interpretation. It's best to avoid overly
194 permissive predicates like @code{scheme?} when the application
195 rather calls for more specific argument types.
197 For a list of available predefined type predicates, see
198 @ruser{Predefined type predicates}.
203 @ruser{Predefined type predicates}.
206 @file{lily/music-scheme.cc},
210 @node Scheme function usage
211 @subsection Scheme function usage
213 Scheme functions can be called pretty much anywhere where a Scheme
214 expression starting with @code{#} can be written. You call a scheme
215 function by writing its name preceded by @code{\}, followed by its
216 arguments. Once an optional argument predicate does not match an
217 argument, LilyPond skips this and all following optional arguments,
218 replacing them with their specified default, and @q{backs up} the
219 argument that did not match to the place of the next mandatory argument.
220 Since the backed up argument needs to go somewhere, optional arguments
221 are not actually considered optional unless followed by a mandatory
224 There is one exception: if you write @code{\default} in the place of an
225 optional argument, this and all following optional arguments are skipped
226 and replaced by their default. This works even when no mandatory
227 argument follows since @code{\default} does not need to get backed up.
228 The @code{mark} and @code{key} commands make use of that trick to
229 provide their default behavior when just followed by @code{\default}.
231 Apart from places where a Scheme value is required, there are a few
232 places where @code{#} expressions are currently accepted and evaluated
233 for their side effects but otherwise ignored. Mostly those are the
234 places where an assignment would be acceptable as well.
236 Since it is a bad idea to return values that can be misinterpreted in
237 some context, you should use normal scheme functions only for those
238 cases where you always return a useful value, and use void scheme
239 functions (@pxref{Void scheme functions}) otherwise.
241 @node Void scheme functions
242 @subsection Void scheme functions
243 @funindex define-void-function
246 Sometimes a procedure is executed in order to perform an action rather
247 than return a value. Some programming languages (like C and Scheme) use
248 functions for either concept and just discard the returned value
249 (usually by allowing any expression to act as statement, ignoring the
250 result). This is clever but error-prone: most C compilers nowadays
251 offer warnings for various non-``void'' expressions being discarded.
252 For many functions executing an action, the Scheme standards declare the
253 return value to be unspecified. LilyPond's Scheme interpreter Guile has
254 a unique value @code{*unspecified*} that it usually (such when using
255 @code{set!} directly on a variable) but unfortunately not consistently
256 returns in such cases.
258 Defining a LilyPond function with @code{define-void-function} makes
259 sure that this special value (the only value satisfying the predicate
260 @code{void?}) will be returned.
264 #(define-void-function
267 (ly:set-option 'point-and-click #f))
269 \noPointAndClick % disable point and click
272 If you want to evaluate an expression only for its side-effect and
273 don't want any value it may return interpreted, you can do so by
274 prefixing it with @code{\void}:
277 \void #(hashq-set! some-table some-key some-value)
280 That way, you can be sure that LilyPond will not assign meaning to the
281 returned value regardless of where it encounters it. This will also
282 work for music functions such as @code{\displayMusic}.
284 @node Music functions
285 @section Music functions
287 @cindex music functions
289 @emph{Music functions} are Scheme procedures that can create music
290 expressions automatically, and can be used to greatly simplify the
294 * Music function definitions::
295 * Music function usage::
296 * Simple substitution functions::
297 * Intermediate substitution functions::
298 * Mathematics in functions::
299 * Functions without arguments::
300 * Void music functions::
304 @node Music function definitions
305 @subsection Music function definitions
306 @cindex defining music functions
307 @funindex define-music-function
309 The general form for defining music functions is:
313 #(define-music-function
314 (parser location @var{arg1} @var{arg2} @dots{})
315 (@var{type1?} @var{type2?} @dots{})
320 quite in analogy to @ref{Scheme function definitions}. More often than
321 not, @var{body} will be a @ref{LilyPond code blocks, LilyPond code block}.
323 For a list of available type predicates, see
324 @ruser{Predefined type predicates}.
329 @ruser{Predefined type predicates}.
332 @file{lily/music-scheme.cc},
337 @node Music function usage
338 @subsection Music function usage
339 Music functions may currently be used in several places. Depending on
340 where they are used, restrictions apply in order to be able to parse
341 them unambiguously. The result a music function returns must be
342 compatible with the context in which it is called.
346 At top level in a music expression. No restriction apply here.
349 As a post-event, explicitly started with a direction indicator (one of
350 @code{-}, @code{^}, @w{and @code{_}}).
352 In this case, you can't use an @emph{open} music expression as the last
353 argument, one that would end with a music expression able to accept
354 additional postevents.
357 As a chord constituent. The returned expression must be of
358 @code{rhythmic-event} type, most likely a @code{NoteEvent}.
362 The special rules for trailing arguments make it possible to write
363 polymorphic functions like @code{\tweak} that can be applied to
364 different constructs.
366 @node Simple substitution functions
367 @subsection Simple substitution functions
369 Simple substitution functions are music functions whose output
370 music expression is written in LilyPond format and contains
371 function arguments in the output expression. They are described
372 in @ruser{Substitution function examples}.
375 @node Intermediate substitution functions
376 @subsection Intermediate substitution functions
378 Intermediate substitution functions involve a mix of Scheme code
379 and LilyPond code in the music expression to be returned.
381 Some @code{\override} commands require an argument consisting of
382 a pair of numbers (called a @emph{cons cell} in Scheme).
384 The pair can be directly passed into the music function,
385 using a @code{pair?} variable:
389 #(define-music-function
390 (parser location beg-end)
393 \once \override Beam.positions = #beg-end
397 \manualBeam #'(3 . 6) c8 d e f
401 Alternatively, the numbers making up the pair can be
402 passed as separate arguments, and the Scheme code
403 used to create the pair can be included in the
406 @lilypond[quote,verbatim,ragged-right]
408 #(define-music-function
409 (parser location beg end)
412 \once \override Beam.positions = #(cons beg end)
416 \manualBeam #3 #6 c8 d e f
421 @cindex temporary overrides
422 @cindex overrides, temporary
423 @cindex properties, popping previous value
425 Properties are maintained conceptually using one stack per property
426 per grob per context. Music functions may need to override one or
427 several properties for the duration of the function, restoring them
428 to their previous value before exiting. However, normal overrides
429 pop and discard the top of the current property stack before
430 pushing to it, so the previous value of the property is lost when it
431 is overridden. When the previous value must be preserved, prefix the
432 @code{\override} command with @code{\temporary}, like this:
435 \temporary \override @dots{}
438 The use of @code{\temporary} causes the (usually set) @code{pop-first}
439 property in the override to be cleared, so the previous value is not
440 popped off the property stack before pushing the new value onto it.
441 When a subsequent @code{\revert} pops off the temporarily overriden
442 value, the previous value will re-emerge.
444 In other words, calling @code{\temporary \override} and @code{\revert}
445 in succession on the same property will have a net effect of zero.
446 Similarly, pairing @code{\temporary} and @code{\undo} on the same
447 music containing overrides will have a net effect of zero.
449 Here is an example of a music function which makes use of this.
450 The use of @code{\temporary} ensures the values of the
451 @code{cross-staff} and @code{style} properties are restored on exit
452 to whatever values they had when the @code{crossStaff} function was
453 called. Without @code{\temporary} the default values would have been
458 #(define-music-function (parser location notes) (ly:music?)
459 (_i "Create cross-staff stems")
461 \temporary \override Stem.cross-staff = #cross-staff-connect
462 \temporary \override Flag.style = #'no-flag
464 \revert Stem.cross-staff
470 @node Mathematics in functions
471 @subsection Mathematics in functions
473 Music functions can involve Scheme programming in
474 addition to simple substitution,
476 @lilypond[quote,verbatim,ragged-right]
478 #(define-music-function
479 (parser location mag)
482 \override Stem.length = #(* 7.0 mag)
483 \override NoteHead.font-size =
484 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
489 \revert NoteHead.font-size
494 \AltOn #1.5 c c \AltOff c2
499 This example may be rewritten to pass in music expressions,
501 @lilypond[quote,verbatim,ragged-right]
503 #(define-music-function
504 (parser location mag music)
507 \override Stem.length = #(* 7.0 mag)
508 \override NoteHead.font-size =
509 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
512 \revert NoteHead.font-size
516 c2 \withAlt #0.5 { c4 c }
517 \withAlt #1.5 { c c } c2
522 @node Functions without arguments
523 @subsection Functions without arguments
525 In most cases a function without arguments should be written
529 dolce = \markup@{ \italic \bold dolce @}
532 However, in rare cases it may be useful to create a music function
537 #(define-music-function
540 (if (eq? #t (ly:get-option 'display-bar-numbers))
541 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
545 To actually display bar numbers where this function is called,
546 invoke @command{lilypond} with
549 lilypond -d display-bar-numbers FILENAME.ly
553 @node Void music functions
554 @subsection Void music functions
556 A music function must return a music expression. If you want to
557 execute a function only for its side effect, you should use
558 @code{define-void-function}. But there may be cases where you
559 sometimes want to produce a music expression, and sometimes not (like
560 in the previous example). Returning a @code{void} music expression
561 via @code{#@{ #@}} will achieve that.
563 @node Event functions
564 @section Event functions
565 @funindex define-event-function
566 @cindex event functions
568 To use a music function in the place of an event, you need to write a
569 direction indicator before it. But sometimes, this does not quite match
570 the syntax of constructs you want to replace. For example, if you want
571 to write dynamics commands, those are usually attached without direction
572 indicator, like @code{c'\pp}. Here is a way to write arbitrary
574 @lilypond[quote,verbatim,ragged-right]
575 dyn=#(define-event-function (parser location arg) (markup?)
576 (make-dynamic-script arg))
577 \relative c' { c\dyn pfsss }
579 You could do the same using a music function, but then you always would
580 have to write a direction indicator before calling it, like
581 @code{@w{c-\dyn pfsss}}.
584 @node Markup functions
585 @section Markup functions
587 Markups are implemented as special Scheme functions which produce a
588 @code{Stencil} object given a number of arguments.
591 * Markup construction in Scheme::
592 * How markups work internally::
593 * New markup command definition::
594 * New markup list command definition::
598 @node Markup construction in Scheme
599 @subsection Markup construction in Scheme
601 @cindex defining markup commands
602 @funindex \displayScheme
604 Markup expressions are internally represented in Scheme using the
611 To see a markup expression in its Scheme form, use the
612 @code{\displayScheme} command:
618 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
619 \larger \line @{ foo bar baz @}
625 Compiling the code above will send the following to the display
633 (#:bold (#:italic "hello") #:raise 0.4 "world")
636 (#:simple "foo" #:simple "bar" #:simple "baz")))))
639 To prevent the markup from printing on the page, use
640 @w{@samp{\void \displayScheme @var{markup}}}. Also, as with the
641 @code{\displayMusic} command, the output of @code{\displayScheme}
642 can be saved to an external file. See
643 @ref{Displaying music expressions}.
646 This example demonstrates the main translation rules between regular
647 LilyPond markup syntax and Scheme markup syntax. Using @code{#@{
648 @dots{} #@}} for entering in LilyPond syntax will often be most
649 convenient, but we explain how to use the @code{markup} macro to get a
650 Scheme-only solution.
653 @multitable @columnfractions .3 .3
654 @item @b{LilyPond} @tab @b{Scheme}
655 @item @code{\markup markup1} @tab @code{(markup markup1)}
656 @item @code{\markup @{ markup1 markup2 @dots{} @}} @tab
657 @code{(markup markup1 markup2 @dots{} )}
658 @item @code{\markup-command} @tab @code{#:markup-command}
659 @item @code{\variable} @tab @code{variable}
660 @item @code{\center-column @{ @dots{} @}} @tab
661 @code{#:center-column ( @dots{} )}
662 @item @code{string} @tab @code{"string"}
663 @item @code{#scheme-arg} @tab @code{scheme-arg}
667 The whole Scheme language is accessible inside the
668 @code{markup} macro. For example, You may use function calls inside
669 @code{markup} in order to manipulate character strings. This is
670 useful when defining new markup commands (see
671 @ref{New markup command definition}).
676 The markup-list argument of commands such as @code{#:line},
677 @code{#:center}, and @code{#:column} cannot be a variable or
678 the result of a function call.
681 (markup #:line (function-that-returns-markups))
685 is invalid. One should use the @code{make-line-markup},
686 @code{make-center-markup}, or @code{make-column-markup} functions
690 (markup (make-line-markup (function-that-returns-markups)))
694 @node How markups work internally
695 @subsection How markups work internally
700 \raise #0.5 "text example"
704 @code{\raise} is actually represented by the @code{raise-markup}
705 function. The markup expression is stored as
708 (list raise-markup 0.5 (list simple-markup "text example"))
711 When the markup is converted to printable objects (Stencils), the
712 @code{raise-markup} function is called as
717 @var{list of property alists}
719 @var{the "text example" markup})
722 The @code{raise-markup} function first creates the stencil for the
723 @code{text example} string, and then it raises that Stencil by 0.5
724 staff space. This is a rather simple example; more complex examples
726 of this section, and in @file{scm/define-markup-commands.scm}.
729 @node New markup command definition
730 @subsection New markup command definition
732 This section discusses the definition of new markup commands.
735 * Markup command definition syntax::
737 * A complete example::
738 * Adapting builtin commands::
741 @node Markup command definition syntax
742 @unnumberedsubsubsec Markup command definition syntax
744 New markup commands can be defined using the
745 @code{define-markup-command} Scheme macro, at top-level.
748 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} @dots{})
749 (@var{arg1-type?} @var{arg2-type?} @dots{})
750 [ #:properties ((@var{property1} @var{default-value1})
752 @dots{}command body@dots{})
758 @item @var{command-name}
759 the markup command name
761 the @q{layout} definition.
763 a list of associative lists, containing all active properties.
765 @var{i}th command argument
766 @item @var{argi-type?}
767 a type predicate for the i@var{th} argument
770 If the command uses properties from the @code{props} arguments,
771 the @code{#:properties} keyword can be used to specify which
772 properties are used along with their default values.
774 Arguments are distinguished according to their type:
776 @item a markup, corresponding to type predicate @code{markup?};
777 @item a list of markups, corresponding to type predicate
779 @item any other scheme object, corresponding to type predicates such as
780 @code{list?}, @code{number?}, @code{boolean?}, etc.
783 There is no limitation on the order of arguments (after the
784 standard @code{layout} and @code{props} arguments). However,
785 markup functions taking a markup as their last argument are
786 somewhat special as you can apply them to a markup list, and the
787 result is a markup list where the markup function (with the
788 specified leading arguments) has been applied to every element of
789 the original markup list.
791 Since replicating the leading arguments for applying a markup
792 function to a markup list is cheap mostly for Scheme arguments,
793 you avoid performance pitfalls by just using Scheme arguments for
794 the leading arguments of markup functions that take a markup as
799 @funindex interpret-markup
800 Markup commands have a rather complex life cycle. The body of a
801 markup command definition is responsible for converting the
802 arguments of the markup command into a stencil expression which is
803 returned. Quite often this is accomplished by calling the
804 @code{interpret-markup} function on a markup expression, passing
805 the @var{layout} and @var{props} arguments on to it. Those
806 arguments are usually only known at a very late stage in
807 typesetting. Markup expressions have their components assembled
808 into markup expressions already when @code{\markup} in a LilyPond
809 expression or the @code{markup} macro in Scheme is expanded. The
810 evaluation and typechecking of markup command arguments happens at
811 the time @code{\markup}/@code{markup} are interpreted.
813 But the actual conversion of markup expressions into stencil
814 expressions by executing the markup function bodies only happens
815 when @code{interpret-markup} is called on a markup expression.
818 @unnumberedsubsubsec On properties
820 The @code{layout} and @code{props} arguments of markup commands bring a
821 context for the markup interpretation: font size, line width, etc.
823 The @code{layout} argument allows access to properties defined in
824 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
825 For instance, the line width (the same as the one used in scores) is
829 (ly:output-def-lookup layout 'line-width)
832 The @code{props} argument makes some properties accessible to markup
833 commands. For instance, when a book title markup is interpreted, all
834 the variables defined in the @code{\header} block are automatically
835 added to @code{props}, so that the book title markup can access the book
836 title, composer, etc. It is also a way to configure the behaviour of a
837 markup command: for example, when a command uses font size during
838 processing, the font size is read from @code{props} rather than having a
839 @code{font-size} argument. The caller of a markup command may change
840 the value of the font size property in order to change the behaviour.
841 Use the @code{#:properties} keyword of @code{define-markup-command} to
842 specify which properties shall be read from the @code{props} arguments.
844 The example in next section illustrates how to access and override
845 properties in a markup command.
847 @node A complete example
848 @unnumberedsubsubsec A complete example
850 The following example defines a markup command to draw a double box
851 around a piece of text.
853 Firstly, we need to build an approximative result using markups.
854 Consulting the @ruser{Text markup commands} shows us the @code{\box}
857 @lilypond[quote,verbatim,ragged-right]
858 \markup \box \box HELLO
861 Now, we consider that more padding between the text and the boxes is
862 preferable. According to the @code{\box} documentation, this command
863 uses a @code{box-padding} property, which defaults to 0.2. The
864 documentation also mentions how to override it:
866 @lilypond[quote,verbatim,ragged-right]
867 \markup \box \override #'(box-padding . 0.6) \box A
870 Then, the padding between the two boxes is considered too small, so we
873 @lilypond[quote,verbatim,ragged-right]
874 \markup \override #'(box-padding . 0.4) \box
875 \override #'(box-padding . 0.6) \box A
878 Repeating this lengthy markup would be painful. This is where a markup
879 command is needed. Thus, we write a @code{double-box} markup command,
880 taking one argument (the text). This draws the two boxes, with some
884 #(define-markup-command (double-box layout props text) (markup?)
885 "Draw a double box around text."
886 (interpret-markup layout props
887 #@{\markup \override #'(box-padding . 0.4) \box
888 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
894 #(define-markup-command (double-box layout props text) (markup?)
895 "Draw a double box around text."
896 (interpret-markup layout props
897 (markup #:override '(box-padding . 0.4) #:box
898 #:override '(box-padding . 0.6) #:box text)))
901 @code{text} is the name of the command argument, and @code{markup?} its
902 type: it identifies it as a markup. The @code{interpret-markup}
903 function is used in most of markup commands: it builds a stencil, using
904 @code{layout}, @code{props}, and a markup. In the second case, this
905 markup is built using the @code{markup} scheme macro, see @ref{Markup
906 construction in Scheme}. The transformation from @code{\markup}
907 expression to scheme markup expression is straight-forward.
909 The new command can be used as follow:
912 \markup \double-box A
915 It would be nice to make the @code{double-box} command customizable:
916 here, the @code{box-padding} values are hard coded, and cannot be
917 changed by the user. Also, it would be better to distinguish the
918 padding between the two boxes, from the padding between the inner box
919 and the text. So we will introduce a new property,
920 @code{inter-box-padding}, for the padding between the two boxes. The
921 @code{box-padding} will be used for the inner padding. The new code is
925 #(define-markup-command (double-box layout props text) (markup?)
926 #:properties ((inter-box-padding 0.4)
928 "Draw a double box around text."
929 (interpret-markup layout props
930 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
931 \override #`(box-padding . ,box-padding) \box
935 Again, the equivalent version using the markup macro would be:
938 #(define-markup-command (double-box layout props text) (markup?)
939 #:properties ((inter-box-padding 0.4)
941 "Draw a double box around text."
942 (interpret-markup layout props
943 (markup #:override `(box-padding . ,inter-box-padding) #:box
944 #:override `(box-padding . ,box-padding) #:box text)))
947 Here, the @code{#:properties} keyword is used so that the
948 @code{inter-box-padding} and @code{box-padding} properties are read from
949 the @code{props} argument, and default values are given to them if the
950 properties are not defined.
952 Then, these values are used to override the @code{box-padding}
953 properties used by the two @code{\box} commands. Note the backquote and
954 the comma in the @code{\override} argument: they allow you to introduce
955 a variable value into a literal expression.
957 Now, the command can be used in a markup, and the boxes padding be
960 @lilypond[quote,verbatim,ragged-right]
961 #(define-markup-command (double-box layout props text) (markup?)
962 #:properties ((inter-box-padding 0.4)
964 "Draw a double box around text."
965 (interpret-markup layout props
966 #{\markup \override #`(box-padding . ,inter-box-padding) \box
967 \override #`(box-padding . ,box-padding) \box
970 \markup \double-box A
971 \markup \override #'(inter-box-padding . 0.8) \double-box A
972 \markup \override #'(box-padding . 1.0) \double-box A
975 @node Adapting builtin commands
976 @unnumberedsubsubsec Adapting builtin commands
978 A good way to start writing a new markup command, is to take example on
979 a builtin one. Most of the markup commands provided with LilyPond can be
980 found in file @file{scm/define-markup-commands.scm}.
982 For instance, we would like to adapt the @code{\draw-line} command, to
983 draw a double line instead. The @code{\draw-line} command is defined as
984 follow (documentation stripped):
987 (define-markup-command (draw-line layout props dest)
990 #:properties ((thickness 1))
991 "@dots{}documentation@dots{}"
992 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
996 (make-line-stencil th 0 0 x y)))
999 To define a new command based on an existing one, copy the definition,
1000 and change the command name. The @code{#:category} keyword can be
1001 safely removed, as it is only used for generating LilyPond
1002 documentation, and is of no use for user-defined markup commands.
1005 (define-markup-command (draw-double-line layout props dest)
1007 #:properties ((thickness 1))
1008 "@dots{}documentation@dots{}"
1009 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1013 (make-line-stencil th 0 0 x y)))
1016 Then, a property for setting the gap between two lines is added, called
1017 @code{line-gap}, defaulting e.g. to 0.6:
1020 (define-markup-command (draw-double-line layout props dest)
1022 #:properties ((thickness 1)
1024 "@dots{}documentation@dots{}"
1028 Finally, the code for drawing two lines is added. Two calls to
1029 @code{make-line-stencil} are used to draw the lines, and the resulting
1030 stencils are combined using @code{ly:stencil-add}:
1032 @lilypond[quote,verbatim,ragged-right]
1033 #(define-markup-command (my-draw-line layout props dest)
1035 #:properties ((thickness 1)
1038 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1042 (w (/ line-gap 2.0))
1043 (x (cond ((= dx 0) w)
1045 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1046 (y (* (if (< (* dx dy) 0) 1 -1)
1049 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1050 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1051 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1053 \markup \my-draw-line #'(4 . 3)
1054 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1058 @node New markup list command definition
1059 @subsection New markup list command definition
1060 @funindex define-markup-list-command
1061 @funindex interpret-markup-list
1062 Markup list commands are defined with the
1063 @code{define-markup-list-command} Scheme macro, which is similar to the
1064 @code{define-markup-command} macro described in
1065 @ref{New markup command definition}, except that where the latter returns
1066 a single stencil, the former returns a list of stencils.
1068 In a similar vein, @code{interpret-markup-list} is used instead of
1069 @code{interpret-markup} for converting a markup list into a list
1072 In the following example, a @code{\paragraph} markup list command is
1073 defined, which returns a list of justified lines, the first one being
1074 indented. The indent width is taken from the @code{props} argument.
1077 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1078 #:properties ((par-indent 2))
1079 (interpret-markup-list layout props
1080 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1084 The version using just Scheme is more complex:
1086 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1087 #:properties ((par-indent 2))
1088 (interpret-markup-list layout props
1089 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1093 Besides the usual @code{layout} and @code{props} arguments, the
1094 @code{paragraph} markup list command takes a markup list argument, named
1095 @code{args}. The predicate for markup lists is @code{markup-list?}.
1097 First, the function gets the indent width, a property here named
1098 @code{par-indent}, from the property list @code{props}. If the
1099 property is not found, the default value is @code{2}. Then, a
1100 list of justified lines is made using the built-in markup list command
1101 @code{\justified-lines}, which is related to the
1102 @code{make-justified-lines-markup-list} function. A
1103 horizontal space is added at the beginning using @code{\hspace} (or the
1104 @code{make-hspace-markup} function). Finally, the markup list is
1105 interpreted using the @code{interpret-markup-list} function.
1107 This new markup list command can be used as follows:
1111 The art of music typography is called \italic @{(plate) engraving.@}
1112 The term derives from the traditional process of music printing.
1113 Just a few decades ago, sheet music was made by cutting and stamping
1114 the music into a zinc or pewter plate in mirror image.
1116 \override-lines #'(par-indent . 4) \paragraph @{
1117 The plate would be inked, the depressions caused by the cutting
1118 and stamping would hold ink. An image was formed by pressing paper
1119 to the plate. The stamping and cutting was completely done by
1125 @node Contexts for programmers
1126 @section Contexts for programmers
1129 * Context evaluation::
1130 * Running a function on all layout objects::
1133 @node Context evaluation
1134 @subsection Context evaluation
1136 @cindex calling code during interpreting
1137 @funindex \applyContext
1139 Contexts can be modified during interpretation with Scheme code. The
1142 \applyContext @var{function}
1145 @code{@var{function}} should be a Scheme function that takes a
1146 single argument: the context in which the @code{\applyContext}
1147 command is being called. The following code will print the
1148 current bar number on the standard output during the compile:
1153 (format #t "\nWe were called in barnumber ~a.\n"
1154 (ly:context-property x 'currentBarNumber)))
1159 @node Running a function on all layout objects
1160 @subsection Running a function on all layout objects
1163 @cindex calling code on layout objects
1164 @funindex \applyOutput
1166 The most versatile way of tuning an object is @code{\applyOutput} which
1167 works by inserting an event into the specified context
1168 (@rinternals{ApplyOutputEvent}). Its syntax is
1170 \applyOutput @var{Context} @var{proc}
1174 where @code{@var{proc}} is a Scheme function, taking three arguments.
1176 When interpreted, the function @code{@var{proc}} is called for
1177 every layout object found in the context @code{@var{Context}} at
1178 the current time step, with the following arguments:
1180 @item the layout object itself,
1181 @item the context where the layout object was created, and
1182 @item the context where @code{\applyOutput} is processed.
1186 In addition, the cause of the layout object, i.e., the music
1187 expression or object that was responsible for creating it, is in the
1188 object property @code{cause}. For example, for a note head, this is a
1189 @rinternals{NoteHead} event, and for a stem object,
1190 this is a @rinternals{Stem} object.
1192 Here is a function to use for @code{\applyOutput}; it blanks
1193 note-heads on the center-line and next to it:
1195 @lilypond[quote,verbatim,ragged-right]
1196 #(define (blanker grob grob-origin context)
1197 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1198 (< (abs (ly:grob-property grob 'staff-position)) 2))
1199 (set! (ly:grob-property grob 'transparent) #t)))
1202 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1206 To have @var{function} interpreted at the @code{Score} or @code{Staff}
1207 level use these forms
1210 \applyOutput #'Score #@var{function}
1211 \applyOutput #'Staff #@var{function}
1215 @node Callback functions
1216 @section Callback functions
1218 Properties (like @code{thickness}, @code{direction}, etc.) can be
1219 set at fixed values with @code{\override}, e.g.
1222 \override Stem.thickness = #2.0
1225 Properties can also be set to a Scheme procedure,
1227 @lilypond[fragment,verbatim,quote,relative=2]
1228 \override Stem.thickness = #(lambda (grob)
1229 (if (= UP (ly:grob-property grob 'direction))
1236 In this case, the procedure is executed as soon as the value of the
1237 property is requested during the formatting process.
1239 Most of the typesetting engine is driven by such callbacks.
1240 Properties that typically use callbacks include
1244 The printing routine, that constructs a drawing for the symbol
1246 The routine that sets the horizontal position
1248 The routine that computes the width of an object
1251 The procedure always takes a single argument, being the grob.
1253 That procedure may access the usual value of the property, by first
1254 calling the function that is the usual callback for that property, which
1255 can by found in the Internals Reference or the file 'define-grobs.scm':
1259 \override Flag #'X-offset = #(lambda (flag)
1260 (let ((default (ly:flag::calc-x-offset flag)))
1266 If routines with multiple arguments must be called, the current grob
1267 can be inserted with a grob closure. Here is a setting from
1268 @code{AccidentalSuggestion},
1272 ,(ly:make-simple-closure
1274 ,(ly:make-simple-closure
1275 (list ly:self-alignment-interface::centered-on-x-parent))
1276 ,(ly:make-simple-closure
1277 (list ly:self-alignment-interface::x-aligned-on-self)))))
1281 In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
1282 @code{ly:self-alignment-interface::centered-on-x-parent} are called
1283 with the grob as argument. The results are added with the @code{+}
1284 function. To ensure that this addition is properly executed, the whole
1285 thing is enclosed in @code{ly:make-simple-closure}.
1287 In fact, using a single procedure as property value is equivalent to
1290 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1294 The inner @code{ly:make-simple-closure} supplies the grob as argument
1295 to @var{proc}, the outer ensures that result of the function is
1296 returned, rather than the @code{simple-closure} object.
1298 From within a callback, the easiest method for evaluating a markup is
1299 to use grob-interpret-markup. For example:
1302 my-callback = #(lambda (grob)
1303 (grob-interpret-markup grob (markup "foo")))
1308 @n ode Inline Scheme code
1309 @s ection Inline Scheme code
1311 TODO: after this section had been written, LilyPond has improved
1312 to the point that finding a @emph{simple} example where one would
1313 @emph{have} to revert to Scheme has become rather hard.
1315 Until this section gets a rewrite, let's pretend we don't know.
1317 The main disadvantage of @code{\tweak} is its syntactical
1318 inflexibility. For example, the following produces a syntax error
1319 (or rather, it did so at some point in the past).
1322 F = \tweak font-size #-3 -\flageolet
1330 Using Scheme, this problem can be avoided. The route to the
1331 result is given in @ref{Adding articulation to notes (example)},
1332 especially how to use @code{\displayMusic} as a helping guide.
1335 F = #(let ((m (make-music 'ArticulationEvent
1336 'articulation-type "flageolet")))
1337 (set! (ly:music-property m 'tweaks)
1338 (acons 'font-size -3
1339 (ly:music-property m 'tweaks)))
1348 Here, the @code{tweaks} properties of the flageolet object
1349 @code{m} (created with @code{make-music}) are extracted with
1350 @code{ly:music-property}, a new key-value pair to change the
1351 font size is prepended to the property list with the
1352 @code{acons} Scheme function, and the result is finally
1353 written back with @code{set!}. The last element of the
1354 @code{let} block is the return value, @code{m} itself.
1359 @node Difficult tweaks
1360 @section Difficult tweaks
1362 There are a few classes of difficult adjustments.
1368 One type of difficult adjustment involves the appearance of
1369 spanner objects, such as slurs and ties. Usually, only one
1370 spanner object is created at a time, and it can be adjusted with
1371 the normal mechanism. However, occasionally a spanner crosses a
1372 line break. When this happens, the object is cloned. A separate
1373 object is created for every system in which the spanner appears.
1374 The new objects are clones of the original object and inherit all
1375 properties, including @code{\override}s.
1378 In other words, an @code{\override} always affects all pieces of a
1379 broken spanner. To change only one part of a spanner at a line break,
1380 it is necessary to hook into the formatting process. The
1381 @code{after-line-breaking} callback contains the Scheme procedure that
1382 is called after the line breaks have been determined and layout
1383 objects have been split over different systems.
1385 In the following example, we define a procedure
1386 @code{my-callback}. This procedure
1390 determines if the spanner has been split across line breaks
1392 if yes, retrieves all the split objects
1394 checks if this grob is the last of the split objects
1396 if yes, it sets @code{extra-offset}.
1399 This procedure is installed into @rinternals{Tie}, so the last part
1400 of the broken tie is repositioned.
1402 @lilypond[quote,verbatim,ragged-right]
1403 #(define (my-callback grob)
1405 ;; have we been split?
1406 (orig (ly:grob-original grob))
1408 ;; if yes, get the split pieces (our siblings)
1409 (siblings (if (ly:grob? orig)
1410 (ly:spanner-broken-into orig)
1413 (if (and (>= (length siblings) 2)
1414 (eq? (car (last-pair siblings)) grob))
1415 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1418 \override Tie.after-line-breaking =
1426 When applying this trick, the new @code{after-line-breaking} callback
1427 should also call the old one, if such a default exists. For example,
1428 if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
1429 should also be called.
1433 Some objects cannot be changed with @code{\override} for
1434 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1435 and @code{PaperColumn}. They can be changed with the
1436 @code{\overrideProperty} function, which works similar to @code{\once
1437 \override}, but uses a different syntax.
1441 Score.NonMusicalPaperColumn % Grob name
1442 . line-break-system-details % Property name
1443 . next-padding % Optional subproperty name
1447 Note, however, that @code{\override}, applied to
1448 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1449 expected within @code{\context} blocks.
1453 @node LilyPond Scheme interfaces
1454 @chapter LilyPond Scheme interfaces
1456 This chapter covers the various tools provided by LilyPond to help
1457 Scheme programmers get information into and out of the music streams.
1459 TODO -- figure out what goes in here and how to organize it