4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
11 @chapter Advanced Topics
14 When LilyPond is run, it reads an input file. During parsing, Music
15 objects are created. This music is interpreted, which is done by
16 contexts, that produce graphical objects. This section discusses
17 details of these three concepts, and how they are glued together with
18 the embedded Scheme interpreter.
21 * Interpretation context::
22 * Scheme integration::
23 * Music storage format::
29 @node Interpretation context
30 @section Interpretation context
35 * Context evaluation::
36 * Context properties::
37 * Engravers and performers::
38 * Changing context definitions::
39 * Defining new contexts::
43 Interpretation contexts are objects that only exist during program
44 run. During the interpretation phase (when @code{interpreting music}
45 is interpreted to standard output), the music expression in a
46 @code{\score} block is interpreted in time order, the same order in
47 which hear and play the music. During this phase, the interpretation
48 context holds the state for the current point within the music, for example
50 @item What notes are playing at this point?
52 @item What symbols will be printed at this point?
54 @item What is the current key signature, time signature, point within
58 Contexts are grouped hierarchically: A @internalsref{Voice} context is
59 contained in a @internalsref{Staff} context (because a staff can contain
60 multiple voices at any point), a @internalsref{Staff} context is contained in
61 @internalsref{Score}, @internalsref{StaffGroup}, or
62 @internalsref{ChoirStaff} context.
64 Contexts associated with sheet music output are called @emph{notation
65 contexts}, those for sound output are called @emph{performance
66 contexts}. The default definitions of the standard notation and
67 performance contexts can be found in @file{ly/engraver-init.ly} and
68 @file{ly/performer-init.ly}, respectively.
71 @node Creating contexts
72 @subsection Creating contexts
73 @cindex @code{\context}
74 @cindex context selection
76 Contexts for a music expression can be selected manually, using the
77 following music expression.
80 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
84 This means that @var{musicexpr} should be interpreted within a context
85 of type @var{contexttype} (with name @var{contextname} if specified).
86 If no such context exists, it will be created.
88 @lilypond[verbatim,singleline]
90 \notes \relative c'' {
91 c4 <d4 \context Staff = "another" e4> f
97 In this example, the @code{c} and @code{d} are printed on the
98 default staff. For the @code{e}, a context Staff called
99 @code{another} is specified; since that does not exist, a new
100 context is created. Within @code{another}, a (default) Voice context
101 is created for the @code{e4}. When all music referring to a
102 context is finished, the context is ended as well. So after the
103 third quarter, @code{another} is removed.
106 @node Default contexts
107 @subsection Default contexts
109 Most music expressions do not need an explicit @code{\context}
110 declaration: they inherit the notation context from their parent. In
111 the following example, only the sequential expression has an explicit
112 context. The notes contained therein inherit the @code{goUp} context
113 from the enclosing music expression.
115 @lilypond[verbatim,singleline]
116 \notes \context Voice = goUp { c'4 d' e' }
119 There are some quirks that you must keep in mind when dealing with
122 First, every top level music is interpreted by the Score context; in other
123 words, you may think of @code{\score} working like
127 \context Score @var{music}
131 Second, contexts are created automatically to be able to interpret the
132 music expressions. Consider the following example.
134 @lilypond[verbatim, singleline]
135 \score { \notes { c'4-( d' e'-) } }
139 The sequential music is interpreted by the Score context initially
140 (notice that the @code{\context} specification is redundant), but when a
141 note is encountered, contexts are setup to accept that note. In this
142 case, a Thread, Voice, and Staff context are created. The rest of the
143 sequential music is also interpreted with the same Thread, Voice, and
144 Staff context, putting the notes on the same staff, in the same voice.
146 @node Context evaluation
147 @subsection Context evaluation
149 Scheme code can be used to modify contexts. The syntax for this is
152 \applycontext @var{function}
155 @var{function} should be a Scheme function taking a single argument,
156 being the context to apply it with. The following code will print the
157 current bar number on the standard output during the compile.
162 (format #t "\nWe were called in barnumber ~a.\n"
163 (ly:get-context-property x 'currentBarNumber)))
167 @node Context properties
168 @subsection Context properties
171 Notation contexts have properties. These properties are from
172 the @file{.ly} file using the following expression:
173 @cindex @code{\property}
174 @cindex context properties
175 @cindex properties, context
178 \property @var{contextname}.@var{propname} = @var{value}
182 Sets the @var{propname} property of the context @var{contextname} to
183 the specified Scheme expression @var{value}. Both @var{propname} and
184 @var{contextname} are strings, which can often be written unquoted.
187 Properties that are set in one context are inherited by all of the
188 contained contexts. This means that a property valid for the
189 @internalsref{Voice} context can be set in the @internalsref{Score} context
190 (for example) and thus take effect in all @internalsref{Voice} contexts.
192 @cindex @code{Current}
193 If you do not wish to specify the name of the context in the
194 @code{\property}-expression itself, you can refer to the abstract context
195 name, @code{Current}. The @code{Current} context is the latest
196 used context. This will typically mean the @internalsref{Thread}
197 context, but you can force another context with the
198 @code{\property}-command. Hence the expressions
201 \property @var{contextname}.@var{propname} = @var{value}
208 \context @var{contextname}
209 \property Current.@var{propname} = @var{value}
213 do the same thing. The main use for this is in predefined variables.
214 This construction allows the specification of a property-setting
215 without restriction to a specific context.
217 Properties can be unset using the following statement.
219 \property @var{contextname}.@var{propname} \unset
222 @cindex properties, unsetting
223 @cindex @code{\unset}
226 This removes the definition of @var{propname} in @var{contextname}. If
227 @var{propname} was not defined in @var{contextname} (but was inherited
228 from a higher context), then this has no effect.
232 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
233 the inverse of @code{\property \set}.
236 @node Engravers and performers
237 @subsection Engravers and performers
239 @node Changing context definitions
240 @subsection Changing context definitions
241 @cindex context definition
242 @cindex translator definition
244 The most common way to define a context is by extending an existing
245 context. You can change an existing context from the paper block by
246 first initializing a translator with an existing context identifier:
251 @var{context-identifier}
257 Every predefined context has a standard identifier. For example, the
258 @code{Staff} context can be referred to as @code{\StaffContext}.
261 The context can then be modified by setting or changing properties,
266 Stem \set #'thickness = #1.2
267 defaultBarType = #"||"
270 These assignments happen before interpretation starts, so a @code{\property}
271 command will override any predefined settings.
277 It is not possible to collect multiple property assignments in a
278 variable, and apply to one @code{\translator} definition by
279 referencing that variable.
281 @node Defining new contexts
282 @subsection Defining new contexts
287 Each context is composed of a number of building blocks, or plug-ins
288 called engravers. An engraver is a specialized C++ class that is
289 compiled into the executable. Typically, an engraver is responsible
290 for one function: the @code{Slur_engraver} creates only @code{Slur}
291 objects, and the @code{Skip_event_swallow_translator} only swallows
292 (silently gobbles) @code{SkipEvent}s.
294 An existing context definition can be changed by adding or removing an
295 engraver. The syntax for these operations is
297 \consists @var{engravername}
298 \remove @var{engravername}
305 Here @var{engravername} is a string, the name of an engraver in the
306 system. In the following example, the @code{Clef_engraver} is removed
307 from the Staff context. The result is a staff without a clef, where
308 the central C is at its default position, the center line.
310 @lilypond[verbatim,singleline]
318 \remove Clef_engraver
324 A list of all engravers is in the internal documentation,
325 see @internalsref{All engravers}.
327 It is also possible to define new contexts from scratch. To do this,
328 you must define give the new context a name. In the following
329 example, a very simple Staff context is created: one that will put
330 note heads on a staff symbol.
334 \type "Engraver_group_engraver"
337 \consists "Staff_symbol_engraver"
338 \consists "Note_head_engraver"
339 \consistsend "Axis_group_engraver"
344 The argument of @code{\type} is the name for a special engraver that
345 handles cooperation between simple engravers such as
346 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
347 should always be @code{Engraver_group_engraver} (unless you are
348 defining a Score context from scratch, in which case
349 @code{Score_engraver} must be used).
351 The complete list of context modifiers is as follows:
353 @item @code{\alias} @var{alternate-name}:
354 This specifies a different name. In the above example,
355 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
357 @item @code{\consistsend} @var{engravername}:
358 Analogous to @code{\consists}, but makes sure that
359 @var{engravername} is always added to the end of the list of
362 Engravers that group context objects into axis groups or alignments
363 need to be at the end of the list. @code{\consistsend} insures that
364 engravers stay at the end even if a user adds or removes engravers.
366 @item @code{\accepts} @var{contextname}:
367 This context can contains @var{contextname} contexts. The first
368 @code{\accepts} is created as a default context when events (eg. notes
369 or rests) are encountered.
371 @item @code{\denies}:
372 The opposite of @code{\accepts}.
374 @item @code{\name} @var{contextname}:
375 This sets the type name of the context, e.g. @code{Staff},
376 @code{Voice}. If the name is not specified, the translator will not
381 @node Scheme integration
382 @section Scheme integration
386 @cindex Scheme, in-line code
387 @cindex accessing Scheme
388 @cindex evaluating Scheme
391 LilyPond internally uses GUILE, a Scheme-interpreter.
394 Scheme is used to represent data throughout the whole program.
396 In some places of the input file, Scheme expressions also form valid
397 syntax: wherever it is allowed, GUILE can be accessed directly by
398 entering a hash-sign (@code{#}). The expression following the
399 hash-sign is evaluated as Scheme. For example, the boolean value @var{true} is
400 @code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
401 and can be used in property assignments:
403 \property Staff.autoBeaming = ##f
406 Scheme is a full-blown programming language, from the LISP family. and
407 a full discussion is outside the scope of this document. Interested
408 readers are referred to the website @uref{http://www.schemers.org/}
409 for more information on Scheme.
411 The GUILE library for extension is documented at
412 @uref{http://www.gnu.org/software/guile}.
414 When it is installed, the following link should take you to its manual
415 @ref{(guile.info)guile}
419 * Input variables and Scheme::
424 @node Input variables and Scheme
425 @subsection Input variables and Scheme
428 The input format supports the notion of variable: in the following
429 example, a music expression is assigned to a variable with the name
432 traLaLa = \notes @{ c'4 d'4 @}
437 There is also a form of scoping: in the following example, the
438 @code{\paper} block also contains a @code{traLaLa} variable, which is
439 independent of the outer \traLaLa.
441 traLaLa = \notes @{ c'4 d'4 @}
442 \paper @{ traLaLa = 1.0 @}
445 In effect, each input file is a scope, and all @code{\header},
446 @code{\midi} and @code{\paper} blocks are scopes nested inside that
449 Both variables and scoping are implemented in the GUILE module system.
450 A anonymous Scheme module is attached to each scope. An assignment of
453 traLaLa = \notes @{ c'4 d'4 @}
457 is internally converted to a Scheme definition
459 (define traLaLa @var{Scheme value of @code{\notes ... }})
462 This means that input variables and Scheme variables may be freely
463 mixed. In the following example, a music fragment is stored in the
464 variable @code{traLaLa}, and duplicated using Scheme. The result is
465 imported in a @code{\score} by means of a second variable
468 traLaLa = \notes @{ c'4 d'4 @}
470 #(define newLa (map ly:music-deep-copy
471 (list traLaLa traLaLa)))
473 (make-sequential-music newLa))
478 In the above example, music expressions can be `exported' from the
479 input to the Scheme interpreter. The opposite is also possible. By
480 wrapping a Scheme value in the function @code{ly:export}, a Scheme
481 value is interpreted as if it were entered in LilyPond syntax: instead
482 of defining @code{\twice}, the example above could also have been
486 \score @{ #(ly:export (make-sequential-music newLa)) @}
493 @node Scheme datatypes
494 @subsection Scheme datatypes
496 Scheme is used to glue together different program modules. To aid this
497 glue function, many lilypond specific object types can be passed as
500 The following list are all lilypond specific types, that
501 can exist during parsing:
508 @item Music_output_def
515 During a run, transient objects are also created and destroyed.
518 @item Grob: short for `Graphical object'.
519 @item Scheme_hash_table
522 @item Molecule: Device-independent page output object,
523 including dimensions.
529 @item Translator: An object that produces audio objects or Grobs. This is
530 not yet user-accessible.
532 @item Font_metric: An object representing a font.
535 Many functions are defined to manipulate these data structures. They
536 are all listed and documented in the internals manual, see
537 @internalsref{All scheme functions}.
541 @subsection Assignments
544 Identifiers allow objects to be assigned to names during the parse
545 stage. To assign an identifier, use @var{name}@code{=}@var{value}.
546 To refer to an identifier, precede its name with a backslash:
547 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
548 the input-types listed above. Identifier assignments can appear at top
549 level in the LilyPond file, but also in @code{\paper} blocks.
551 An identifier can be created with any string for its name, but you will
552 only be able to refer to identifiers whose names begin with a letter,
553 being entirely alphabetical. It is impossible to refer to an identifier
554 whose name is the same as the name of a keyword.
556 The right hand side of an identifier assignment is parsed completely
557 before the assignment is done, so it is allowed to redefine an
558 identifier in terms of its old value, e.g.
564 When an identifier is referenced, the information it points to is
565 copied. For this reason, an identifier reference must always be the
566 first item in a block.
571 \paperIdent % wrong and invalid
577 \paperIdent % correct
584 @node Music storage format
585 @section Music storage format
588 * Music expressions::
589 * Internal music representation::
590 * Manipulating music expressions::
593 @node Music expressions
594 @subsection Music expressions
595 @cindex music expressions
597 Music in LilyPond is entered as a music expression. Notes, rests, lyric
598 syllables are music expressions, and you can combine music expressions
599 to form new ones, for example by enclosing a list of expressions in
600 @code{\sequential @{ @}} or @code{< >}. In the following example, a
601 compound expression is formed out of the quarter note @code{c} and a
602 quarter note @code{d}:
605 \sequential @{ c4 d4 @}
608 @cindex Sequential music
609 @cindex @code{\sequential}
610 @cindex sequential music
613 @cindex Simultaneous music
614 @cindex @code{\simultaneous}
616 The two basic compound music expressions are simultaneous and
620 \sequential @code{@{} @var{musicexprlist} @code{@}}
621 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
624 For both, there is a shorthand:
627 @code{@{} @var{musicexprlist} @code{@}}
634 @code{<} @var{musicexprlist} @code{>}
638 for simultaneous music.
639 In principle, the way in which you nest sequential and simultaneous to
640 produce music is not relevant. In the following example, three chords
641 are expressed in two different ways:
643 @lilypond[fragment,verbatim,center,quote]
644 \notes \context Voice {
645 <a c'> <b d'> <c' e'>
646 < { a b c' } { c' d' e' } >
649 However, using @code{<} and @code{>} for entering chords leads to
650 various peculiarities. For this reason, a special syntax
651 for chords was introduced in version 1.7: @code{<< >>}.
657 Other compound music expressions include
660 \transpose @var{from} @var{to} @var{expr}
661 \apply @var{func} @var{expr}
662 \context @var{type} = @var{id} @var{expr}
663 \times @var{fraction} @var{expr}
666 @node Internal music representation
667 @subsection Internal music representation
674 @node Manipulating music expressions
675 @subsection Manipulating music expressions
677 When a music expression is parsed, it is converted into a set of
678 Scheme music objects. The defining property of a music object is that
679 it takes up time. Time is a rational number that measures the length
680 of a piece of music, in whole notes.
682 A music object has three kinds of types
685 Music name: each music expression has a name, for example, a note
686 leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
687 a @internalsref{SimultaneousMusic}. A list of all expressions
688 available is in the internals manual, under @internalsref{Music
692 Each music name has several `types' or interface. For example, a
693 note is an @code{event}, but it is also a @code{note-event}, a
694 @code{rhythmic-event} and a @code{melodic-event}.
696 All classes of music are listed in the internals manual, under
697 @internalsref{Music classes}.
699 Each music object is represented by a C++ object. may be represented
700 by different C++ classes. For technical reasons, different music
701 objects may be represented by different C++ object types. For example,
702 a note is @code{Event} object, while @code{\grace} creates a
703 @code{Grace_music} object.
705 The distinctions between different C++ types will disappear in the
709 The actual information of a music expression is stored in properties.
710 For example, a @internalsref{NoteEvent} has @code{pitch} and
711 @code{duration} properties that store the pitch and duration of that
712 note. A list of all properties available is in the internals manual,
713 under @internalsref{Music properties}.
715 A compound music expresssion is a music object that contains other
716 music objects in its properties. A list of objects can be stored in
717 the @code{elements} property of a music object, or a single `child'
718 music object is stored in the @code{element} object. For example,
719 @internalsref{SequentialMusic} has its children in @code{elements},
720 and @internalsref{GraceMusic} has its single argument in
721 @code{element}. The body of a repeat is in @code{element} property of
722 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
724 These properties and objects can be directly accessed and manipulated,
725 through the @code{\apply} mechanism. Scheme functions can read and
726 write properties using the functions @code{ly:get-music-property} and
727 @code{ly:set-music-property!}.
729 The syntax for @code{\apply}
731 \apply #@var{func} @var{music}
735 This means that the scheme function @var{func} is called with
736 @var{music} as its argument. The return value of @var{func} is the
737 result of the entire expresssion.
739 An example is a function that reverses the order of elements in
742 #(define (rev-music-1 m)
743 (ly:set-music-property! 'elements (reverse
744 (ly:get-music-property mus 'elements)))
746 \apply #rev-music-1 @{ c4 d4 @}
749 The use of such a function is very limited. The effect of this
750 function is void, when it is applied to an argument which is does not
751 have multiple children, for example
754 \apply #rev-music-1 \grace @{ c4 d4 @}
758 does not do anything: @code{\grace} is stored as
759 @internalsref{GraceMusic}, which has no @code{elements}, only a single
760 @code{element}. Every generally applicable function for @code{\apply}
761 must --like music expressions themselves-- be recursive.
763 The following example is such a recursive function: it first extracts
764 the @code{elements} of an expression, reverses them and puts them
765 back. Then it recurses, both on @code{elements} and @code{element}
768 #(define (reverse-music music)
769 (let* ((elements (ly:get-mus-property music 'elements))
770 (child (ly:get-mus-property music 'element))
771 (reversed (reverse elements)))
774 (ly:set-mus-property! music 'elements reversed)
777 (if (ly:music? child) (reverse-music child))
778 (map reverse-music reversed)
783 A slightly more elaborate example is in
784 @inputfileref{input/test,reverse-music.ly}.
786 Some of the input syntax is also implemented as recursive music
787 functions. For example, the syntax for polyphony
793 is actually implemented as a recursive function that replaces the
794 above by the internal equivalent of
796 < \context Voice = "1" @{ \voiceOne a @}
797 \context Voice = "2" @{ \voiceTwo a @} >
800 Other applications of @code{\apply} are writing out repeats
801 automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
802 saving keystrokes (@inputfileref{input/test,music-box.ly}) and
804 LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
808 @file{scm/music-functions.scm}, @file{scm/music-types.scm},
809 @inputfileref{input/test,add-staccato.ly},
810 @inputfileref{input/test,duration-check.ly}.
811 @inputfileref{input/test,unfold-all-repeats.ly},
812 @inputfileref{input/test,music-box.ly}.
814 @node Lexical details
815 @section Lexical details
826 Begins and ends with the @code{"} character. To include a @code{"}
827 character in a string write @code{\"}. Various other backslash
828 sequences have special interpretations as in the C language. A string
829 that contains no spaces can be written without the quotes. Strings can
830 be concatenated with the @code{+} operator.
835 @section Output details
837 LilyPond's default output format is @TeX{}. Using the option @option{-f}
838 (or @option{--format}) other output formats can be selected also, but
839 currently none of them reliably work.
841 At the beginning of the output file, various global parameters are defined.
842 It also contains a large @code{\special} call to define PostScript routines
843 to draw items not representable with @TeX{}, mainly slurs and ties. A DVI
844 driver must be able to understand such embedded PostScript, or the output
845 will be rendered incompletely.
847 Then the file @file{lilyponddefs.tex} is loaded to define the macros used
848 in the code which follows. @file{lilyponddefs.tex} includes various other
849 files, partially depending on the global parameters.
851 Now the music is output system by system (a `system' consists of all
852 staves belonging together). From @TeX{}'s point of view, a system is an
853 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
854 vertically on the baseline of the text. Between systems,
855 @code{\interscoreline} is inserted vertically to have stretchable space.
856 The horizontal dimension of the @code{\hbox} is given by the
857 @code{linewidth} parameter from LilyPond's @code{\paper} block.
860 After the last system LilyPond emits a stronger variant of
861 @code{\interscoreline} only if the macro
862 @code{\lilypondpaperlastpagefill} is not defined (flushing the systems
863 to the top of the page). You can avoid that by setting the variable
864 @code{lastpagefill} in LilyPond's @code{\paper} block.
866 It is possible to fine-tune the vertical offset further by defining the
867 macro @code{\lilypondscoreshift}. Example:
870 \def\lilypondscoreshift@{0.25\baselineskip@}
874 @code{\baselineskip} is the distance from one text line to the next.
876 The code produced by LilyPond should be run through La@TeX{}, not
879 Here an example how to embed a small LilyPond file @code{foo.ly} into
880 running La@TeX{} text without using the @code{lilypond-book} script
881 (@pxref{Integrating text and music with lilypond-book}).
884 \documentclass@{article@}
886 \def\lilypondpaperlastpagefill@{@}
888 \def\lilypondscoreshift@{0.25\baselineskip@}
891 This is running text which includes an example music file
897 The file @file{foo.tex} has been simply produced with
903 It is important to set the @code{indent} parameter to zero in the
904 @code{\paper} block of @file{foo.ly}.
906 The call to @code{\lineskip} assures that there is enough vertical space
907 between the LilyPond box and the surrounding text lines.