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 () ()
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 The reader extracts the LilyPond code block and generates a runtime
67 call to the LilyPond parser to interpret the LilyPond code.
68 Scheme expressions embedded in the LilyPond code are evaluated in the
69 lexical environment of the LilyPond code block, so all local variables
70 and function parameters available at the point the LilyPond code block
71 is written may be accessed. Variables defined in other Scheme modules,
72 like the modules containing @code{\header} and @code{\layout} blocks,
73 are not accessible as Scheme variables, i.e. prefixed
74 with@tie{}@code{#}, but they are accessible as LilyPond variables, i.e.
75 prefixed with@tie{}@code{\}.
77 All music generated inside the code block has its
78 @samp{origin} set to the current input location.
80 A LilyPond code block may contain anything that you can use on the
81 right side of an assignment. In addition, an empty LilyPond block
82 corresponds to a void music expression, and a LilyPond block
83 containing multiple music events gets turned into a sequential music
86 @node Scheme functions
87 @section Scheme functions
88 @cindex Scheme functions (LilyPond syntax)
90 @emph{Scheme functions} are Scheme procedures that can create Scheme
91 expressions from input written in LilyPond syntax. They can be called
92 in pretty much all places where using @code{#} for specifying a value in
93 Scheme syntax is allowed. While Scheme has functions of its own, this
94 chapter is concerned with @emph{syntactic} functions, functions that
95 receive arguments specified in LilyPond syntax.
98 * Scheme function definitions::
99 * Scheme function usage::
100 * Void scheme functions::
103 @node Scheme function definitions
104 @subsection Scheme function definitions
105 @funindex define-scheme-function
107 The general form for defining scheme functions is:
111 #(define-scheme-function
112 (@var{arg1} @var{arg2} @dots{})
113 (@var{type1?} @var{type2?} @dots{})
120 @multitable @columnfractions .33 .66
121 @item @code{@var{argN}}
122 @tab @var{n}th argument
124 @item @code{@var{typeN?}}
125 @tab a Scheme @emph{type predicate} for which @code{@var{argN}}
126 must return @code{#t}. There is also a special form
127 @code{(@emph{predicate?} @emph{default})} for specifying optional
128 arguments. If the actual argument is missing when the function is being
129 called, the default value is substituted instead. Default values are
130 evaluated at definition time (including LilyPond code blocks!), so if
131 you need a default calculated at runtime, instead write a special value
132 you can easily recognize. If you write the predicate in parentheses but
133 don't follow it with a default value, @code{#f} is used as the default.
134 Default values are not verified with @emph{predicate?} at either
135 definition or run time: it is your responsibility to deal with the
136 values you specify. Default values that happen to be music expressions
137 are copied while setting @code{origin} to the current input location.
139 @item @code{@var{body}}
140 @tab A sequence of Scheme forms evaluated in order, the last one being
141 used as the return value of the scheme function. It may contain
142 LilyPond code blocks enclosed in hashed braces
143 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in
144 @ref{LilyPond code blocks}. Within LilyPond code blocks, use @code{#}
145 to reference function arguments (eg., @samp{#arg1}) or to start an
146 inline Scheme expression containing function arguments (eg.,
147 @w{@samp{#(cons arg1 arg2)}}). Where normal Scheme expressions using
148 @code{#} don't do the trick, you might need to revert to immediate
149 Scheme expressions using @code{$}, for example as @samp{$music}.
151 If your function returns a music expression, it is given a useful value
156 Suitability of arguments for the predicates is determined by
157 actually calling the predicate after LilyPond has already converted them
158 into a Scheme expression. As a consequence, the argument can be
159 specified in Scheme syntax if desired (introduced with @code{#} or as
160 the result of calling a scheme function), but LilyPond will also convert
161 a number of LilyPond constructs into Scheme before actually checking the
162 predicate on them. Currently, those include music, postevents, simple
163 strings (with or without quotes), numbers, full markups and markup
164 lists, score, book, bookpart, context definition and output definition
168 ambiguities LilyPond sorts out by checking with predicate
169 functions: is @samp{-3} a fingering postevent or a negative number? Is
170 @code{"a" 4} in lyric mode a string followed by a number, or a lyric
171 event of duration @code{4}? LilyPond tries the argument
172 predicate on successive interpretations until success, with an
173 order designed to minimize inconsistent interpretations and
176 For example, a predicate accepting both music expressions and
177 pitches will consider @code{c''} to be a pitch rather than a music
178 expression. Immediately following durations or postevents will
179 change that interpretation. It's best to avoid overly
180 permissive predicates like @code{scheme?} when the application
181 rather calls for more specific argument types.
183 For a list of available predefined type predicates, see
184 @ruser{Predefined type predicates}.
189 @ruser{Predefined type predicates}.
192 @file{lily/music-scheme.cc},
196 @node Scheme function usage
197 @subsection Scheme function usage
199 Scheme functions can be called pretty much anywhere where a Scheme
200 expression starting with @code{#} can be written. You call a scheme
201 function by writing its name preceded by @code{\}, followed by its
202 arguments. Once an optional argument predicate does not match an
203 argument, LilyPond skips this and all following optional arguments,
204 replacing them with their specified default, and @q{backs up} the
205 argument that did not match to the place of the next mandatory argument.
206 Since the backed up argument needs to go somewhere, optional arguments
207 are not actually considered optional unless followed by a mandatory
210 There is one exception: if you write @code{\default} in the place of an
211 optional argument, this and all following optional arguments are skipped
212 and replaced by their default. This works even when no mandatory
213 argument follows since @code{\default} does not need to get backed up.
214 The @code{mark} and @code{key} commands make use of that trick to
215 provide their default behavior when just followed by @code{\default}.
217 Apart from places where a Scheme value is required, there are a few
218 places where @code{#} expressions are currently accepted and evaluated
219 for their side effects but otherwise ignored. Mostly those are the
220 places where an assignment would be acceptable as well.
222 Since it is a bad idea to return values that can be misinterpreted in
223 some context, you should use normal scheme functions only for those
224 cases where you always return a useful value, and use void scheme
225 functions (@pxref{Void scheme functions}) otherwise.
227 @node Void scheme functions
228 @subsection Void scheme functions
229 @funindex define-void-function
232 Sometimes a procedure is executed in order to perform an action rather
233 than return a value. Some programming languages (like C and Scheme) use
234 functions for either concept and just discard the returned value
235 (usually by allowing any expression to act as statement, ignoring the
236 result). This is clever but error-prone: most C compilers nowadays
237 offer warnings for various non-``void'' expressions being discarded.
238 For many functions executing an action, the Scheme standards declare the
239 return value to be unspecified. LilyPond's Scheme interpreter Guile has
240 a unique value @code{*unspecified*} that it usually (such when using
241 @code{set!} directly on a variable) but unfortunately not consistently
242 returns in such cases.
244 Defining a LilyPond function with @code{define-void-function} makes
245 sure that this special value (the only value satisfying the predicate
246 @code{void?}) will be returned.
250 #(define-void-function
253 (ly:set-option 'point-and-click #f))
255 \noPointAndClick % disable point and click
258 If you want to evaluate an expression only for its side-effect and
259 don't want any value it may return interpreted, you can do so by
260 prefixing it with @code{\void}:
263 \void #(hashq-set! some-table some-key some-value)
266 That way, you can be sure that LilyPond will not assign meaning to the
267 returned value regardless of where it encounters it. This will also
268 work for music functions such as @code{\displayMusic}.
270 @node Music functions
271 @section Music functions
273 @cindex music functions
275 @emph{Music functions} are Scheme procedures that can create music
276 expressions automatically, and can be used to greatly simplify the
280 * Music function definitions::
281 * Music function usage::
282 * Simple substitution functions::
283 * Intermediate substitution functions::
284 * Mathematics in functions::
285 * Functions without arguments::
286 * Void music functions::
290 @node Music function definitions
291 @subsection Music function definitions
292 @cindex defining music functions
293 @funindex define-music-function
295 The general form for defining music functions is:
299 #(define-music-function
300 (@var{arg1} @var{arg2} @dots{})
301 (@var{type1?} @var{type2?} @dots{})
306 quite in analogy to @ref{Scheme function definitions}. More often than
307 not, @var{body} will be a @ref{LilyPond code blocks, LilyPond code block}.
309 For a list of available type predicates, see
310 @ruser{Predefined type predicates}.
315 @ruser{Predefined type predicates}.
318 @file{lily/music-scheme.cc},
323 @node Music function usage
324 @subsection Music function usage
325 A @q{music function} has to return an expression matching the predicate
326 @code{ly:music?}. This makes music function calls suitable as arguments
327 of type @code{ly:music?} for another music function call.
329 When using a music function call in other contexts, the context may
330 cause further semantic restrictions.
334 At the top level in a music expression a post-event is not accepted.
337 When a music function (as opposed to an event function) returns an
338 expression of type post-event, LilyPond requires one of the named
339 direction indicators (@code{-}, @code{^}, @w{and @code{_}})) in order to
340 properly integrate the post-event produced by the music function call
341 into the surrounding expression.
344 As a chord constituent. The returned expression must be of a
345 @code{rhythmic-event} type, most likely a @code{NoteEvent}.
349 @q{Polymorphic} functions, like @code{\tweak}, can be applied to
350 post-events, chord constituent and top level music expressions.
352 @node Simple substitution functions
353 @subsection Simple substitution functions
355 Simple substitution functions are music functions whose output
356 music expression is written in LilyPond format and contains
357 function arguments in the output expression. They are described
358 in @ruser{Substitution function examples}.
361 @node Intermediate substitution functions
362 @subsection Intermediate substitution functions
364 Intermediate substitution functions involve a mix of Scheme code
365 and LilyPond code in the music expression to be returned.
367 Some @code{\override} commands require an argument consisting of
368 a pair of numbers (called a @emph{cons cell} in Scheme).
370 The pair can be directly passed into the music function,
371 using a @code{pair?} variable:
375 #(define-music-function
379 \once \override Beam.positions = #beg-end
383 \manualBeam #'(3 . 6) c8 d e f
387 Alternatively, the numbers making up the pair can be
388 passed as separate arguments, and the Scheme code
389 used to create the pair can be included in the
392 @lilypond[quote,verbatim,ragged-right]
394 #(define-music-function
398 \once \override Beam.positions = #(cons beg end)
402 \manualBeam #3 #6 c8 d e f
407 @cindex temporary overrides
408 @cindex overrides, temporary
409 @cindex properties, popping previous value
411 Properties are maintained conceptually using one stack per property
412 per grob per context. Music functions may need to override one or
413 several properties for the duration of the function, restoring them
414 to their previous value before exiting. However, normal overrides
415 pop and discard the top of the current property stack before
416 pushing to it, so the previous value of the property is lost when it
417 is overridden. When the previous value must be preserved, prefix the
418 @code{\override} command with @code{\temporary}, like this:
421 \temporary \override @dots{}
424 The use of @code{\temporary} causes the (usually set) @code{pop-first}
425 property in the override to be cleared, so the previous value is not
426 popped off the property stack before pushing the new value onto it.
427 When a subsequent @code{\revert} pops off the temporarily overriden
428 value, the previous value will re-emerge.
430 In other words, calling @code{\temporary \override} and @code{\revert}
431 in succession on the same property will have a net effect of zero.
432 Similarly, pairing @code{\temporary} and @code{\undo} on the same
433 music containing overrides will have a net effect of zero.
435 Here is an example of a music function which makes use of this.
436 The use of @code{\temporary} ensures the values of the
437 @code{cross-staff} and @code{style} properties are restored on exit
438 to whatever values they had when the @code{crossStaff} function was
439 called. Without @code{\temporary} the default values would have been
444 #(define-music-function (notes) (ly:music?)
445 (_i "Create cross-staff stems")
447 \temporary \override Stem.cross-staff = #cross-staff-connect
448 \temporary \override Flag.style = #'no-flag
450 \revert Stem.cross-staff
456 @node Mathematics in functions
457 @subsection Mathematics in functions
459 Music functions can involve Scheme programming in
460 addition to simple substitution,
462 @lilypond[quote,verbatim,ragged-right]
464 #(define-music-function
468 \override Stem.length = #(* 7.0 mag)
469 \override NoteHead.font-size =
470 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
475 \revert NoteHead.font-size
480 \AltOn #1.5 c c \AltOff c2
485 This example may be rewritten to pass in music expressions,
487 @lilypond[quote,verbatim,ragged-right]
489 #(define-music-function
493 \override Stem.length = #(* 7.0 mag)
494 \override NoteHead.font-size =
495 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
498 \revert NoteHead.font-size
502 c'2 \withAlt #0.5 { c4 c }
503 \withAlt #1.5 { c c } c2
508 @node Functions without arguments
509 @subsection Functions without arguments
511 In most cases a function without arguments should be written
515 dolce = \markup@{ \italic \bold dolce @}
518 However, in rare cases it may be useful to create a music function
523 #(define-music-function
526 (if (eq? #t (ly:get-option 'display-bar-numbers))
527 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
531 To actually display bar numbers where this function is called,
532 invoke @command{lilypond} with
535 lilypond -d display-bar-numbers FILENAME.ly
539 @node Void music functions
540 @subsection Void music functions
542 A music function must return a music expression. If you want to
543 execute a function only for its side effect, you should use
544 @code{define-void-function}. But there may be cases where you
545 sometimes want to produce a music expression, and sometimes not (like
546 in the previous example). Returning a @code{void} music expression
547 via @code{#@{ #@}} will achieve that.
549 @node Event functions
550 @section Event functions
551 @funindex define-event-function
552 @cindex event functions
554 To use a music function in the place of an event, you need to write a
555 direction indicator before it. But sometimes, this does not quite match
556 the syntax of constructs you want to replace. For example, if you want
557 to write dynamics commands, those are usually attached without direction
558 indicator, like @code{c'\pp}. Here is a way to write arbitrary
560 @lilypond[quote,verbatim,ragged-right]
561 dyn=#(define-event-function (arg) (markup?)
562 (make-dynamic-script arg))
563 \relative { c'\dyn pfsss }
565 You could do the same using a music function, but then you always would
566 have to write a direction indicator before calling it, like
567 @code{@w{c-\dyn pfsss}}.
570 @node Markup functions
571 @section Markup functions
573 Markups are implemented as special Scheme functions which produce a
574 @code{Stencil} object given a number of arguments.
577 * Markup construction in Scheme::
578 * How markups work internally::
579 * New markup command definition::
580 * New markup list command definition::
584 @node Markup construction in Scheme
585 @subsection Markup construction in Scheme
587 @cindex defining markup commands
588 @funindex \displayScheme
590 Markup expressions are internally represented in Scheme using the
597 To see a markup expression in its Scheme form, use the
598 @code{\displayScheme} command:
604 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
605 \larger \line @{ foo bar baz @}
611 Compiling the code above will send the following to the display
619 (#:bold (#:italic "hello") #:raise 0.4 "world")
622 (#:simple "foo" #:simple "bar" #:simple "baz")))))
625 To prevent the markup from printing on the page, use
626 @w{@samp{\void \displayScheme @var{markup}}}. Also, as with the
627 @code{\displayMusic} command, the output of @code{\displayScheme}
628 can be saved to an external file. See
629 @ref{Displaying music expressions}.
632 This example demonstrates the main translation rules between regular
633 LilyPond markup syntax and Scheme markup syntax. Using @code{#@{
634 @dots{} #@}} for entering in LilyPond syntax will often be most
635 convenient, but we explain how to use the @code{markup} macro to get a
636 Scheme-only solution.
639 @multitable @columnfractions .3 .3
640 @item @b{LilyPond} @tab @b{Scheme}
641 @item @code{\markup markup1} @tab @code{(markup markup1)}
642 @item @code{\markup @{ markup1 markup2 @dots{} @}} @tab
643 @code{(markup markup1 markup2 @dots{} )}
644 @item @code{\markup-command} @tab @code{#:markup-command}
645 @item @code{\variable} @tab @code{variable}
646 @item @code{\center-column @{ @dots{} @}} @tab
647 @code{#:center-column ( @dots{} )}
648 @item @code{string} @tab @code{"string"}
649 @item @code{#scheme-arg} @tab @code{scheme-arg}
653 The whole Scheme language is accessible inside the
654 @code{markup} macro. For example, You may use function calls inside
655 @code{markup} in order to manipulate character strings. This is
656 useful when defining new markup commands (see
657 @ref{New markup command definition}).
662 The markup-list argument of commands such as @code{#:line},
663 @code{#:center}, and @code{#:column} cannot be a variable or
664 the result of a function call.
667 (markup #:line (function-that-returns-markups))
671 is invalid. One should use the @code{make-line-markup},
672 @code{make-center-markup}, or @code{make-column-markup} functions
676 (markup (make-line-markup (function-that-returns-markups)))
680 @node How markups work internally
681 @subsection How markups work internally
686 \raise #0.5 "text example"
690 @code{\raise} is actually represented by the @code{raise-markup}
691 function. The markup expression is stored as
694 (list raise-markup 0.5 (list simple-markup "text example"))
697 When the markup is converted to printable objects (Stencils), the
698 @code{raise-markup} function is called as
703 @var{list of property alists}
705 @var{the "text example" markup})
708 The @code{raise-markup} function first creates the stencil for the
709 @code{text example} string, and then it raises that Stencil by 0.5
710 staff space. This is a rather simple example; more complex examples
712 of this section, and in @file{scm/define-markup-commands.scm}.
715 @node New markup command definition
716 @subsection New markup command definition
718 This section discusses the definition of new markup commands.
721 * Markup command definition syntax::
723 * A complete example::
724 * Adapting builtin commands::
727 @node Markup command definition syntax
728 @unnumberedsubsubsec Markup command definition syntax
730 New markup commands can be defined using the
731 @code{define-markup-command} Scheme macro, at top-level.
734 (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} @dots{})
735 (@var{arg1-type?} @var{arg2-type?} @dots{})
736 [ #:properties ((@var{property1} @var{default-value1})
738 @dots{}command body@dots{})
744 @item @var{command-name}
745 the markup command name
747 the @q{layout} definition.
749 a list of associative lists, containing all active properties.
751 @var{i}th command argument
752 @item @var{argi-type?}
753 a type predicate for the i@var{th} argument
756 If the command uses properties from the @code{props} arguments,
757 the @code{#:properties} keyword can be used to specify which
758 properties are used along with their default values.
760 Arguments are distinguished according to their type:
762 @item a markup, corresponding to type predicate @code{markup?};
763 @item a list of markups, corresponding to type predicate
765 @item any other scheme object, corresponding to type predicates such as
766 @code{list?}, @code{number?}, @code{boolean?}, etc.
769 There is no limitation on the order of arguments (after the
770 standard @code{layout} and @code{props} arguments). However,
771 markup functions taking a markup as their last argument are
772 somewhat special as you can apply them to a markup list, and the
773 result is a markup list where the markup function (with the
774 specified leading arguments) has been applied to every element of
775 the original markup list.
777 Since replicating the leading arguments for applying a markup
778 function to a markup list is cheap mostly for Scheme arguments,
779 you avoid performance pitfalls by just using Scheme arguments for
780 the leading arguments of markup functions that take a markup as
785 @funindex interpret-markup
786 Markup commands have a rather complex life cycle. The body of a
787 markup command definition is responsible for converting the
788 arguments of the markup command into a stencil expression which is
789 returned. Quite often this is accomplished by calling the
790 @code{interpret-markup} function on a markup expression, passing
791 the @var{layout} and @var{props} arguments on to it. Those
792 arguments are usually only known at a very late stage in
793 typesetting. Markup expressions have their components assembled
794 into markup expressions already when @code{\markup} in a LilyPond
795 expression or the @code{markup} macro in Scheme is expanded. The
796 evaluation and typechecking of markup command arguments happens at
797 the time @code{\markup}/@code{markup} are interpreted.
799 But the actual conversion of markup expressions into stencil
800 expressions by executing the markup function bodies only happens
801 when @code{interpret-markup} is called on a markup expression.
804 @unnumberedsubsubsec On properties
806 The @code{layout} and @code{props} arguments of markup commands bring a
807 context for the markup interpretation: font size, line width, etc.
809 The @code{layout} argument allows access to properties defined in
810 @code{paper} blocks, using the @code{ly:output-def-lookup} function.
811 For instance, the line width (the same as the one used in scores) is
815 (ly:output-def-lookup layout 'line-width)
818 The @code{props} argument makes some properties accessible to markup
819 commands. For instance, when a book title markup is interpreted, all
820 the variables defined in the @code{\header} block are automatically
821 added to @code{props}, so that the book title markup can access the book
822 title, composer, etc. It is also a way to configure the behaviour of a
823 markup command: for example, when a command uses font size during
824 processing, the font size is read from @code{props} rather than having a
825 @code{font-size} argument. The caller of a markup command may change
826 the value of the font size property in order to change the behaviour.
827 Use the @code{#:properties} keyword of @code{define-markup-command} to
828 specify which properties shall be read from the @code{props} arguments.
830 The example in next section illustrates how to access and override
831 properties in a markup command.
833 @node A complete example
834 @unnumberedsubsubsec A complete example
836 The following example defines a markup command to draw a double box
837 around a piece of text.
839 Firstly, we need to build an approximative result using markups.
840 Consulting the @ruser{Text markup commands} shows us the @code{\box}
843 @lilypond[quote,verbatim,ragged-right]
844 \markup \box \box HELLO
847 Now, we consider that more padding between the text and the boxes is
848 preferable. According to the @code{\box} documentation, this command
849 uses a @code{box-padding} property, which defaults to 0.2. The
850 documentation also mentions how to override it:
852 @lilypond[quote,verbatim,ragged-right]
853 \markup \box \override #'(box-padding . 0.6) \box A
856 Then, the padding between the two boxes is considered too small, so we
859 @lilypond[quote,verbatim,ragged-right]
860 \markup \override #'(box-padding . 0.4) \box
861 \override #'(box-padding . 0.6) \box A
864 Repeating this lengthy markup would be painful. This is where a markup
865 command is needed. Thus, we write a @code{double-box} markup command,
866 taking one argument (the text). This draws the two boxes, with some
870 #(define-markup-command (double-box layout props text) (markup?)
871 "Draw a double box around text."
872 (interpret-markup layout props
873 #@{\markup \override #'(box-padding . 0.4) \box
874 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
880 #(define-markup-command (double-box layout props text) (markup?)
881 "Draw a double box around text."
882 (interpret-markup layout props
883 (markup #:override '(box-padding . 0.4) #:box
884 #:override '(box-padding . 0.6) #:box text)))
887 @code{text} is the name of the command argument, and @code{markup?} its
888 type: it identifies it as a markup. The @code{interpret-markup}
889 function is used in most of markup commands: it builds a stencil, using
890 @code{layout}, @code{props}, and a markup. In the second case, this
891 markup is built using the @code{markup} scheme macro, see @ref{Markup
892 construction in Scheme}. The transformation from @code{\markup}
893 expression to scheme markup expression is straight-forward.
895 The new command can be used as follow:
898 \markup \double-box A
901 It would be nice to make the @code{double-box} command customizable:
902 here, the @code{box-padding} values are hard coded, and cannot be
903 changed by the user. Also, it would be better to distinguish the
904 padding between the two boxes, from the padding between the inner box
905 and the text. So we will introduce a new property,
906 @code{inter-box-padding}, for the padding between the two boxes. The
907 @code{box-padding} will be used for the inner padding. The new code is
911 #(define-markup-command (double-box layout props text) (markup?)
912 #:properties ((inter-box-padding 0.4)
914 "Draw a double box around text."
915 (interpret-markup layout props
916 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
917 \override #`(box-padding . ,box-padding) \box
921 Again, the equivalent version using the markup macro would be:
924 #(define-markup-command (double-box layout props text) (markup?)
925 #:properties ((inter-box-padding 0.4)
927 "Draw a double box around text."
928 (interpret-markup layout props
929 (markup #:override `(box-padding . ,inter-box-padding) #:box
930 #:override `(box-padding . ,box-padding) #:box text)))
933 Here, the @code{#:properties} keyword is used so that the
934 @code{inter-box-padding} and @code{box-padding} properties are read from
935 the @code{props} argument, and default values are given to them if the
936 properties are not defined.
938 Then, these values are used to override the @code{box-padding}
939 properties used by the two @code{\box} commands. Note the backquote and
940 the comma in the @code{\override} argument: they allow you to introduce
941 a variable value into a literal expression.
943 Now, the command can be used in a markup, and the boxes padding be
946 @lilypond[quote,verbatim,ragged-right]
947 #(define-markup-command (double-box layout props text) (markup?)
948 #:properties ((inter-box-padding 0.4)
950 "Draw a double box around text."
951 (interpret-markup layout props
952 #{\markup \override #`(box-padding . ,inter-box-padding) \box
953 \override #`(box-padding . ,box-padding) \box
956 \markup \double-box A
957 \markup \override #'(inter-box-padding . 0.8) \double-box A
958 \markup \override #'(box-padding . 1.0) \double-box A
961 @node Adapting builtin commands
962 @unnumberedsubsubsec Adapting builtin commands
964 A good way to start writing a new markup command, is to take example on
965 a builtin one. Most of the markup commands provided with LilyPond can be
966 found in file @file{scm/define-markup-commands.scm}.
968 For instance, we would like to adapt the @code{\draw-line} command, to
969 draw a double line instead. The @code{\draw-line} command is defined as
970 follow (documentation stripped):
973 (define-markup-command (draw-line layout props dest)
976 #:properties ((thickness 1))
977 "@dots{}documentation@dots{}"
978 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
982 (make-line-stencil th 0 0 x y)))
985 To define a new command based on an existing one, copy the definition,
986 and change the command name. The @code{#:category} keyword can be
987 safely removed, as it is only used for generating LilyPond
988 documentation, and is of no use for user-defined markup commands.
991 (define-markup-command (draw-double-line layout props dest)
993 #:properties ((thickness 1))
994 "@dots{}documentation@dots{}"
995 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
999 (make-line-stencil th 0 0 x y)))
1002 Then, a property for setting the gap between two lines is added, called
1003 @code{line-gap}, defaulting e.g. to 0.6:
1006 (define-markup-command (draw-double-line layout props dest)
1008 #:properties ((thickness 1)
1010 "@dots{}documentation@dots{}"
1014 Finally, the code for drawing two lines is added. Two calls to
1015 @code{make-line-stencil} are used to draw the lines, and the resulting
1016 stencils are combined using @code{ly:stencil-add}:
1018 @lilypond[quote,verbatim,ragged-right]
1019 #(define-markup-command (my-draw-line layout props dest)
1021 #:properties ((thickness 1)
1024 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1028 (w (/ line-gap 2.0))
1029 (x (cond ((= dx 0) w)
1031 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1032 (y (* (if (< (* dx dy) 0) 1 -1)
1035 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1036 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1037 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1039 \markup \my-draw-line #'(4 . 3)
1040 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1044 @node New markup list command definition
1045 @subsection New markup list command definition
1046 @funindex define-markup-list-command
1047 @funindex interpret-markup-list
1048 Markup list commands are defined with the
1049 @code{define-markup-list-command} Scheme macro, which is similar to the
1050 @code{define-markup-command} macro described in
1051 @ref{New markup command definition}, except that where the latter returns
1052 a single stencil, the former returns a list of stencils.
1054 In a similar vein, @code{interpret-markup-list} is used instead of
1055 @code{interpret-markup} for converting a markup list into a list
1058 In the following example, a @code{\paragraph} markup list command is
1059 defined, which returns a list of justified lines, the first one being
1060 indented. The indent width is taken from the @code{props} argument.
1063 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1064 #:properties ((par-indent 2))
1065 (interpret-markup-list layout props
1066 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1070 The version using just Scheme is more complex:
1072 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1073 #:properties ((par-indent 2))
1074 (interpret-markup-list layout props
1075 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1079 Besides the usual @code{layout} and @code{props} arguments, the
1080 @code{paragraph} markup list command takes a markup list argument, named
1081 @code{args}. The predicate for markup lists is @code{markup-list?}.
1083 First, the function gets the indent width, a property here named
1084 @code{par-indent}, from the property list @code{props}. If the
1085 property is not found, the default value is @code{2}. Then, a
1086 list of justified lines is made using the built-in markup list command
1087 @code{\justified-lines}, which is related to the
1088 @code{make-justified-lines-markup-list} function. A
1089 horizontal space is added at the beginning using @code{\hspace} (or the
1090 @code{make-hspace-markup} function). Finally, the markup list is
1091 interpreted using the @code{interpret-markup-list} function.
1093 This new markup list command can be used as follows:
1097 The art of music typography is called \italic @{(plate) engraving.@}
1098 The term derives from the traditional process of music printing.
1099 Just a few decades ago, sheet music was made by cutting and stamping
1100 the music into a zinc or pewter plate in mirror image.
1102 \override-lines #'(par-indent . 4) \paragraph @{
1103 The plate would be inked, the depressions caused by the cutting
1104 and stamping would hold ink. An image was formed by pressing paper
1105 to the plate. The stamping and cutting was completely done by
1111 @node Contexts for programmers
1112 @section Contexts for programmers
1115 * Context evaluation::
1116 * Running a function on all layout objects::
1119 @node Context evaluation
1120 @subsection Context evaluation
1122 @cindex calling code during interpreting
1123 @funindex \applyContext
1124 @funindex make-apply-context
1125 @funindex ly:context-property
1126 @funindex ly:context-set-property!
1127 @funindex ly:context-grob-definition
1128 @funindex ly:assoc-get
1129 @funindex ly:context-pushpop-property
1131 Contexts can be modified during interpretation with Scheme code.
1132 In a LilyPond code block, the syntax for this is:
1135 \applyContext @var{function}
1138 In Scheme code, the syntax is:
1141 (make-apply-context @var{function})
1144 @code{@var{function}} should be a Scheme function that takes a
1145 single argument: the context in which the @code{\applyContext}
1146 command is being called. The function can access as well as
1147 override/set grob properties and context properties. Any actions
1148 taken by the function that depend on the state of the context are
1149 limited to the state of the context @emph{when the function is
1150 called}. Also, changes effected by a call to @code{\applyContext}
1151 remain in effect until they are directly modified again, or
1152 reverted, even if the initial conditions that they depended on
1155 The following scheme functions are useful when using
1156 @code{\applyContext}:
1159 @item ly:context-property
1160 look up a context property value
1162 @item ly:context-set-property!
1163 set a context property
1165 @item ly:context-grob-definition
1167 look up a grob property value
1169 @item ly:context-pushpop-property
1170 do a @code{\temporary@tie{}\override}
1171 or a @code{\revert} on a grob property
1175 The following example looks up the current @code{fontSize} value, and
1178 @lilypond[quote,verbatim]
1182 (let ((fontSize (ly:context-property context 'fontSize)))
1183 (ly:context-set-property! context 'fontSize (+ fontSize 6))))
1194 The following example looks up the current colors of the
1195 @code{NoteHead}, @code{Stem}, and @code{Beam} grobs, and then changes
1196 each to a less saturated shade.
1198 @lilypond[quote,verbatim]
1202 (define (desaturate-grob grob)
1203 (let* ((grob-def (ly:context-grob-definition context grob))
1204 (color (ly:assoc-get 'color grob-def black))
1205 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1206 (ly:context-pushpop-property context grob 'color new-color)))
1207 (for-each desaturate-grob '(NoteHead Stem Beam)))
1211 g'8[ g] \desaturate g[ g] \desaturate g[ g]
1212 \override NoteHead.color = #darkred
1213 \override Stem.color = #darkred
1214 \override Beam.color = #darkred
1215 g[ g] \desaturate g[ g] \desaturate g[ g]
1220 This also could be implemented as a music function, in order to
1221 restrict the modifications to a single music block. Notice how
1222 @code{ly:context-pushpop-property} is used both as a
1223 @code{\temporary@tie{}\override} and as a @code{\revert}:
1225 @lilypond[quote,verbatim]
1227 #(define-music-function
1232 (define (desaturate-grob grob)
1233 (let* ((grob-def (ly:context-grob-definition context grob))
1234 (color (ly:assoc-get 'color grob-def black))
1235 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1236 (ly:context-pushpop-property context grob 'color new-color)))
1237 (for-each desaturate-grob '(NoteHead Stem Beam)))
1241 (define (revert-color grob)
1242 (ly:context-pushpop-property context grob 'color))
1243 (for-each revert-color '(NoteHead Stem Beam)))
1247 \override NoteHead.color = #darkblue
1248 \override Stem.color = #darkblue
1249 \override Beam.color = #darkblue
1251 \desaturate { d c b a }
1257 @node Running a function on all layout objects
1258 @subsection Running a function on all layout objects
1261 @cindex calling code on layout objects
1262 @funindex \applyOutput
1264 The most versatile way of tuning an object is @code{\applyOutput} which
1265 works by inserting an event into the specified context
1266 (@rinternals{ApplyOutputEvent}). Its syntax is
1268 \applyOutput @var{Context} @var{proc}
1272 where @code{@var{proc}} is a Scheme function, taking three arguments.
1274 When interpreted, the function @code{@var{proc}} is called for
1275 every layout object found in the context @code{@var{Context}} at
1276 the current time step, with the following arguments:
1278 @item the layout object itself,
1279 @item the context where the layout object was created, and
1280 @item the context where @code{\applyOutput} is processed.
1284 In addition, the cause of the layout object, i.e., the music
1285 expression or object that was responsible for creating it, is in the
1286 object property @code{cause}. For example, for a note head, this is a
1287 @rinternals{NoteHead} event, and for a stem object,
1288 this is a @rinternals{Stem} object.
1290 Here is a function to use for @code{\applyOutput}; it blanks
1291 note-heads on the center-line and next to it:
1293 @lilypond[quote,verbatim,ragged-right]
1294 #(define (blanker grob grob-origin context)
1295 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1296 (< (abs (ly:grob-property grob 'staff-position)) 2))
1297 (set! (ly:grob-property grob 'transparent) #t)))
1300 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1304 To have @var{function} interpreted at the @code{Score} or @code{Staff}
1305 level use these forms
1308 \applyOutput #'Score #@var{function}
1309 \applyOutput #'Staff #@var{function}
1313 @node Callback functions
1314 @section Callback functions
1316 Properties (like @code{thickness}, @code{direction}, etc.) can be
1317 set at fixed values with @code{\override}, e.g.
1320 \override Stem.thickness = #2.0
1323 Properties can also be set to a Scheme procedure,
1325 @lilypond[fragment,verbatim,quote,relative=2]
1326 \override Stem.thickness = #(lambda (grob)
1327 (if (= UP (ly:grob-property grob 'direction))
1334 In this case, the procedure is executed as soon as the value of the
1335 property is requested during the formatting process.
1337 Most of the typesetting engine is driven by such callbacks.
1338 Properties that typically use callbacks include
1342 The printing routine, that constructs a drawing for the symbol
1344 The routine that sets the horizontal position
1346 The routine that computes the width of an object
1349 The procedure always takes a single argument, being the grob.
1351 That procedure may access the usual value of the property, by first
1352 calling the function that is the usual callback for that property, which
1353 can by found in the Internals Reference or the file 'define-grobs.scm':
1357 \override Flag.X-offset = #(lambda (flag)
1358 (let ((default (ly:flag::calc-x-offset flag)))
1364 From within a callback, the easiest method for evaluating a markup is
1365 to use grob-interpret-markup. For example:
1368 my-callback = #(lambda (grob)
1369 (grob-interpret-markup grob (markup "foo")))
1374 @n ode Inline Scheme code
1375 @s ection Inline Scheme code
1377 TODO: after this section had been written, LilyPond has improved
1378 to the point that finding a @emph{simple} example where one would
1379 @emph{have} to revert to Scheme has become rather hard.
1381 Until this section gets a rewrite, let's pretend we don't know.
1383 The main disadvantage of @code{\tweak} is its syntactical
1384 inflexibility. For example, the following produces a syntax error
1385 (or rather, it did so at some point in the past).
1388 F = \tweak font-size #-3 -\flageolet
1396 Using Scheme, this problem can be avoided. The route to the
1397 result is given in @ref{Adding articulation to notes (example)},
1398 especially how to use @code{\displayMusic} as a helping guide.
1401 F = #(let ((m (make-music 'ArticulationEvent
1402 'articulation-type "flageolet")))
1403 (set! (ly:music-property m 'tweaks)
1404 (acons 'font-size -3
1405 (ly:music-property m 'tweaks)))
1414 Here, the @code{tweaks} properties of the flageolet object
1415 @code{m} (created with @code{make-music}) are extracted with
1416 @code{ly:music-property}, a new key-value pair to change the
1417 font size is prepended to the property list with the
1418 @code{acons} Scheme function, and the result is finally
1419 written back with @code{set!}. The last element of the
1420 @code{let} block is the return value, @code{m} itself.
1425 @node Difficult tweaks
1426 @section Difficult tweaks
1428 There are a few classes of difficult adjustments.
1434 One type of difficult adjustment involves the appearance of
1435 spanner objects, such as slurs and ties. Usually, only one
1436 spanner object is created at a time, and it can be adjusted with
1437 the normal mechanism. However, occasionally a spanner crosses a
1438 line break. When this happens, the object is cloned. A separate
1439 object is created for every system in which the spanner appears.
1440 The new objects are clones of the original object and inherit all
1441 properties, including @code{\override}s.
1444 In other words, an @code{\override} always affects all pieces of a
1445 broken spanner. To change only one part of a spanner at a line break,
1446 it is necessary to hook into the formatting process. The
1447 @code{after-line-breaking} callback contains the Scheme procedure that
1448 is called after the line breaks have been determined and layout
1449 objects have been split over different systems.
1451 In the following example, we define a procedure
1452 @code{my-callback}. This procedure
1456 determines if the spanner has been split across line breaks
1458 if yes, retrieves all the split objects
1460 checks if this grob is the last of the split objects
1462 if yes, it sets @code{extra-offset}.
1465 This procedure is installed into @rinternals{Tie}, so the last part
1466 of the broken tie is repositioned.
1468 @lilypond[quote,verbatim,ragged-right]
1469 #(define (my-callback grob)
1471 ;; have we been split?
1472 (orig (ly:grob-original grob))
1474 ;; if yes, get the split pieces (our siblings)
1475 (siblings (if (ly:grob? orig)
1476 (ly:spanner-broken-into orig)
1479 (if (and (>= (length siblings) 2)
1480 (eq? (car (last-pair siblings)) grob))
1481 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1484 \override Tie.after-line-breaking =
1492 When applying this trick, the new @code{after-line-breaking} callback
1493 should also call the old one, if such a default exists. For example,
1494 if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
1495 should also be called.
1499 Some objects cannot be changed with @code{\override} for
1500 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
1501 and @code{PaperColumn}. They can be changed with the
1502 @code{\overrideProperty} function, which works similar to @code{\once
1503 \override}, but uses a different syntax.
1507 Score.NonMusicalPaperColumn % Grob name
1508 . line-break-system-details % Property name
1509 . next-padding % Optional subproperty name
1513 Note, however, that @code{\override}, applied to
1514 @code{NonMusicalPaperColumn} and @code{PaperColumn}, still works as
1515 expected within @code{\context} blocks.
1519 @node LilyPond Scheme interfaces
1520 @chapter LilyPond Scheme interfaces
1522 This chapter covers the various tools provided by LilyPond to help
1523 Scheme programmers get information into and out of the music streams.
1525 TODO -- figure out what goes in here and how to organize it