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
14 When translating the input to notation, there are number of distinct
15 phases. We list them here:
21 The LY file is read, and converted to a list of @code{Scores}, which
22 each contain @code{Music} and paper/midi-definitions. Here @code{Music},
23 @code{Pitch} and @code{Duration} objects are created.
25 @item Interpreting music
26 @cindex interpreting music
28 All music events are "read" in the same order as they would be played
29 (or read from paper). At every step of the interpretation, musical
30 events are delivered to
31 interpretation contexts,
33 which use them to build @code{Grob}s (or MIDI objects, for MIDI output).
35 In this stage @code{Music_iterators} do a traversal of the @code{Music}
36 structure. The music events thus encountered are reported to
37 @code{Translator}s, a set of objects that collectively form interpretation
45 At places where line breaks may occur, clefs and bars are prepared for
46 a possible line break.
52 In this stage, all information that is needed to determine line breaking
55 @item Break calculation:
57 The lines and horizontal positions of the columns are determined.
61 Relations between all grobs are modified to reflect line breaks: When a
62 spanner, e.g. a slur, crosses a line-break, then the spanner is "broken
63 into pieces", for every line that the spanner is in, a copy of the grob
64 is made. A substitution process redirects all grob-reference so that
65 each spanner grob will only reference other grobs in the same line.
69 All vertical dimensions and spanning objects are computed, and all grobs
70 are output, line by line. The output is encoded in the form of
75 The data types that are mentioned here are all discussed in this
86 * Grobs:: Graphical object
87 * Molecules:: Molecules are stand-alone descriptions of output
88 * Font metrics:: Font metrics
89 * Miscellaneous Scheme functions::
93 Why not use Scheme syntax for the functions below, such as
94 (ly-input-location? obj) and (ly-get-mus-property m sym) ?
100 @section Input location
102 @c The parser generates
104 Input location objects point to a location in the input file. This
105 location is used to generate error messages and to enable the point and
108 @defun ly-input-location? obj
109 Type predicate, return true if @var{obj} is an input location.
118 Moment is a point in musical time. It is consists of a pair of
119 rationals (@var{m},@var{g}), where @var{m} is the timing for the main
120 notes, and @var{g} the timing for grace notes. In absence of grace
121 notes, @var{g} is zero.
124 Type predicate, return true if @var{obj} is a moment.
127 @defun make-moment num den
128 create the rational number with main timing @var{num}/@var{den}.
134 A duration is a musical duration, i.e. a length of time described by a
135 power of two (whole, half, quarter, etc.) and a number of augmentation
138 @defun make-duration length dotcount
140 @var{length} is the negative logarithm (base 2) of the duration:
141 1 is a half note, 2 is a quarter note, 3 is an eighth
142 note, etc. The number of dots after the note is given by
148 Type predicate, return true if @var{obj} is a duration.
151 @node Pitch data type
152 @section Pitch data type
156 @defun make-pitch octave note shift
158 @var{octave} is specified by an integer, zero for the octave containing
159 middle C. @var{note} is a number from 0 to 6, with 0 corresponding to C
160 and 6 corresponding to B. The shift is zero for a natural, negative for
161 flats, or positive for sharps.
164 @defun pitch-octave p
165 extract the octave from pitch @var{p}.
168 @defun pitch-notename p
169 extract the note name from pitch @var{p}.
172 @defun pitch-alteration p
173 extract the alteration from pitch @var{p}.
176 @defun pitch-semitones p
177 calculate the number of semitones of @var{p} from central C.
180 @defun Pitch::transpose t p
181 Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that
182 central C is transposed to.
189 Music is the data type that music expressions are stored in. The data
190 type does not yet offer many manipulations.
192 @defun ly-get-mus-property m sym
193 Get the property @var{sym} of music expression @var{m}.
196 @defun ly-set-mus-property m sym val
197 Set property @var{sym} in music expression @var{m} to @var{val}.
200 @defun ly-make-music name
201 Make a music object/expression of type @var{name}. Warning: this
202 interface will likely change in the near future.
206 Type predicate, return true if @var{obj} is a music object.
209 @defun ly-music-name music
210 Print the name of @var{music}.
215 @section Music_iterator
217 Music_iterator is an object type that traverses the Music structure and
218 reports the events it finds to interpretation contexts. It is not yet
221 @defun c++-function? obj
222 Type predicate, return true if @var{obj} is a c++-function.
223 Music_iterator are created from schemified C++ constructors. Such a
224 constructor is a @code{c++-function}.
230 Translators are the building blocks of contexts. They are not yet user
233 @defun ly-get-trans-property tr sym
234 retrieve the value of @var{sym} from context @var{tr}
237 @defun ly-set-trans-property tr sym val
238 set value of property @var{sym} in context @var{tr} to @var{val}.
241 @defun Translator::name tr
242 Return the type name of the translator @var{tr}.
245 @defun Translator::description tr
246 Return an alist of properties of translator @var{tr}.
252 This section is about Grobs (short for Graphical Objects), which are
253 formatting objects used to create the final output. This material is
254 normally the domain of LilyPond gurus, but occasionally, a normal user
255 also has to deal with grobs.
257 The most simple interaction with Grobs are when you use
261 \property Voice.Stem \override #'direction = #1
264 This piece of lily input causes all stem objects to be stem-up
265 henceforth. In effect, you are telling lilypond to extend the definition
266 of the `Stem' grob with the setting @code{direction := 1}.
271 * Setting grob properties::
273 * Items and Spanners::
274 * Grob Scheme functions::
279 @node What is a grob?
280 @subsection What is a grob?
282 In music notation, lots of symbols are related in some way. You can
283 think of music notation as a graph where nodes are formed by the
284 symbols, and the arcs by their relations. A grob is a node in that graph.
285 The directed edges in the graph are formed by references to other grobs
287 This big graph of grobs specifies the notation problem. The solution of
288 this problem is a description of the printout in closed form, i.e. a
289 list of values. These values are Molecules. (see @ref{Molecules})
291 All grobs have an X and Y-position on the page. These X and Y positions
292 are stored in a relative format, so they can easily be combined by
293 stacking them, hanging one grob to the side of another, and coupling
294 them into a grouping-grob.
296 Each grob has a reference point (a.k.a. parent): the position of a grob
297 is stored relative to that reference point. For example the X-reference
298 point of a staccato dot usually is the note head that it applies
299 to. When the note head is moved, the staccato dot moves along
302 If you keep following offset reference points, you will always end up at
303 the root object. This root object is called @code{Line_of_score}, and it
304 represents a system (i.e. a line of music).
306 All grobs carry a set of grob-properties. In the Stem example above,
307 the property @code{direction} is set to value @code{1}. The function
308 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
309 @code{direction} to determine how to print the stem and the flag. The
310 appearance of a grob is determined solely by the values of its
313 A grob is often associated with a symbol, but some grobs do not print
314 any symbols. They take care of grouping objects. For example, there is a
315 separate grob that stacks staves vertically. The @code{NoteCollision}
316 is also an abstract grob: it only moves around chords, but doesn't print
319 A complete list of grob types is found in the generated documentation.
323 @subsection Callbacks
325 Offsets of grobs are relative to a parent reference point. Most
326 positions are not known when an object is created, so these are
327 calculated as needed. This is done by adding a callback for a specific
330 Suppose you have the following code in a .ly file.
332 #(define (my-callback gr axis)
333 (* 2.0 (get-grob-property gr 'direction))
338 \property Voice.Stem \override #'Y-offset-callbacks = #(list
342 When the Y-offset of a Stem object is needed, LilyPond will
343 automatically execute all callbacks for that object. In this case, it
344 will find @code{my-callback}, and execute that. The result is that the
345 stem is translated by two staff spaces in its direction.
347 (note: @code{Y-offset-callbacks} is also a property)
351 Offset callbacks can be stacked, i.e.
354 \property .... \override #'Y-offset-callbacks = #(list
355 callback1 callback2 callback3)
359 The callbacks will be executed in the order @code{callback3 callback2
360 callback1}. This is used for quantized positioning: the staccato dot is
361 above or below a note head, and it must not be on a staff-line. To
362 achieve this, the staccato dot has two callbacks: one that positions the
363 grob above or below the note head, and one that rounds the Y-position of
364 the grob to the nearest open space.
366 Similarly, the size of a grob are determined through callbacks, settable
367 with grob properties @code{X-extent-callback} and
368 @code{Y-extent-callback}. There can be only one extent-callback for
369 each axis. No callback (Scheme value @code{#f}) means: "empty in this
370 direction". If you fill in a pair of numbers, that pair hard-codes the
371 extent in that coordinate.
374 @node Setting grob properties
375 @subsection Setting grob properties
377 Grob properties are stored as GUILE association lists, with symbols as
378 keys. In GUILE you can access these using functions described in
379 Section @ref{Grob Scheme functions}. From C++, grob properties can be
380 accessed using these functions:
383 SCM get_grob_property (SCM) const;
384 void set_grob_property (const char * , SCM val);
385 void set_immutable_grob_property (const char * , SCM val);
386 void set_immutable_grob_property (SCM key, SCM val);
387 void set_grob_property (SCM , SCM val);
388 void set_grob_pointer (const char*, SCM val);
389 SCM remove_grob_property (const char* nm);
392 All lookup functions identify undefined properties with end-of-list
393 (i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
395 Properties are stored in two ways:
397 @item mutable properties.
398 Grob properties that change from object to object. The storage of
399 these are private to a grob. For example pointers to other grobs are
400 always stored in the mutable properties.
402 @item immutable properties.
403 Grob properties that are shared across different grobs of the same
404 type. The storage is shared, and hence it is read-only. Typically, this
405 is used to store function callbacks, and default settings. They are
406 initially read from @file{scm/grob-description.scm}.
409 You can change immutable grob properties with the \override syntax:
412 \property Voice.Stem \override #'direction = #1
415 This will push the entry @code{'(direction . 1)} on the immutable
416 property list for stems, in effect overriding the setting from
417 @file{scm/grob-description.scm}. This can be undone by
420 \property Voice.stem \revert #'direction
423 There is also a shorthand,
426 \property Context.GrobType \set #'prop = #VAL
429 this does a @code{\revert} followed by a @code{\override}
431 You can change mutable properties with \outputproperty. This construct
435 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
438 In this case, in every grob that satisfies @var{pred}, the grob property
439 @var{sym} is set to @var{val}. For example
443 #(lambda (gr) (string? (ly-get-grob-property gr
445 #'extra-offset = #'(-1.0 . 0.0)
448 This shifts all grobs that have a @code{text} property one staff
449 space to the left. This mechanism is rather clumsy to use, but it allows
450 you tweak any setting of any grob.
453 @node Grob interfaces
454 @unnumberedsubsec Grob interfaces
456 Grob properties form a name space where you can set variables per
457 object. Each object however, may have multiple functions. For example,
458 consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
459 above or below the staff, it is a dynamic sign, and it is a kind of
462 To reflect this different functions of a grob, procedures and variables
463 are grouped into so-called interfaces. The dynamic text for example
464 supports the following interfaces:
467 The glyph is built from characters from a font, hence the
468 @code{font-interface}. For objects supporting @code{font-interface}, you
469 can select alternate fonts by setting @code{font-style},
470 @code{font-point-size}, etc.
472 @item dynamic-interface
473 Dynamic interface is not associated with any variable or function in
474 particular, but this makes it possible to distinguish this grob from
475 other similar grobs (like @code{TextScript}), that have no meaning of
479 This interface is for texts that are to be set using special routines
480 to stack text into lines, using kerning, etc.
482 @item general-grob-interface
483 This interface is supported by all grob types.
488 @node Items and Spanners
489 @unnumberedsubsec Items and Spanners
491 Grobs can also be distinguished in their role in the horizontal spacing.
492 Many grobs define constraints on the spacing by their sizes. For
493 example, note heads, clefs, stems, and all other symbols with a fixed
494 shape. These grobs form a subtype called @code{Item}.
496 Other grobs have a shape that depends on the horizontal spacing. For
497 example, slur, beam, tie, etc. These grobs form a subtype called
498 @code{Spanner}. All spanners have two span-points (these must be
499 @code{Item}s), one on the left and one on the right. The left bound is
500 also the X-reference point of the spanner.
502 Some items need special treatment for line breaking. For example, a
503 clef is normally only printed at the start of a line (i.e. after a line
504 break). To model this, `breakable' items (clef, key signature, bar lines,
505 etc.) are copied twice. Then we have three versions of each breakable
506 item: one version if there is no line break, one version that is printed
507 before the line break (at the end of a system), one version that is
508 printed after the line break.
510 Whether these versions are visible and take up space, is determined by
511 the outcome of the @code{visibility-lambda}. This grob property is a
512 function taking a direction (-1, 0 or 1) as argument. It returns a cons
513 of booleans, signifying whether this grob should be transparent and have
516 @node Grob Scheme functions
517 @unnumberedsubsec Grob Scheme functions
519 Grob properties can be manipulated from Scheme. In practice, most
520 manipulations are coded in C++ because of tradition.
522 @defun ly-get-grob-property g sym
523 Get the value of a value in grob @var{g} of property @var{sym}. It
524 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
527 @defun ly-set-grob-property g sym val
528 Set @var{sym} in grob @var{g} to value @var{val}
531 @defun ly-get-spanner-bound spanner dir
532 Get one of the bounds of @var{spanner}. @var{dir} may be @code{-1} for
533 left, and @code{1} for right.
537 Typecheck: is @var{g} a grob?
548 @cindex Output description
550 The objective of any typesetting system is to put ink on paper in the
551 right places. For LilyPond, this final stage is left to the @TeX{} and
552 the printer subsystem. For lily, the last stage in processing a score is
553 outputting a description of what to put where. This description roughly
562 you merely have to look at the tex output of lily to see this.
563 Internally these instructions are encoded in Molecules.@footnote{At some
564 point LilyPond also contained Atom-objects, but they have been replaced
565 by Scheme expressions, making the name outdated.} A molecule is
566 what-to-print-where information that also contains dimension information
567 (how large is this glyph?).
569 Conceptually, Molecules can be constructed from Scheme code, by
570 translating a Molecule and by combining two molecules. In BNF
574 Molecule :: COMBINE Molecule Molecule
575 | TRANSLATE Offset Molecule
580 If you are interested in seeing how this information is stored, you
581 can run with the @code{-f scm} option. The scheme expressions are then
582 dumped in the output file.
584 All visible, i.e. non-transparent, grobs have a callback to create a
585 Molecule. The name of the property is @code{molecule-callback}, and its
586 value should be a Scheme function taking one argument (the grob) and
587 returning a Molecule. Most molecule callbacks are written in C++, but
588 you can also write them in Scheme. An example is provided in
589 @code{input/regression/molecule-hacking.ly}.
596 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
597 Construct a molecule by putting @var{mol2} next to
598 @var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be
599 -1 (left or down) or 1 (right or up). @var{padding} specifies extra
600 space to add in between measured in global staff space.
603 @defun ly-get-molecule-extent! mol axis
604 Return a pair of numbers signifying the extent of @var{mol} in
605 @var{axis} direction (0 or 1 for x and y axis respectively).
608 @defun ly-set-molecule-extent! mol axis extent
609 Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in
610 @var{axis} direction (0 or 1 for x- and y-axis respectively).
612 Note that an extent @code{(A . B)} is an interval and hence @code{A} is
613 smaller than @code{B}, and is often negative.
618 @section Font metrics
620 The font object represents the metric information of a font. Every font
621 that is loaded into LilyPond can be accessed via Scheme.
623 LilyPond only needs to know the dimension of glyph to be able to process
624 them. This information is stored in font metric files. LilyPond can read
625 two types of font-metrics: @TeX{} Font Metric files (TFM files) and
626 Adobe Font Metric files (AFM files). LilyPond will always try to load
627 AFM files first since they are more versatile.
629 @defun ly-get-default-font gr
630 This returns the default font for grob @var{gr}.
633 @defun ly-find-glyph-by-name font name
634 This function retrieves a Molecule for the glyph named @var{name} in
635 @var{font}. The font must be available as an AFM file.
640 @node Miscellaneous Scheme functions
641 @section Miscellaneous Scheme functions
645 Scheme callable function to issue the warning @code{msg}.
649 Return the current lilypond version as a list, e.g.
650 @code{(1 3 127 uu1)}.
653 @defun ly-gulp-file name
654 Read the file named @var{name}, and return its contents in a string. The
655 file is looked up using the lilypond search path.
660 type predicate. A direction is a -1, 0 or 1, where -1 represents left or
661 down and 1 represents right or up.
664 @defun ly-number->string num
665 converts @var{num} to a string without generating many decimals. It
666 leaves a space at the end.
669 @defun set-lily-option sym val
670 Set a global option for the program. Supported options include
673 If set to true, generate human readable MIDI
676 This function is useful to call from the command line: @code{lilypond -e
677 "(set-lily-option 'midi-debug #t)"}