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 translating the input to notation, there are number of distinct
15 phases. We list them here:
17 @c todo: moved from refman.
19 The purpose of LilyPond is explained informally by the term `music
20 typesetter'. This is not a fully correct name: not only does the
21 program print musical symbols, it also makes aesthetic decisions.
22 Symbols and their placements are @emph{generated} from a high-level
23 musical description. In other words, LilyPond would be best described
24 by `music compiler' or `music to notation compiler'.
26 LilyPond is linked to GUILE, GNU's Scheme library for extension
27 programming. The Scheme library provides the glue that holds together
28 the low-level routines and separate modules which are written in C++.
30 When lilypond is run to typeset sheet music, the following happens:
32 @item GUILE Initialization: various scheme files are read
33 @item parsing: first standard @code{ly} initialization files are read, and
34 then the user @file{ly} file is read.
35 @item interpretation: the music in the file is processed ``in playing
36 order'', i.e. the order that you use to read sheet music, or the
37 order in which notes are played. The result of this step is a typesetting
41 The typesetting specification is solved: positions and formatting is
44 @item the visible results ("virtual ink") are written to the output file.
47 During these stages different types of data play the the main role:
48 during parsing, @strong{Music} objects are created. During the
49 interpretation, @strong{contexts} are constructed, and with these
50 contexts a network of @strong{graphical objects} (``grobs'') is
51 created. These grobs contain unknown variables, and the network forms a
52 set of equations. After solving the equations and filling in these
53 variables, the printed output is written to an output file.
55 These threemanship of tasks (parsing, translating, typesetting) and
56 data-structures (music, context, graphical objects) permeates the entire
57 design of the program.
65 The LY file is read, and converted to a list of @code{Scores}, which
66 each contain @code{Music} and paper/midi-definitions. Here @code{Music},
67 @code{Pitch} and @code{Duration} objects are created.
69 @item Interpreting music
70 @cindex interpreting music
72 All music events are "read" in the same order as they would be played
73 (or read from paper). At every step of the interpretation, musical
74 events are delivered to
75 interpretation contexts,
77 which use them to build @code{Grob}s (or MIDI objects, for MIDI output).
79 In this stage @code{Music_iterators} do a traversal of the @code{Music}
80 structure. The music events thus encountered are reported to
81 @code{Translator}s, a set of objects that collectively form interpretation
89 At places where line breaks may occur, clefs and bars are prepared for
90 a possible line break.
96 In this stage, all information that is needed to determine line breaking
99 @item Break calculation:
101 The lines and horizontal positions of the columns are determined.
105 Relations between all grobs are modified to reflect line breaks: When a
106 spanner, e.g. a slur, crosses a line-break, then the spanner is "broken
107 into pieces", for every line that the spanner is in, a copy of the grob
108 is made. A substitution process redirects all grob-reference so that
109 each spanner grob will only reference other grobs in the same line.
113 All vertical dimensions and spanning objects are computed, and all grobs
114 are output, line by line. The output is encoded in the form of
119 The data types that are mentioned here are all discussed in this
124 @c FIXME: Note entry vs Music entry at top level menu is confusing.
127 * Interpretation context::
128 * Syntactic details::
133 @node Interpretation context
134 @section Interpretation context
137 * Creating contexts::
139 * Context properties::
140 * Engravers and performers::
141 * Changing context definitions::
142 * Defining new contexts::
146 Interpretation contexts are objects that only exist during a run of
147 LilyPond. During the interpretation phase of LilyPond (when it prints
148 "interpreting music"), the music expression in a @code{\score} block is
149 interpreted in time order. This is the same order that humans hear and
152 During this interpretation, the interpretation context holds the
153 state for the current point within the music. It contains information
157 @item What notes are playing at this point?
158 @item What symbols will be printed at this point?
159 @item What is the current key signature, time signature, point within
163 Contexts are grouped hierarchically: A @internalsref{Voice} context is
164 contained in a @internalsref{Staff} context (because a staff can contain
165 multiple voices at any point), a @internalsref{Staff} context is contained in
166 @internalsref{Score}, @internalsref{StaffGroup}, or @internalsref{ChoirStaff} context.
168 Contexts associated with sheet music output are called @emph{notation
169 contexts}, those for sound output are called @emph{performance
170 contexts}. The default definitions of the standard notation and
171 performance contexts can be found in @file{ly/engraver-init.ly} and
172 @file{ly/performer-init.ly}, respectively.
174 @node Creating contexts
175 @subsection Creating contexts
177 @cindex @code{\context}
178 @cindex context selection
180 Contexts for a music expression can be selected manually, using the
181 following music expression.
184 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
187 This instructs lilypond to interpret @var{musicexpr} within the context
188 of type @var{contexttype} and with name @var{contextname}. If this
189 context does not exist, it will be created.
191 @lilypond[verbatim,singleline]
193 \notes \relative c'' {
194 c4 <d4 \context Staff = "another" e4> f
200 In this example, the @code{c} and @code{d} are printed on the
201 default staff. For the @code{e}, a context Staff called
202 @code{another} is specified; since that does not exist, a new
203 context is created. Within @code{another}, a (default) Voice context
204 is created for the @code{e4}. When all music referring to a
205 context is finished, the context is ended as well. So after the
206 third quarter, @code{another} is removed.
210 @node Default contexts
211 @subsection Default contexts
213 Most music expressions don't need an explicit @code{\context}
214 declaration: they inherit the
215 notation context from their parent. Each note is a music expression, and
216 as you can see in the following example, only the sequential music
217 enclosing the three notes has an explicit context.
219 @lilypond[verbatim,singleline]
220 \score { \notes \context Voice = goUp { c'4 d' e' } }
223 There are some quirks that you must keep in mind when dealing with
226 First, every top level music is interpreted by the Score context, in other
227 words, you may think of @code{\score} working like
230 \context Score @var{music}
234 Second, contexts are created automatically to be able to interpret the
235 music expressions. Consider the following example.
237 @lilypond[verbatim, singleline]
238 \score { \context Score \notes { c'4 ( d' )e' } }
241 The sequential music is interpreted by the Score context initially
242 (notice that the @code{\context} specification is redundant), but when a
243 note is encountered, contexts are setup to accept that note. In this
244 case, a Thread, Voice and Staff are created. The rest of the sequential
245 music is also interpreted with the same Thread, Voice and Staff context,
246 putting the notes on the same staff, in the same voice.
248 This is a convenient mechanism, but do not expect opening chords to work
249 without @code{\context}. For every note, a separate staff is
252 @cindex explicit context
253 @cindex starting with chords
254 @cindex chords, starting with
256 @lilypond[verbatim, singleline]
257 \score { \notes <c'4 es'> }
260 Of course, if the chord is preceded by a normal note in sequential
261 music, the chord will be interpreted by the Thread of the preceding
263 @lilypond[verbatim,singleline]
264 \score { \notes { c'4 <c'4 es'> } }
269 @node Context properties
270 @subsection Context properties
272 Notation contexts have properties. These properties are from
273 the @file{.ly} file using the following expression:
274 @cindex @code{\property}
276 \property @var{contextname}.@var{propname} = @var{value}
279 Sets the @var{propname} property of the context @var{contextname} to the
280 specified Scheme expression @var{value}. All @var{propname} and
281 @var{contextname} are strings, which are typically unquoted.
283 Properties that are set in one context are inherited by all of the
284 contained contexts. This means that a property valid for the
285 @internalsref{Voice} context can be set in the @internalsref{Score} context (for
286 example) and thus take effect in all @internalsref{Voice} contexts.
288 Properties can be unset using the following expression:
290 \property @var{contextname}.@var{propname} \unset
293 @cindex properties, unsetting
294 @cindex @code{\unset}
296 This removes the definition of @var{propname} in @var{contextname}. If
297 @var{propname} was not defined in @var{contextname} (but was inherited
298 from a higher context), then this has no effect.
303 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
304 the inverse of @code{\property \set}.
306 @node Engravers and performers
307 @subsection Engravers and performers
311 Basic building blocks of translation are called engravers; they are
316 @node Changing context definitions
317 @subsection Changing context definitions
319 @cindex context definition
320 @cindex translator definition
322 The most common way to define a context is by extending an existing
323 context. You can change an existing context from the paper block, by
324 first initializing a translator with an existing context identifier:
328 @var{context-identifier}
331 Then you can add and remove engravers using the following syntax:
333 \remove @var{engravername}
334 \consists @var{engravername}
338 Here @var{engravername} is a string, the name of an engraver in the
342 @lilypond[verbatim,singleline]
346 \translator { \StaffContext
347 \remove Clef_engraver
353 You can also set properties in a translator definition. The syntax is as
356 @var{propname} = @var{value}
357 @var{propname} \set @var{grob-propname} = @var{pvalue}
358 @var{propname} \override @var{grob-propname} = @var{pvalue}
359 @var{propname} \revert @var{grob-propname}
361 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
362 and @code{pvalue} are Scheme expressions. These type of property
363 assignments happen before interpretation starts, so a @code{\property}
364 command will override any predefined settings.
367 To simplify editing translators, all standard contexts have standard
368 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
369 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
371 @node Defining new contexts
372 @subsection Defining new contexts
374 If you want to build a context from scratch, you must also supply the
375 following extra information:
377 @item A name, specified by @code{\name @var{contextname}}.
379 @item A cooperation module. This is specified by @code{\type
386 \type "Engraver_group_engraver"
389 \consists "Staff_symbol_engraver"
390 \consists "Note_head_engraver"
391 \consistsend "Axis_group_engraver"
395 The argument of @code{\type} is the name for a special engraver that
396 handles cooperation between simple engravers such as
397 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
398 for this engraver are the following:
400 @cindex @code{Engraver_group_engraver}
401 @item @code{Engraver_group_engraver}
402 The standard cooperation engraver.
404 @cindex @code{Score_engraver}
406 @item @code{Score_engraver}
407 This is cooperation module that should be in the top level context,
408 and only the top level context.
415 @item @code{\alias} @var{alternate-name}
416 This specifies a different name. In the above example,
417 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
419 @item @code{\consistsend} @var{engravername}
420 Analogous to @code{\consists}, but makes sure that
421 @var{engravername} is always added to the end of the list of
424 Some engraver types need to be at the end of the list; this
425 insures they stay there even if a user adds or removes engravers.
426 End-users generally don't need this command.
428 @item @code{\accepts} @var{contextname}
429 Add @var{contextname} to the list of contexts this context can
430 contain in the context hierarchy. The first listed context is the
431 context to create by default.
433 @item @code{\denies}. The opposite of @code{\accepts}. Added for
434 completeness, but is never used in practice.
437 @item @code{\name} @var{contextname}
438 This sets the type name of the context, e.g. @internalsref{Staff},
439 @internalsref{Voice}. If the name is not specified, the translator won't do
443 In the @code{\paper} block, it is also possible to define translator
444 identifiers. Like other block identifiers, the identifier can only
445 be used as the very first item of a translator. In order to define
446 such an identifier outside of @code{\score}, you must do
451 foo = \translator @{ @dots{} @}
458 \translator @{ \foo @dots{} @}
466 @cindex paper types, engravers, and pre-defined translators
469 @node Syntactic details
470 @section Syntactic details
471 @cindex Syntactic details
473 This section describes details that were too boring to be put elsewhere.
477 * Music expressions::
478 * Manipulating music expressions::
487 @subsection Identifiers
491 What has this section got to do with identifiers?
492 It seems more appropriate in the introduction to Chapter 4,
498 All of the information in a LilyPond input file, is internally
499 represented as a Scheme value. In addition to normal Scheme data types
500 (such as pair, number, boolean, etc.), LilyPond has a number of
501 specialized data types,
512 @item Music_output_def
513 @item Moment (rational number)
516 LilyPond also includes some transient object types. Objects of these
517 types are built during a LilyPond run, and do not `exist' per se within
518 your input file. These objects are created as a result of your input
519 file, so you can include commands in the input to manipulate them,
520 during a lilypond run.
523 @item Grob: short for Graphical object.
524 @item Molecule: device-independent page output object,
525 including dimensions. Produced by some Grob functions
526 @item Translator: object that produces audio objects or Grobs. This is
527 not yet user accessible.
528 @item Font_metric: object representing a font.
532 @node Music expressions
533 @subsection Music expressions
535 @cindex music expressions
537 Music in LilyPond is entered as a music expression. Notes, rests, lyric
538 syllables are music expressions, and you can combine music expressions
539 to form new ones, for example by enclosing a list of expressions in
540 @code{\sequential @{ @}} or @code{< >}. In the following example, a
541 compound expression is formed out of the quarter note @code{c} and a
542 quarter note @code{d}:
545 \sequential @{ c4 d4 @}
548 @cindex Sequential music
549 @cindex @code{\sequential}
550 @cindex sequential music
553 @cindex Simultaneous music
554 @cindex @code{\simultaneous}
556 The two basic compound music expressions are simultaneous and
560 \sequential @code{@{} @var{musicexprlist} @code{@}}
561 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
563 For both, there is a shorthand:
565 @code{@{} @var{musicexprlist} @code{@}}
569 @code{<} @var{musicexprlist} @code{>}
571 for simultaneous music.
572 In principle, the way in which you nest sequential and simultaneous to
573 produce music is not relevant. In the following example, three chords
574 are expressed in two different ways:
576 @lilypond[fragment,verbatim,center]
577 \notes \context Voice {
578 <a c'> <b d' > <c' e'>
579 < { a b c' } { c' d' e' } >
584 Other compound music expressions include
587 \transpose @var{pitch} @var{expr}
588 \apply @var{func} @var{expr}
589 \context @var{type} = @var{id} @var{expr}
590 \times @var{fraction} @var{expr}
594 @c . {Manipulating music expressions}
595 @node Manipulating music expressions
596 @subsection Manipulating music expressions
598 The @code{\apply} mechanism gives you access to the internal
599 representation of music. You can write Scheme-functions that operate
600 directly on it. The syntax is
602 \apply #@var{func} @var{music}
604 This means that @var{func} is applied to @var{music}. The function
605 @var{func} should return a music expression.
607 This example replaces the text string of a script. It also shows a dump
608 of the music it processes, which is useful if you want to know more
609 about how music is stored.
611 @lilypond[verbatim,singleline]
612 #(define (testfunc x)
613 (if (equal? (ly-get-mus-property x 'text) "foo")
614 (ly-set-mus-property! x 'text "bar"))
616 (ly-set-mus-property! x 'elements
617 (map testfunc (ly-get-mus-property x 'elements)))
622 \apply #testfunc { c'4_"foo" }
626 For more information on what is possible, see the automatically
627 generated documentation.
630 Directly accessing internal representations is dangerous: the
631 implementation is subject to changes, so you should avoid this feature
634 A final example is a function that reverses a piece of music in time:
636 @lilypond[verbatim,singleline]
637 #(define (reverse-music music)
638 (let* ((elements (ly-get-mus-property music 'elements))
639 (reversed (reverse elements))
640 (span-dir (ly-get-mus-property music 'span-direction)))
641 (ly-set-mus-property! music 'elements reversed)
643 (ly-set-mus-property! music 'span-direction (- span-dir)))
644 (map reverse-music reversed)
647 music = \notes { c'4 d'4( e'4 f'4 }
649 \score { \context Voice {
651 \apply #reverse-music \music
656 More examples are given in the distributed example files in
665 @subsection Span requests
666 @cindex Span requests
668 Notational constructs that start and end on different notes can be
669 entered using span requests. The syntax is as follows:
673 \spanrequest @var{startstop} @var{type}
677 @cindex @code{\start}
680 This defines a spanning request. The @var{startstop} parameter is either
681 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
682 describes what should be started. Much of the syntactic sugar is a
683 shorthand for @code{\spanrequest}, for example,
685 @lilypond[fragment,verbatim,center]
686 c'4-\spanrequest \start "slur"
687 c'4-\spanrequest \stop "slur"
690 Among the supported types are @code{crescendo}, @code{decrescendo},
691 @code{beam}, @code{slur}. This is an internal command. Users are
692 encouraged to use the shorthands which are defined in the initialization
693 file @file{spanners.ly}.
698 @subsection Assignments
701 Identifiers allow objects to be assigned to names during the parse
702 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
703 and to refer to an identifier, you precede its name with a backslash:
704 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
705 the input-types listed above. Identifier assignments can appear at top
706 level in the LilyPond file, but also in @code{\paper} blocks.
708 An identifier can be created with any string for its name, but you will
709 only be able to refer to identifiers whose names begin with a letter,
710 being entirely alphabetical. It is impossible to refer to an identifier
711 whose name is the same as the name of a keyword.
713 The right hand side of an identifier assignment is parsed completely
714 before the assignment is done, so it is allowed to redefine an
715 identifier in terms of its old value, e.g.
721 When an identifier is referenced, the information it points to is
722 copied. For this reason, an identifier reference must always be the
723 first item in a block.
727 \paperIdent % wrong and invalid
731 \paperIdent % correct
738 @subsection Lexical modes
739 @cindex Lexical modes
742 @cindex @code{\notes}
743 @cindex @code{\chords}
744 @cindex @code{\lyrics}
746 To simplify entering notes, lyrics, and chords, LilyPond has three
747 special input modes in addition to the default mode: note, lyrics and
748 chords mode. These input modes change the way that normal, unquoted
749 words are interpreted: for example, the word @code{cis} may be
750 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
751 major triad respectively.
753 A mode switch is entered as a compound music expression
755 @code{\notes} @var{musicexpr}
756 @code{\chords} @var{musicexpr}
757 @code{\lyrics} @var{musicexpr}.
760 In each of these cases, these expressions do not add anything to the
761 meaning of their arguments. They just instruct the parser in what mode
762 to parse their arguments.
764 Different input modes may be nested.
768 @subsection Ambiguities
773 The grammar contains a number of ambiguities. We hope to resolve them at
782 is interpreted as the string identifier assignment. However,
783 it can also be interpreted as making a string identifier @code{\foo}
784 containing @code{"bar"}, or a music identifier @code{\foo} containing
785 the syllable `bar'. The former interpretation is chosen.
787 @item If you do a nested repeat like
799 then it is ambiguous to which @code{\repeat} the
800 @code{\alternative} belongs. This is the classic if-then-else
801 dilemma. It may be solved by using braces.
805 @c . {Lexical details}
806 @node Lexical details
807 @section Lexical details
809 Even more boring details, now on lexical side of the input parser.
819 @subsection Direct Scheme
823 @cindex Scheme, in-line code
829 @cindex accessing Scheme
830 @cindex evaluating Scheme
833 LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
834 language from the LISP family. You can learn more about Scheme at
835 @uref{http://www.scheme.org}. It is used to represent data throughout
836 the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
837 code following the hash-sign is evaluated as Scheme. The boolean value
838 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
841 LilyPond contains a Scheme interpreter (the GUILE library) for
842 internal use. In some places, Scheme expressions also form valid syntax:
843 wherever it is allowed,
847 evaluates the specified Scheme code. Example:
849 \property Staff.TestObject \override #'foobar = #(+ 1 2)
851 @code{\override} expects two Scheme expressions, so there are two Scheme
852 expressions. The first one is a symbol (@code{foobar}), the second one
853 an integer (namely, 3).
855 In-line scheme may be used at the top level. In this case the result is
858 Scheme is a full-blown programming language, and a full discussion is
859 outside the scope of this document. Interested readers are referred to
860 the website @uref{http://www.schemers.org/} for more information on
868 Formed from an optional minus sign and a sequence of digits followed
869 by a @emph{required} decimal point and an optional exponent such as
870 @code{-1.2e3}. Reals can be built up using the usual operations:
871 `@code{+}', `@code{-}', `@code{*}', and
872 `@code{/}', with parentheses for grouping.
880 A real constant can be followed by one of the dimension keywords:
881 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
882 points, inches and centimeters, respectively. This converts the number
883 a number that is the internal representation of that dimension.
891 Begins and ends with the @code{"} character. To include a @code{"}
892 character in a string write @code{\"}. Various other backslash
893 sequences have special interpretations as in the C language. A string
894 that contains no spaces can be written without the quotes. Strings can
895 be concatenated with the @code{+} operator.