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 @cindex @code{Current}
289 If you don't wish to specify the name of the context in the
290 @code{\property}-expression
291 itself, you can refer to the abstract context name,
292 @code{Current}. The @code{Current} context is the latest
293 used context. This will typically mean the @internalsref{Thread}
294 context, but you can force another context with the
295 @code{\property}-command. Hence the expressions
298 \property @var{contextname}.@var{propname} = @var{value}
304 \context @var{contextname}
305 \property Current.@var{propname} = @var{value}
309 The main use for this is in macros - allowing the specification of a
310 property-setting without restriction to a specific context.
312 Properties can be unset using the following expression:
314 \property @var{contextname}.@var{propname} \unset
317 @cindex properties, unsetting
318 @cindex @code{\unset}
320 This removes the definition of @var{propname} in @var{contextname}. If
321 @var{propname} was not defined in @var{contextname} (but was inherited
322 from a higher context), then this has no effect.
327 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
328 the inverse of @code{\property \set}.
330 @node Engravers and performers
331 @subsection Engravers and performers
335 Basic building blocks of translation are called engravers; they are
340 @node Changing context definitions
341 @subsection Changing context definitions
343 @cindex context definition
344 @cindex translator definition
346 The most common way to define a context is by extending an existing
347 context. You can change an existing context from the paper block, by
348 first initializing a translator with an existing context identifier:
352 @var{context-identifier}
355 Then you can add and remove engravers using the following syntax:
357 \remove @var{engravername}
358 \consists @var{engravername}
362 Here @var{engravername} is a string, the name of an engraver in the
366 @lilypond[verbatim,singleline]
370 \translator { \StaffContext
371 \remove Clef_engraver
377 You can also set properties in a translator definition. The syntax is as
380 @var{propname} = @var{value}
381 @var{propname} \set @var{grob-propname} = @var{pvalue}
382 @var{propname} \override @var{grob-propname} = @var{pvalue}
383 @var{propname} \revert @var{grob-propname}
385 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
386 and @code{pvalue} are Scheme expressions. These type of property
387 assignments happen before interpretation starts, so a @code{\property}
388 command will override any predefined settings.
391 To simplify editing translators, all standard contexts have standard
392 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
393 @code{VoiceContext}, see @file{ly/engraver-init.ly}.
395 @node Defining new contexts
396 @subsection Defining new contexts
398 If you want to build a context from scratch, you must also supply the
399 following extra information:
401 @item A name, specified by @code{\name @var{contextname}}.
403 @item A cooperation module. This is specified by @code{\type
410 \type "Engraver_group_engraver"
413 \consists "Staff_symbol_engraver"
414 \consists "Note_head_engraver"
415 \consistsend "Axis_group_engraver"
419 The argument of @code{\type} is the name for a special engraver that
420 handles cooperation between simple engravers such as
421 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
422 for this engraver are the following:
424 @cindex @code{Engraver_group_engraver}
425 @item @code{Engraver_group_engraver}
426 The standard cooperation engraver.
428 @cindex @code{Score_engraver}
430 @item @code{Score_engraver}
431 This is cooperation module that should be in the top level context,
432 and only the top level context.
439 @item @code{\alias} @var{alternate-name}
440 This specifies a different name. In the above example,
441 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
443 @item @code{\consistsend} @var{engravername}
444 Analogous to @code{\consists}, but makes sure that
445 @var{engravername} is always added to the end of the list of
448 Some engraver types need to be at the end of the list; this
449 insures they stay there even if a user adds or removes engravers.
450 End-users generally don't need this command.
452 @item @code{\accepts} @var{contextname}
453 Add @var{contextname} to the list of contexts this context can
454 contain in the context hierarchy. The first listed context is the
455 context to create by default.
457 @item @code{\denies}. The opposite of @code{\accepts}. Added for
458 completeness, but is never used in practice.
461 @item @code{\name} @var{contextname}
462 This sets the type name of the context, e.g. @internalsref{Staff},
463 @internalsref{Voice}. If the name is not specified, the translator won't do
467 In the @code{\paper} block, it is also possible to define translator
468 identifiers. Like other block identifiers, the identifier can only
469 be used as the very first item of a translator. In order to define
470 such an identifier outside of @code{\score}, you must do
475 foo = \translator @{ @dots{} @}
482 \translator @{ \foo @dots{} @}
490 @cindex paper types, engravers, and pre-defined translators
493 @node Syntactic details
494 @section Syntactic details
495 @cindex Syntactic details
497 This section describes details that were too boring to be put elsewhere.
501 * Music expressions::
502 * Manipulating music expressions::
511 @subsection Identifiers
515 What has this section got to do with identifiers?
516 It seems more appropriate in the introduction to Chapter 4,
522 All of the information in a LilyPond input file, is internally
523 represented as a Scheme value. In addition to normal Scheme data types
524 (such as pair, number, boolean, etc.), LilyPond has a number of
525 specialized data types,
536 @item Music_output_def
537 @item Moment (rational number)
540 LilyPond also includes some transient object types. Objects of these
541 types are built during a LilyPond run, and do not `exist' per se within
542 your input file. These objects are created as a result of your input
543 file, so you can include commands in the input to manipulate them,
544 during a lilypond run.
547 @item Grob: short for Graphical object.
548 @item Molecule: device-independent page output object,
549 including dimensions. Produced by some Grob functions
550 @item Translator: object that produces audio objects or Grobs. This is
551 not yet user accessible.
552 @item Font_metric: object representing a font.
556 @node Music expressions
557 @subsection Music expressions
559 @cindex music expressions
561 Music in LilyPond is entered as a music expression. Notes, rests, lyric
562 syllables are music expressions, and you can combine music expressions
563 to form new ones, for example by enclosing a list of expressions in
564 @code{\sequential @{ @}} or @code{< >}. In the following example, a
565 compound expression is formed out of the quarter note @code{c} and a
566 quarter note @code{d}:
569 \sequential @{ c4 d4 @}
572 @cindex Sequential music
573 @cindex @code{\sequential}
574 @cindex sequential music
577 @cindex Simultaneous music
578 @cindex @code{\simultaneous}
580 The two basic compound music expressions are simultaneous and
584 \sequential @code{@{} @var{musicexprlist} @code{@}}
585 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
587 For both, there is a shorthand:
589 @code{@{} @var{musicexprlist} @code{@}}
593 @code{<} @var{musicexprlist} @code{>}
595 for simultaneous music.
596 In principle, the way in which you nest sequential and simultaneous to
597 produce music is not relevant. In the following example, three chords
598 are expressed in two different ways:
600 @lilypond[fragment,verbatim,center]
601 \notes \context Voice {
602 <a c'> <b d' > <c' e'>
603 < { a b c' } { c' d' e' } >
608 Other compound music expressions include
611 \transpose @var{pitch} @var{expr}
612 \apply @var{func} @var{expr}
613 \context @var{type} = @var{id} @var{expr}
614 \times @var{fraction} @var{expr}
618 @c . {Manipulating music expressions}
619 @node Manipulating music expressions
620 @subsection Manipulating music expressions
622 The @code{\apply} mechanism gives you access to the internal
623 representation of music. You can write Scheme-functions that operate
624 directly on it. The syntax is
626 \apply #@var{func} @var{music}
628 This means that @var{func} is applied to @var{music}. The function
629 @var{func} should return a music expression.
631 This example replaces the text string of a script. It also shows a dump
632 of the music it processes, which is useful if you want to know more
633 about how music is stored.
635 @lilypond[verbatim,singleline]
636 #(define (testfunc x)
637 (if (equal? (ly-get-mus-property x 'text) "foo")
638 (ly-set-mus-property! x 'text "bar"))
640 (ly-set-mus-property! x 'elements
641 (map testfunc (ly-get-mus-property x 'elements)))
646 \apply #testfunc { c'4_"foo" }
650 For more information on what is possible, see the automatically
651 generated documentation.
654 Directly accessing internal representations is dangerous: the
655 implementation is subject to changes, so you should avoid this feature
658 A final example is a function that reverses a piece of music in time:
660 @lilypond[verbatim,singleline]
661 #(define (reverse-music music)
662 (let* ((elements (ly-get-mus-property music 'elements))
663 (reversed (reverse elements))
664 (span-dir (ly-get-mus-property music 'span-direction)))
665 (ly-set-mus-property! music 'elements reversed)
667 (ly-set-mus-property! music 'span-direction (- span-dir)))
668 (map reverse-music reversed)
671 music = \notes { c'4 d'4( e'4 f'4 }
673 \score { \context Voice {
675 \apply #reverse-music \music
680 More examples are given in the distributed example files in
689 @subsection Span requests
690 @cindex Span requests
692 Notational constructs that start and end on different notes can be
693 entered using span requests. The syntax is as follows:
697 \spanrequest @var{startstop} @var{type}
701 @cindex @code{\start}
704 This defines a spanning request. The @var{startstop} parameter is either
705 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
706 describes what should be started. Much of the syntactic sugar is a
707 shorthand for @code{\spanrequest}, for example,
709 @lilypond[fragment,verbatim,center]
710 c'4-\spanrequest \start "slur"
711 c'4-\spanrequest \stop "slur"
714 Among the supported types are @code{crescendo}, @code{decrescendo},
715 @code{beam}, @code{slur}. This is an internal command. Users are
716 encouraged to use the shorthands which are defined in the initialization
717 file @file{spanners.ly}.
722 @subsection Assignments
725 Identifiers allow objects to be assigned to names during the parse
726 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
727 and to refer to an identifier, you precede its name with a backslash:
728 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
729 the input-types listed above. Identifier assignments can appear at top
730 level in the LilyPond file, but also in @code{\paper} blocks.
732 An identifier can be created with any string for its name, but you will
733 only be able to refer to identifiers whose names begin with a letter,
734 being entirely alphabetical. It is impossible to refer to an identifier
735 whose name is the same as the name of a keyword.
737 The right hand side of an identifier assignment is parsed completely
738 before the assignment is done, so it is allowed to redefine an
739 identifier in terms of its old value, e.g.
745 When an identifier is referenced, the information it points to is
746 copied. For this reason, an identifier reference must always be the
747 first item in a block.
751 \paperIdent % wrong and invalid
755 \paperIdent % correct
762 @subsection Lexical modes
763 @cindex Lexical modes
766 @cindex @code{\notes}
767 @cindex @code{\chords}
768 @cindex @code{\lyrics}
770 To simplify entering notes, lyrics, and chords, LilyPond has three
771 special input modes in addition to the default mode: note, lyrics and
772 chords mode. These input modes change the way that normal, unquoted
773 words are interpreted: for example, the word @code{cis} may be
774 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
775 major triad respectively.
777 A mode switch is entered as a compound music expression
779 @code{\notes} @var{musicexpr}
780 @code{\chords} @var{musicexpr}
781 @code{\lyrics} @var{musicexpr}.
784 In each of these cases, these expressions do not add anything to the
785 meaning of their arguments. They just instruct the parser in what mode
786 to parse their arguments.
788 Different input modes may be nested.
792 @subsection Ambiguities
797 The grammar contains a number of ambiguities. We hope to resolve them at
806 is interpreted as the string identifier assignment. However,
807 it can also be interpreted as making a string identifier @code{\foo}
808 containing @code{"bar"}, or a music identifier @code{\foo} containing
809 the syllable `bar'. The former interpretation is chosen.
811 @item If you do a nested repeat like
823 then it is ambiguous to which @code{\repeat} the
824 @code{\alternative} belongs. This is the classic if-then-else
825 dilemma. It may be solved by using braces.
829 @c . {Lexical details}
830 @node Lexical details
831 @section Lexical details
833 Even more boring details, now on lexical side of the input parser.
843 @subsection Direct Scheme
847 @cindex Scheme, in-line code
853 @cindex accessing Scheme
854 @cindex evaluating Scheme
857 LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
858 language from the LISP family. You can learn more about Scheme at
859 @uref{http://www.scheme.org}. It is used to represent data throughout
860 the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
861 code following the hash-sign is evaluated as Scheme. The boolean value
862 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
865 LilyPond contains a Scheme interpreter (the GUILE library) for
866 internal use. In some places, Scheme expressions also form valid syntax:
867 wherever it is allowed,
871 evaluates the specified Scheme code. Example:
873 \property Staff.TestObject \override #'foobar = #(+ 1 2)
875 @code{\override} expects two Scheme expressions, so there are two Scheme
876 expressions. The first one is a symbol (@code{foobar}), the second one
877 an integer (namely, 3).
879 In-line scheme may be used at the top level. In this case the result is
882 Scheme is a full-blown programming language, and a full discussion is
883 outside the scope of this document. Interested readers are referred to
884 the website @uref{http://www.schemers.org/} for more information on
892 Formed from an optional minus sign and a sequence of digits followed
893 by a @emph{required} decimal point and an optional exponent such as
894 @code{-1.2e3}. Reals can be built up using the usual operations:
895 `@code{+}', `@code{-}', `@code{*}', and
896 `@code{/}', with parentheses for grouping.
904 A real constant can be followed by one of the dimension keywords:
905 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
906 points, inches and centimeters, respectively. This converts the number
907 a number that is the internal representation of that dimension.
915 Begins and ends with the @code{"} character. To include a @code{"}
916 character in a string write @code{\"}. Various other backslash
917 sequences have special interpretations as in the C language. A string
918 that contains no spaces can be written without the quotes. Strings can
919 be concatenated with the @code{+} operator.