@c
@c A menu is needed before every deeper *section nesting of @nodes
@c Run M-x texinfo-all-menus-update
-@c to automagically fill in these menus
+@c to automatically fill in these menus
@c before saving changes
-@node Internals
-@chapter Internals
+@node Technical manual
+@chapter Technical manual
-When translating the input to notation, there are number of distinct
-phases. We list them here:
+When LilyPond is run, it reads music from a file, translates that into
+notation, and outputs the result to a file. The most important steps
+are the first three. Consequently, there are three important basic
+concepts within LilyPond: music, translation and layout. The
+following diagram illustrates the concepts, and list the terminology
+associated with each step.
-@table @b
-
-@item Parsing:
-
-The LY file is read, and converted to a list of @code{Scores}, which
-each contain @code{Music} and paper/midi-definitions. Here @code{Music},
-@code{Pitch} and @code{Duration} objects are created.
-
-@item Interpreting music
-@cindex interpreting music
-
-All music events are "read" in the same order as they would be played
-(or read from paper). At every step of the interpretation, musical
-events are delivered to
-interpretation contexts,
-@cindex engraver
-which use them to build @code{Grob}s (or MIDI objects, for MIDI output).
+
+@verbatim
-In this stage @code{Music_iterators} do a traversal of the @code{Music}
-structure. The music events thus encountered are reported to
-@code{Translator}s, a set of objects that collectively form interpretation
-contexts.
+ +-------------+ Translation +----------+
+ | | | |
+ | Music | ------------------> | Layout |
+ | | | |
+ +-------------+ +----------+
+
+
+Syntax: c4 \context \set #'padding =
+ \override
+
+Objects: Music expressions Contexts Layout object
+ Engravers (aka. Grob)
+
+Example objects: NoteEvent Voice NoteHead
+ Note_heads_engraver
+
+Example properties: #'pitch keySignature #'line-count
+User applications: none various tuning layout
-@item Prebreaking
+@end verbatim
-@cindex prebreaking
+The objects passed around in LilyPond have @emph{properties},
+variables that can contain many different types of information. Users
+can set these variables, to modify the default behavior. Since there
+are three different main concepts, there are also three types of
+properties:
-At places where line breaks may occur, clefs and bars are prepared for
-a possible line break.
+@cindex properties
+@cindex concepts, main
+@cindex context
+@cindex music expressions
+@cindex layout
+@cindex grob
-@item Preprocessing
-@cindex preprocessing
+@table @b
+@item Music properties
+These are used internally, and most users will not see or use them.
-In this stage, all information that is needed to determine line breaking
-is computed.
+They use Scheme-style naming, i.e. lowercase words separated with
+dashes: @code{pitch}, @code{tremolo-type}.
-@item Break calculation:
+@item Translation properties
+These influence the translation process, and most users will encounter them
+regularly. For example, beaming behavior is tuned with
+@code{autoBeamSettings}.
-The lines and horizontal positions of the columns are determined.
+These use mixed-caps naming: @code{autoBeamSettings},
+@code{ignoreMelismata}. They are assigned as follows:
+@example
+ \set ignoreMelismata = ...
+@end example
-@item Breaking
+@item Layout properties
+These are internally used in the formatting process. Consequently, to
+tune formatting details, it is necessary to adjust these
+properties. For example, some objects may be moved around vertically
+by setting their @code{padding} property.
-Relations between all grobs are modified to reflect line breaks: When a
-spanner, e.g. a slur, crosses a line-break, then the spanner is "broken
-into pieces", for every line that the spanner is in, a copy of the grob
-is made. A substitution process redirects all grob-reference so that
-each spanner grob will only reference other grobs in the same line.
+These properties use Scheme-style naming: @code{c0-position},
+@code{break-align-symbol}. They most often assigned as follows:
-@item Outputting:
+@example
+ \override Score.RehearsalMark #'break-align-symbol = ...
+@end example
-All vertical dimensions and spanning objects are computed, and all grobs
-are output, line by line. The output is encoded in the form of
-@code{Molecule}s
+@noindent
+Here, @code{RehearsalMark} is the type of the layout object.
@end table
-The data types that are mentioned here are all discussed in this
-section.
+This chapter discusses details of the three concepts in more detail,
+and explains how they are glued together in LilyPond with the embedded
+Scheme interpreter.
@menu
-* Input location::
-* Moment::
-* Duration::
-* Pitch data type::
-* Music::
-* Music_iterator::
-* Translator::
-* Grobs:: Graphical object
-* Molecules:: Molecules are stand-alone descriptions of output
-* Font metrics:: Font metrics
-* Miscellaneous Scheme functions::
+* Interpretation context::
+* Scheme integration::
+* Music storage format::
+* Lexical details::
+* Output details::
@end menu
-@ignore
- Why not use Scheme syntax for the functions below, such as
- (ly-input-location? obj) and (ly-get-mus-property m sym) ?
- /MB
-@end ignore
+@node Interpretation context
+@section Interpretation context
-@node Input location
-@section Input location
+@menu
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Context evaluation::
+* Defining contexts::
+* Changing contexts locally::
+* Engravers and performers::
+* Defining new contexts::
+@end menu
-@c The parser generates
-Input location objects point to a location in the input file. This
-location is used to generate error messages and to enable the point and
-click output.
+Interpretation contexts are objects that only exist during program
+run. During the interpretation phase (when @code{interpreting music}
+is printed on the standard output), the music expression in a
+@code{\score} block is interpreted in time order, the same order in
+which we hear and play the music. During this phase, the interpretation
+context holds the state for the current point within the music, for
+example:
+@itemize @bullet
+@item What notes are playing at this point?
-@defun ly-input-location? obj
-Type predicate, return true if @var{obj} is an input location.
-@end defun
+@item What symbols will be printed at this point?
+@item What is the current key signature, time signature, point within
+the measure, etc.?
+@end itemize
+Contexts are grouped hierarchically: A @internalsref{Voice} context is
+contained in a @internalsref{Staff} context (because a staff can contain
+multiple voices at any point), a @internalsref{Staff} context is contained in
+@internalsref{Score}, @internalsref{StaffGroup}, or
+@internalsref{ChoirStaff} context.
+Contexts associated with sheet music output are called @emph{notation
+contexts}, those for sound output are called @emph{performance
+contexts}. The default definitions of the standard notation and
+performance contexts can be found in @file{ly/engraver-init.ly} and
+@file{ly/performer-init.ly}, respectively.
-@node Moment
-@section Moment
-Moment is a rational number. Since GUILE doesn't support them natively,
-so we created our own rational data type.
+@node Creating contexts
+@subsection Creating contexts
+@cindex @code{\context}
+@cindex context selection
-@defun moment? obj
-Type predicate, return true if @var{obj} is a moment.
-@end defun
+Contexts for a music expression can be selected manually, using one of
+the following music expressions:
+
+@example
+\new @var{contexttype} @var{musicexpr}
+\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+@end example
-@defun make-moment num den
-create the rational number @var{num}/@var{den}.
-@end defun
+@noindent
+This means that @var{musicexpr} should be interpreted within a context
+of type @var{contexttype} (with name @var{contextname} if specified).
+If no such context exists, it will be created:
-@node Duration
-@section Duration
+@lilypond[verbatim,raggedright]
+\score {
+ \notes \relative c'' {
+ c4 <<d4 \context Staff = "another" e4>> f
+ }
+}
+@end lilypond
-A duration is a musical duration, i.e. a length of time described by a
-power of two (whole, half, quarter, etc.) and a number of augmentation
-dots.
+@noindent
+In this example, the @code{c} and @code{d} are printed on the default
+staff. For the @code{e}, a context @code{Staff} called @code{another}
+is specified; since that does not exist, a new context is created.
+Within @code{another}, a (default) Voice context is created for the
+@code{e4}. A context is ended when when all music referring it has
+finished, so after the third quarter, @code{another} is removed.
-@defun make-duration length dotcount
+The @code{\new} construction creates a context with a
+generated, unique @var{contextname}. An expression with
+@code{\new} always leads to a new context. This is convenient
+for creating multiple staffs, multiple lyric lines, etc.
-@var{length} is the negative logarithm (base 2) of the duration:
-1 is a half note, 2 is a quarter note, 3 is an eighth
-note, etc. The number of dots after the note is given by
-@var{dotcount}.
-@end defun
+When using automatic staff changes, automatic phrasing, etc., the
+context names have special meanings, so @code{\new} cannot be
+used.
-@defun duration? obj
-Type predicate, return true if @var{obj} is a duration.
-@end defun
+@node Default contexts
+@subsection Default contexts
-@node Pitch data type
-@section Pitch data type
+Every top level music is interpreted by the @code{Score} context; in
+other words, you may think of @code{\score} working like
+@example
+\score @{
+ \context Score @var{music}
+@}
+@end example
+Music expressions inherit their context from the enclosing music
+expression. Hence, it is not necessary to explicitly specify
+@code{\context} for most expressions. In
+the following example, only the sequential expression has an explicit
+context. The notes contained therein inherit the @code{goUp} context
+from the enclosing music expression.
-@defun make-pitch octave note shift
+@lilypond[verbatim,raggedright]
+ \notes \context Voice = goUp { c'4 d' e' }
+@end lilypond
-@var{octave} is specified by an integer, zero for the octave containing
-middle C. @var{note} is a number from 0 to 6, with 0 corresponding to C
-and 6 corresponding to B. The shift is zero for a natural, negative for
-flats, or positive for sharps.
-@end defun
-@defun pitch-octave p
-extract the octave from pitch @var{p}.
-@end defun
+Second, contexts are created automatically to be able to interpret the
+music expressions. Consider the following example:
-@defun pitch-notename p
-extract the note name from pitch @var{p}.
-@end defun
+@lilypond[verbatim,raggedright]
+ \score { \notes { c'4-( d' e'-) } }
+@end lilypond
-@defun pitch-alteration p
-extract the alteration from pitch @var{p}.
-@end defun
+@noindent
+The sequential music is interpreted by the Score context initially,
+but when a note is encountered, contexts are setup to accept that
+note. In this case, a @code{Voice}, and @code{Staff}
+context are created. The rest of the sequential music is also
+interpreted with the same @code{Voice}, and
+@code{Staff} context, putting the notes on the same staff, in the same
+voice.
-@defun pitch-semitones p
-calculate the number of semitones of @var{p} from central C.
-@end defun
+@node Context properties
+@subsection Context properties
-@defun Pitch::transpose t p
-Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that
-central C is transposed to.
-@end defun
+Contexts have properties. These properties are set from the @file{.ly}
+file using the following expression:
+@cindex context properties
+@cindex properties, context
+@example
+\set @var{contextname}.@var{propname} = @var{value}
+@end example
-@node Music
-@section Music
+@noindent
+Sets the @var{propname} property of the context @var{contextname} to
+the specified Scheme expression @var{value}. Both @var{propname} and
+@var{contextname} are strings, which can often be written unquoted.
-Music is the data type that music expressions are stored in. The data
-type does not yet offer many manipulations.
+@cindex inheriting
+Properties that are set in one context are inherited by all of the
+contained contexts. This means that a property valid for the
+@internalsref{Voice} context can be set in the @internalsref{Score} context
+(for example) and thus take effect in all @internalsref{Voice} contexts.
-@defun ly-get-mus-property m sym
-Get the property @var{sym} of music expression @var{m}.
-@end defun
+Properties can be unset using the following statement.
+@example
+\unset @var{contextname}.@var{propname}
+@end example
-@defun ly-set-mus-property m sym val
-Set property @var{sym} in music expression @var{m} to @var{val}.
-@end defun
+@cindex properties, unsetting
+@cindex @code{\unset}
-@defun ly-make-music name
-Make a music object/expression of type @var{name}. Warning: this
-interface will likely change in the near future.
-@end defun
+@noindent
+This removes the definition of @var{propname} in @var{contextname}. If
+@var{propname} was not defined in @var{contextname} (but was inherited
+from a higher context), then this has no effect.
-@defun music? obj
-Type predicate, return true if @var{obj} is a music object.
-@end defun
+If @var{contextname} is left out, then it defaults to the current
+``bottom'' context: this is a context like @internalsref{Voice} that
+cannot contain any other contexts.
-@defun ly-music-name music
-Print the name of @var{music}.
-@end defun
-@node Music_iterator
-@section Music_iterator
+@node Context evaluation
+@subsection Context evaluation
-Music_iterator is an object type that traverses the Music structure and
-reports the events it finds to interpretation contexts. It is not yet
-user-serviceable.
+Contexts can be modified during interpretation with Scheme code. The
+syntax for this is
+@example
+ \applycontext @var{function}
+@end example
-@defun c++-function? obj
-Type predicate, return true if @var{obj} is a c++-function.
-Music_iterator are created from schemified C++ constructors. Such a
-constructor is a @code{c++-function}.
-@end defun
+@var{function} should be a Scheme function taking a single argument,
+being the context to apply it to. The following code will print the
+current bar number on the standard output during the compile:
-@node Translator
-@section Translator
+@example
+ \applycontext
+ #(lambda (x)
+ (format #t "\nWe were called in barnumber ~a.\n"
+ (ly:context-property x 'currentBarNumber)))
+@end example
-Translators are the building blocks of contexts. They are not yet user
-accessible.
-@defun ly-get-trans-property tr sym
-retrieve the value of @var{sym} from context @var{tr}
-@end defun
-@defun ly-set-trans-property tr sym val
-set value of property @var{sym} in context @var{tr} to @var{val}.
-@end defun
+@node Defining contexts
+@subsection Defining contexts
+@cindex context definition
+@cindex translator definition
-@node Grobs
-@section Grobs
+The most common way to create a new context definition is by extending
+an existing one. An existing context from the paper block is copied
+by referencing a context identifier:
-This section is about Grobs (short for Graphical Objects), which are
-formatting objects used to create the final output. This material is
-normally the domain of LilyPond gurus, but occasionally, a normal user
-also has to deal with grobs.
+@example
+\paper @{
+ \translator @{
+ @var{context-identifier}
+ @}
+@}
+@end example
-The most simple interaction with Grobs are when you use
-@code{\override}:
+@noindent
+Every predefined context has a standard identifier. For example, the
+@code{Staff} context can be referred to as @code{\StaffContext}.
+The context can then be modified by setting or changing properties,
+e.g.
@example
- \property Voice.Stem \override #'direction = #1
+\translator @{
+ \StaffContext
+ Stem \set #'thickness = #2.0
+ defaultBarType = #"||"
+@}
@end example
+These assignments happen before interpretation starts, so a property
+command will override any predefined settings.
-This piece of lily input causes all stem objects to be stem-up
-henceforth. In effect, you are telling lilypond to extend the definition
-of the `Stem' grob with the setting @code{direction := 1}.
+@cindex engraver
-@menu
-* What is a grob?::
-* Callbacks::
-* Setting grob properties::
-* Grob interfaces::
-* Items and Spanners::
-* Grob Scheme functions::
-@end menu
+@refbugs
+It is not possible to collect multiple property assignments in a
+variable, and apply to one @code{\translator} definition by
+referencing that variable.
+@node Changing contexts locally
+@subsection Changing contexts locally
-@node What is a grob?
-@subsection What is a grob?
-In music notation, lots of symbols are related in some way. You can
-think of music notation as a graph where nodes are formed by the
-symbols, and the arcs by their relations. A grob is a node in that graph.
-The directed edges in the graph are formed by references to other grobs
-(i.e. pointers).
-This big graph of grobs specifies the notation problem. The solution of
-this problem is a description of the printout in closed form, i.e. a
-list of values. These values are Molecules. (see @ref{Molecules})
+Extending an existing context can also be done locally. A piece of
+music can be interpreted in a changed context by using the following syntax
-All grobs have an X and Y-position on the page. These X and Y positions
-are stored in a relative format, so they can easily be combined by
-stacking them, hanging one grob to the side of another, and coupling
-them into a grouping-grob.
+@example
+ \with @{
+ @var{context modifications}
+ @}
+@end example
+
+These statements comes between @code{\new} or @code{\context} and the
+music to be interpreted. The @var{context modifications} property
+settings and @code{\remove}, @code{\consists} and @code{\consistsend}
+commands. The syntax is similar to the @code{\translator} block.
+
+The following example shows how a staff is created with bigger spaces,
+and without a @code{Clef_engraver}.
-Each grob has a reference point (a.k.a. parent): the position of a grob
-is stored relative to that reference point. For example the X-reference
-point of a staccato dot usually is the note head that it applies
-to. When the note head is moved, the staccato dot moves along
-automatically.
+@lilypond[relative=1,fragment,verbatim]
+<<
+ \new Staff { c4 es4 g2 }
+ \new Staff \with {
+ \override StaffSymbol #'staff-space = #(magstep 1.5)
+ fontSize = #1.5
+ \remove "Clef_engraver"
+ } {
+ c4 es4 g2
+ } >>
+@end lilypond
-If you keep following offset reference points, you will always end up at
-the root object. This root object is called @code{Line_of_score}, and it
-represents a system (i.e. a line of music).
+@refbugs
-All grobs carry a set of grob-properties. In the Stem example above,
-the property @code{direction} is set to value @code{1}. The function
-that draws the symbol (@code{Stem::brew_molecule}) uses the value of
-@code{direction} to determine how to print the stem and the flag. The
-appearance of a grob is determined solely by the values of its
-properties.
+The command @code{\with} has no effect on contexts that already
+exist.
-A grob is often associated with a symbol, but some grobs do not print
-any symbols. They take care of grouping objects. For example, there is a
-separate grob that stacks staves vertically. The @code{NoteCollision}
-is also an abstract grob: it only moves around chords, but doesn't print
-anything.
-A complete list of grob types is found in the generated documentation.
+@node Engravers and performers
+@subsection Engravers and performers
-@node Callbacks
-@subsection Callbacks
+Each context is composed of a number of building blocks, or plug-ins
+called engravers. An engraver is a specialized C++ class that is
+compiled into the executable. Typically, an engraver is responsible
+for one function: the @code{Slur_engraver} creates only @code{Slur}
+objects, and the @code{Skip_event_swallow_translator} only swallows
+(silently gobbles) @code{SkipEvent}s.
-Offsets of grobs are relative to a parent reference point. Most
-positions are not known when an object is created, so these are
-calculated as needed. This is done by adding a callback for a specific
-direction.
-Suppose you have the following code in a .ly file.
+
+@cindex engraver
+@cindex plug-in
+
+An existing context definition can be changed by adding or removing an
+engraver. The syntax for these operations is
@example
- #(define (my-callback gr axis)
- (* 2.0 (get-grob-property gr 'direction))
- )
+\consists @var{engravername}
+\remove @var{engravername}
+@end example
-....
+@cindex @code{\consists}
+@cindex @code{\remove}
+
+@noindent
+Here @var{engravername} is a string, the name of an engraver in the
+system. In the following example, the @code{Clef_engraver} is removed
+from the Staff context. The result is a staff without a clef, where
+the middle C is at its default position, the center line:
+
+@lilypond[verbatim,raggedright]
+\score {
+ \notes {
+ c'4 f'4
+ }
+ \paper {
+ \translator {
+ \StaffContext
+ \remove Clef_engraver
+ }
+ }
+}
+@end lilypond
+
+A list of all engravers is in the internal documentation,
+see @internalsref{Engravers}.
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+
+It is also possible to define new contexts from scratch. To do this,
+you must define give the new context a name. In the following
+example, a very simple Staff context is created: one that will put
+note heads on a staff symbol.
- \property Voice.Stem \override #'Y-offset-callbacks = #(list
- my-callback)
+@example
+\translator @{
+ \type "Engraver_group_engraver"
+ \name "SimpleStaff"
+ \alias "Staff"
+ \consists "Staff_symbol_engraver"
+ \consists "Note_head_engraver"
+ \consistsend "Axis_group_engraver"
+@}
@end example
-When the Y-offset of a Stem object is needed, LilyPond will
-automatically execute all callbacks for that object. In this case, it
-will find @code{my-callback}, and execute that. The result is that the
-stem is translated by two staff spaces in its direction.
+@noindent
+The argument of @code{\type} is the name for a special engraver that
+handles cooperation between simple engravers such as
+@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
+should always be @code{Engraver_group_engraver} (unless you are
+defining a Score context from scratch, in which case
+@code{Score_engraver} must be used).
+
+The complete list of context modifiers is the following:
+@itemize @bullet
+@item @code{\alias} @var{alternate-name}:
+This specifies a different name. In the above example,
+@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
+
+@item @code{\consistsend} @var{engravername}:
+Analogous to @code{\consists}, but makes sure that
+@var{engravername} is always added to the end of the list of
+engravers.
+
+Engravers that group context objects into axis groups or alignments
+need to be at the end of the list. @code{\consistsend} insures that
+engravers stay at the end even if a user adds or removes engravers.
+
+@item @code{\accepts} @var{contextname}:
+This context can contains @var{contextname} contexts. The first
+@code{\accepts} is created as a default context when events (e.g. notes
+or rests) are encountered.
+
+@item @code{\denies}:
+The opposite of @code{\accepts}.
+
+@item @code{\name} @var{contextname}:
+This sets the type name of the context, e.g. @code{Staff},
+@code{Voice}. If the name is not specified, the translator will not
+do anything.
+@end itemize
+
+
+@node Scheme integration
+@section Scheme integration
+
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
+
+LilyPond internally uses GUILE, a Scheme-interpreter, to represent
+data throughout the whole program, and glue together different program
+modules. For advanced usage, it is sometimes necessary to access and
+program the Scheme interpreter.
+
+Scheme is a full-blown programming language, from the LISP
+family. and a full discussion is outside the scope of this document.
+Interested readers are referred to the website
+@uref{http://www.schemers.org/} for more information on Scheme.
+
+The GUILE library for extension is documented at
+@uref{http://www.gnu.org/software/guile}.
+@ifinfo
+When it is installed, the following link should take you to its manual
+@ref{(guile.info)guile}
+@end ifinfo
+
+@menu
+* Inline Scheme::
+* Input variables and Scheme::
+* Assignments::
+@end menu
+
+@node Inline Scheme
+@subsection Inline Scheme
-(note: @code{Y-offset-callbacks} is also a property)
+Scheme expressions can be entered in the input file by entering a
+hash-sign (@code{#}). The expression following the hash-sign is
+evaluated as Scheme. For example, the boolean value @var{true} is
+@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
+and can be used in property assignments:
+@example
+ \set Staff.autoBeaming = ##f
+@end example
+@node Input variables and Scheme
+@subsection Input variables and Scheme
-Offset callbacks can be stacked, i.e.
+The input format supports the notion of variable: in the following
+example, a music expression is assigned to a variable with the name
+@code{traLaLa}.
@example
- \property .... \override #'Y-offset-callbacks = #(list
- callback1 callback2 callback3)
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
+@noindent
+
+There is also a form of scoping: in the following example, the
+@code{\paper} block also contains a @code{traLaLa} variable, which is
+independent of the outer @code{\traLaLa}.
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+ \paper @{ traLaLa = 1.0 @}
@end example
+@c
+In effect, each input file is a scope, and all @code{\header},
+@code{\midi} and @code{\paper} blocks are scopes nested inside that
+toplevel scope.
-The callbacks will be executed in the order @code{callback3 callback2
-callback1}. This is used for quantized positioning: the staccato dot is
-above or below a note head, and it must not be on a staff-line. To
-achieve this, the staccato dot has two callbacks: one that positions the
-grob above or below the note head, and one that rounds the Y-position of
-the grob to the nearest open space.
+Both variables and scoping are implemented in the GUILE module system.
+An anonymous Scheme module is attached to each scope. An assignment of
+the form
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
-Similarly, the size of a grob are determined through callbacks, settable
-with grob properties @code{X-extent-callback} and
-@code{Y-extent-callback}. There can be only one extent-callback for
-each axis. No callback (Scheme value @code{#f}) means: "empty in this
-direction". If you fill in a pair of numbers, that pair hard-codes the
-extent in that coordinate.
+@noindent
+is internally converted to a Scheme definition
+@example
+ (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
+@end example
+This means that input variables and Scheme variables may be freely
+mixed. In the following example, a music fragment is stored in the
+variable @code{traLaLa}, and duplicated using Scheme. The result is
+imported in a @code{\score} by means of a second variable
+@code{twice}:
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
-@node Setting grob properties
-@subsection Setting grob properties
+ #(define newLa (map ly:music-deep-copy
+ (list traLaLa traLaLa)))
+ #(define twice
+ (make-sequential-music newLa))
-Grob properties are stored as GUILE association lists, with symbols as
-keys. In GUILE you can access these using functions described in
-Section @ref{Grob Scheme functions}. From C++, grob properties can be
-accessed using these functions:
+ \score @{ \twice @}
+@end example
+In the above example, music expressions can be `exported' from the
+input to the Scheme interpreter. The opposite is also possible. By
+wrapping a Scheme value in the function @code{ly:export}, a Scheme
+value is interpreted as if it were entered in LilyPond syntax: instead
+of defining @code{\twice}, the example above could also have been
+written as
@example
- SCM get_grob_property (SCM) const;
- void set_grob_property (const char * , SCM val);
- void set_immutable_grob_property (const char * , SCM val);
- void set_immutable_grob_property (SCM key, SCM val);
- void set_grob_property (SCM , SCM val);
- void set_grob_pointer (const char*, SCM val);
- SCM remove_grob_property (const char* nm);
+ @dots{}
+ \score @{ #(ly:export (make-sequential-music newLa)) @}
@end example
-All lookup functions identify undefined properties with end-of-list
-(i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
-Properties are stored in two ways:
-@itemize @bullet
-@item mutable properties.
-Grob properties that change from object to object. The storage of
-these are private to a grob. For example pointers to other grobs are
-always stored in the mutable properties.
-
-@item immutable properties.
-Grob properties that are shared across different grobs of the same
-type. The storage is shared, and hence it is read-only. Typically, this
-is used to store function callbacks, and default settings. They are
-initially read from @file{scm/grob-description.scm}.
-@end itemize
-You can change immutable grob properties with the \override syntax:
+
+@node Assignments
+@subsection Assignments
+@cindex Assignments
+
+Variables allow objects to be assigned to names during the parse
+stage. To assign a variable, use
@example
- \property Voice.Stem \override #'direction = #1
+@var{name}@code{=}@var{value}
@end example
+To refer to a variable, precede its name with a backslash:
+`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
+the input-types listed above. Variable assignments can appear at top
+level in the LilyPond file, but also in @code{\paper} blocks.
+
+A variable can be created with any string for its name, but for
+accessing it in the LilyPond syntax, its name must consist of
+alphabetic characters only, and may not be a keyword of the syntax.
+There are no restrictions for naming and accessing variables in the
+Scheme interpreter,
+
+The right hand side of a variable assignment is parsed completely
+before the assignment is done, so variables may be redefined in terms
+of its old value, e.g.
+@c
+@example
+foo = \foo * 2.0
+@end example
+
+When a variable is referenced in LilyPond syntax, the information it
+points to is copied. For this reason, a variable reference must
+always be the first item in a block.
-This will push the entry @code{'(direction . 1)} on the immutable
-property list for stems, in effect overriding the setting from
-@file{scm/grob-description.scm}. This can be undone by
+@example
+\paper @{
+ foo = 1.0
+ \paperIdent % wrong and invalid
+@}
+@end example
@example
- \property Voice.stem \revert #'direction
+\paper @{
+ \paperIdent % correct
+ foo = 1.0
+@}
@end example
-There is also a shorthand,
+
+
+@node Music storage format
+@section Music storage format
+
+Music in LilyPond is entered as music expressions. This section
+discusses different types of music expressions, and explains how
+information is stored internally. This internal storage is accessible
+through the Scheme interpreter, so music expressions may be
+manipulated using Scheme functions.
+
+@menu
+* Music expressions::
+* Internal music representation::
+* Manipulating music expressions::
+@end menu
+
+@node Music expressions
+@subsection Music expressions
+@cindex music expressions
+
+Notes, rests, lyric syllables are music expressions. Small music
+expressions may be combined to form larger ones, for example, by
+enclosing a list of expressions in @code{\sequential @{ @}} or @code{<<
+>>}. In the following example, a compound expression is formed out of
+the quarter note @code{c} and a quarter note @code{d}:
@example
- \property Context.GrobType \set #'prop = #VAL
+\sequential @{ c4 d4 @}
@end example
-this does a @code{\revert} followed by a @code{\override}
+@cindex Sequential music
+@cindex @code{\sequential}
+@cindex sequential music
+@cindex @code{<<}
+@cindex @code{>>}
+@cindex Simultaneous music
+@cindex @code{\simultaneous}
-You can change mutable properties with \outputproperty. This construct
-looks like
+The two basic compound music expressions are simultaneous and
+sequential music:
@example
- \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
+\sequential @code{@{} @var{musicexprlist} @code{@}}
+\simultaneous @code{@{} @var{musicexprlist} @code{@}}
@end example
-In this case, in every grob that satisfies @var{pred}, the grob property
- @var{sym} is set to @var{val}. For example
+For both, there is a shorthand:
@example
- \outputproperty
- #(lambda (gr) (string? (ly-get-grob-property gr
- 'text)))
- #'extra-offset = #'(-1.0 . 0.0)
+@code{@{} @var{musicexprlist} @code{@}}
@end example
-This shifts all grobs that have a @code{text} property one staff
-space to the left. This mechanism is rather clumsy to use, but it allows
-you tweak any setting of any grob.
+@noindent
+for sequential and
+@example
+@code{<<} @var{musicexprlist} @code{>>}
+@end example
-@node Grob interfaces
-@unnumberedsubsec Grob interfaces
+@noindent
+for simultaneous music.
+In principle, the way in which you nest sequential and simultaneous to
+produce music is not relevant. In the following example, three chords
+are expressed in two different ways:
-Grob properties form a name space where you can set variables per
-object. Each object however, may have multiple functions. For example,
-consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
-above or below the staff, it is a dynamic sign, and it is a kind of
-text.
+@lilypond[fragment,verbatim,center]
+\notes \context Voice {
+ <<a c'>> <<b d'>> <<c' e'>>
+ << { a b c' } { c' d' e' } >>
+}
+@end lilypond
+However, using @code{<<} and @code{>>} for entering chords leads to
+various peculiarities. For this reason, a special syntax
+for chords was introduced in version 1.7: @code{< >}.
-To reflect this different functions of a grob, procedures and variables
-are grouped into so-called interfaces. The dynamic text for example
-supports the following interfaces:
-@table @code
-@item font-interface
- The glyph is built from characters from a font, hence the
-@code{font-interface}. For objects supporting @code{font-interface}, you
-can select alternate fonts by setting @code{font-style},
-@code{font-point-size}, etc.
-@item dynamic-interface
- Dynamic interface is not associated with any variable or function in
-particular, but this makes it possible to distinguish this grob from
-other similar grobs (like @code{TextScript}), that have no meaning of
-dynamics.
-@item text-interface
- This interface is for texts that are to be set using special routines
-to stack text into lines, using kerning, etc.
-@item general-grob-interface
- This interface is supported by all grob types.
-@end table
+Other compound music expressions include:
+@example
+\repeat @var{expr}
+\transpose @var{from} @var{to} @var{expr}
+\apply @var{func} @var{expr}
+\context @var{type} = @var{id} @var{expr}
+\times @var{fraction} @var{expr}
+@end example
+@node Internal music representation
+@subsection Internal music representation
-@node Items and Spanners
-@unnumberedsubsec Items and Spanners
-Grobs can also be distinguished in their role in the horizontal spacing.
-Many grobs define constraints on the spacing by their sizes. For
-example, note heads, clefs, stems, and all other symbols with a fixed
-shape. These grobs form a subtype called @code{Item}.
-Other grobs have a shape that depends on the horizontal spacing. For
-example, slur, beam, tie, etc. These grobs form a subtype called
-@code{Spanner}. All spanners have two span-points (these must be
-@code{Item}s), one on the left and one on the right. The left bound is
-also the X-reference point of the spanner.
-Some items need special treatment for line breaking. For example, a
-clef is normally only printed at the start of a line (i.e. after a line
-break). To model this, `breakable' items (clef, key signature, bar lines,
-etc.) are copied twice. Then we have three versions of each breakable
-item: one version if there is no line break, one version that is printed
-before the line break (at the end of a system), one version that is
-printed after the line break.
-Whether these versions are visible and take up space, is determined by
-the outcome of the @code{visibility-lambda}. This grob property is a
-function taking a direction (-1, 0 or 1) as argument. It returns a cons
-of booleans, signifying whether this grob should be transparent and have
-no extent.
-@node Grob Scheme functions
-@unnumberedsubsec Grob Scheme functions
+When a music expression is parsed, it is converted into a set of
+Scheme music objects. The defining property of a music object is that
+it takes up time. Time is a rational number that measures the length
+of a piece of music, in whole notes.
-Grob properties can be manipulated from Scheme. In practice, most
-manipulations are coded in C++ because of tradition.
+A music object has three kinds of types:
+@itemize @bullet
+@item
+ music name: Each music expression has a name, for example, a note
+leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
+a @internalsref{SimultaneousMusic}. A list of all expressions
+available is in the internals manual, under @internalsref{Music
+expressions}.
+
+@item
+ `type' or interface: Each music name has several `types' or interface,
+ for example, a note is an @code{event}, but it is also a @code{note-event},
+ a @code{rhythmic-event} and a @code{melodic-event}.
+
+ All classes of music are listed in the internals manual, under
+ @internalsref{Music classes}.
+@item
+C++ object: Each music object is represented by a C++ object. For technical
+reasons, different music objects may be represented by different C++
+object types. For example, a note is @code{Event} object, while
+@code{\grace} creates a @code{Grace_music} object.
+
+We expect that distinctions between different C++ types will disappear
+in the future.
+@end itemize
-@defun ly-get-grob-property g sym
- Get the value of a value in grob @var{g} of property @var{sym}. It
-will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
-@end defun
+The actual information of a music expression is stored in properties.
+For example, a @internalsref{NoteEvent} has @code{pitch} and
+@code{duration} properties that store the pitch and duration of that
+note. A list of all properties available is in the internals manual,
+under @internalsref{Music properties}.
+
+A compound music expression is a music object that contains other
+music objects in its properties. A list of objects can be stored in
+the @code{elements} property of a music object, or a single `child'
+music object in the @code{element} object. For example,
+@internalsref{SequentialMusic} has its children in @code{elements},
+and @internalsref{GraceMusic} has its single argument in
+@code{element}. The body of a repeat is in @code{element} property of
+@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
+
+@node Manipulating music expressions
+@subsection Manipulating music expressions
+
+Music objects and their properties can be accessed and manipulated
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
+@example
+\apply #@var{func} @var{music}
+@end example
-@defun ly-set-grob-property g sym val
-Set @var{sym} in grob @var{g} to value @var{val}
-@end defun
+@noindent
+This means that the scheme function @var{func} is called with
+@var{music} as its argument. The return value of @var{func} is the
+result of the entire expression. @var{func} may read and write music
+properties using the functions @code{ly:music-property} and
+@code{ly:music-set-property!}.
+
+An example is a function that reverses the order of elements in
+its argument:
+@lilypond[verbatim,raggedright]
+ #(define (rev-music-1 m)
+ (ly:music-set-property! m 'elements (reverse
+ (ly:music-property m 'elements)))
+ m)
+ \score { \notes \apply #rev-music-1 { c4 d4 } }
+@end lilypond
+
+The use of such a function is very limited. The effect of this
+function is void when applied to an argument which is does not have
+multiple children. The following function application has no effect:
-@defun ly-get-spanner-bound spanner dir
-Get one of the bounds of @var{spanner}. @var{dir} may be @code{-1} for
-left, and @code{1} for right.
-@end defun
+@example
+ \apply #rev-music-1 \grace @{ c4 d4 @}
+@end example
-@defun ly-grob? g
-Typecheck: is @var{g} a grob?
-@end defun
+@noindent
+In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
+@code{elements}, only a single @code{element}. Every generally
+applicable function for @code{\apply} must -- like music expressions
+themselves -- be recursive.
+The following example is such a recursive function: It first extracts
+the @code{elements} of an expression, reverses them and puts them
+back. Then it recurses, both on @code{elements} and @code{element}
+children.
+@example
+#(define (reverse-music music)
+ (let* ((elements (ly:music-property music 'elements))
+ (child (ly:music-property music 'element))
+ (reversed (reverse elements)))
+ ; set children
+ (ly:music-set-property! music 'elements reversed)
+ ; recurse
+ (if (ly:music? child) (reverse-music child))
+ (map reverse-music reversed)
-@node Molecules
-@section Molecules
+ music))
+@end example
-@cindex Molecule
-@cindex Atom
-@cindex Output description
+A slightly more elaborate example is in
+@inputfileref{input/test,reverse-music.ly}.
-The objective of any typesetting system is to put ink on paper in the
-right places. For LilyPond, this final stage is left to the @TeX{} and
-the printer subsystem. For lily, the last stage in processing a score is
-outputting a description of what to put where. This description roughly
-looks like
+Some of the input syntax is also implemented as recursive music
+functions. For example, the syntax for polyphony
+@example
+ <<a \\ b>>
+@end example
+@noindent
+is actually implemented as a recursive function that replaces the
+above by the internal equivalent of
@example
- PUT glyph AT (x,y)
- PUT glyph AT (x,y)
- PUT glyph AT (x,y)
+ << \context Voice = "1" @{ \voiceOne a @}
+ \context Voice = "2" @{ \voiceTwo b @} >>
@end example
-you merely have to look at the tex output of lily to see this.
-Internally these instructions are encoded in Molecules.@footnote{At some
-point LilyPond also contained Atom-objects, but they have been replaced
-by Scheme expressions, making the name outdated.} A molecule is
-what-to-print-where information that also contains dimension information
-(how large is this glyph?).
+Other applications of @code{\apply} are writing out repeats
+automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
+saving keystrokes (@inputfileref{input/test,music-box.ly}) and
+exporting
+LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
-Conceptually, Molecules can be constructed from Scheme code, by
-translating a Molecule and by combining two molecules. In BNF
-notation:
+@seealso
-@example
-Molecule :: COMBINE Molecule Molecule
- | TRANSLATE Offset Molecule
- | GLYPH-DESCRIPTION
- ;
-@end example
+@file{scm/music-functions.scm}, @file{scm/music-types.scm},
+@inputfileref{input/test,add-staccato.ly},
+@inputfileref{input/test,unfold-all-repeats.ly}, and
+@inputfileref{input/test,music-box.ly}.
-If you are interested in seeing how this information is stored, you
-can run with the @code{-f scm} option. The scheme expressions are then
-dumped in the output file.
+@node Lexical details
+@section Lexical details
-All visible, i.e. non-transparent, grobs have a callback to create a
-Molecule. The name of the property is @code{molecule-callback}, and its
-value should be a Scheme function taking one argument (the grob) and
-returning a Molecule. Most molecule callbacks are written in C++, but
-you can also write them in Scheme. An example is provided in
-@code{input/regression/molecule-hacking.ly}.
+@cindex string
+@cindex concatenate
-@defun molecule? m
-type predicate.
-@end defun
+By enclosing text in quotes (@code{"}), strings are formed. To
+include a @code{"} character in a string write @code{\"}. Various
+other backslash sequences have special interpretations as in the C
+language. A string that does not contain spaces or special characters
+can be written without the quotes. The exact form of such unquoted
+strings depends on the input mode; there are different rules for
+lyrics, notes and markups. Strings can be concatenated with the
+@code{+} operator.
-@defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
-Construct a molecule by putting @var{mol2} next to
-@var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be
--1 (left or down) or 1 (right or up). @var{padding} specifies extra
-space to add in between measured in global staff space.
-@end defun
-@defun ly-get-molecule-extent! mol axis
-Return a pair of numbers signifying the extent of @var{mol} in
-@var{axis} direction (0 or 1 for x and y axis respectively).
-@end defun
+@node Output details
+@section Output details
-@defun ly-set-molecule-extent! mol axis extent
-Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in
-@var{axis} direction (0 or 1 for x- and y-axis respectively).
+The default output format is La@TeX{}, which should be run
+through La@TeX{}. Using the option @option{-f}
+(or @option{--format}) other output formats can be selected also, but
+currently none of them work reliably.
-Note that an extent @code{(A . B)} is an interval and hence @code{A} is
-smaller than @code{B}, and is often negative.
+At the beginning of the output file, various global parameters are
+defined. Then the file @file{lilyponddefs.tex} is loaded to define
+the macros used in the code which follows. @file{lilyponddefs.tex}
+includes various other files, partially depending on the global
+parameters.
-@end defun
+Now the music is output system by system (a `system' consists of all
+staves belonging together). From @TeX{}'s point of view, a system is an
+@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
+vertically on the baseline of the text. Between systems,
+@code{\interscoreline} is inserted vertically to have stretchable space.
+The horizontal dimension of the @code{\hbox} is given by the
+@code{linewidth} parameter from LilyPond's @code{\paper} block.
-@node Font metrics
-@section Font metrics
+After the last system LilyPond emits a stronger variant of
+@code{\interscoreline} only if the macro
+@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
+to the top of the page). You can avoid that by setting the variable
+@code{lastpagefill} in LilyPond's @code{\paper} block.
+
+It is possible to fine-tune the vertical offset further by defining the
+macro @code{\lilypondscoreshift}:
+
+@example
+\def\lilypondscoreshift@{0.25\baselineskip@}
+@end example
-The font object represents the metric information of a font. Every font
-that is loaded into LilyPond can be accessed via Scheme.
+@noindent
+where @code{\baselineskip} is the distance from one text line to the next.
-LilyPond only needs to know the dimension of glyph to be able to process
-them. This information is stored in font metric files. LilyPond can read
-two types of font-metrics: @TeX{} Font Metric files (TFM files) and
-Adobe Font Metric files (AFM files). LilyPond will always try to load
-AFM files first since they are more versatile.
+Here an example how to embed a small LilyPond file @code{foo.ly} into
+running La@TeX{} text without using the @code{lilypond-book} script
+(@pxref{lilypond-book manual}):
-@defun ly-get-default-font gr
-This returns the default font for grob @var{gr}.
-@end defun
+@example
+\documentclass@{article@}
-@defun ly-find-glyph-by-name font name
-This function retrieves a Molecule for the glyph named @var{name} in
-@var{font}. The font must be available as an AFM file.
-@cindex afm file
+\def\lilypondpaperlastpagefill@{@}
+\lineskip 5pt
+\def\lilypondscoreshift@{0.25\baselineskip@}
-@end defun
+\begin@{document@}
+This is running text which includes an example music file
+\input@{foo.tex@}
+right here.
+\end@{document@}
+@end example
-@node Miscellaneous Scheme functions
-@section Miscellaneous Scheme functions
+The file @file{foo.tex} has been simply produced with
-
-@defun ly-warn msg
-Scheme callable function to issue the warning @code{msg}.
-@end defun
-
-@defun ly-version
-Return the current lilypond version as a list, e.g.
-@code{(1 3 127 uu1)}.
-@end defun
-
-@defun ly-gulp-file name
-Read the file named @var{name}, and return its contents in a string. The
-file is looked up using the lilypond search path.
-
-@end defun
-
-@defun dir?
-type predicate. A direction is a -1, 0 or 1, where -1 represents left or
-down and 1 represents right or up.
-@end defun
-
-@defun ly-number->string num
- converts @var{num} to a string without generating many decimals. It
-leaves a space at the end.
-@end defun
-
-@defun set-lily-option sym val
- Set a global option for the program. Supported options include
-@table @code
-@item midi-debug
-If set to true, generate human readable MIDI
-@end table
+@example
+ lilypond-bin foo.ly
+@end example
-This function is useful to call from the command line: @code{lilypond -e
-"(set-lily-option 'midi-debug #t)"}
+The call to @code{\lineskip} assures that there is enough vertical space
+between the LilyPond box and the surrounding text lines.
-@end defun
+@c EOF
projects / lilypond.git / blobdiff