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 rational number. Since GUILE doesn't support them natively,
119 so we created our own rational data type.
122 Type predicate, return true if @var{obj} is a moment.
125 @defun make-moment num den
126 create the rational number @var{num}/@var{den}.
132 A duration is a musical duration, i.e. a length of time described by a
133 power of two (whole, half, quarter, etc.) and a number of augmentation
136 @defun make-duration length dotcount
138 @var{length} is the negative logarithm (base 2) of the duration:
139 1 is a half note, 2 is a quarter note, 3 is an eighth
140 note, etc. The number of dots after the note is given by
146 Type predicate, return true if @var{obj} is a duration.
149 @node Pitch data type
150 @section Pitch data type
154 @defun make-pitch octave note shift
156 @var{octave} is specified by an integer, zero for the octave containing
157 middle C. @var{note} is a number from 0 to 6, with 0 corresponding to C
158 and 6 corresponding to B. The shift is zero for a natural, negative for
159 flats, or positive for sharps.
162 @defun pitch-octave p
163 extract the octave from pitch @var{p}.
166 @defun pitch-notename p
167 extract the note name from pitch @var{p}.
170 @defun pitch-alteration p
171 extract the alteration from pitch @var{p}.
174 @defun pitch-semitones p
175 calculate the number of semitones of @var{p} from central C.
178 @defun Pitch::transpose t p
179 Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that
180 central C is transposed to.
187 Music is the data type that music expressions are stored in. The data
188 type does not yet offer many manipulations.
190 @defun ly-get-mus-property m sym
191 Get the property @var{sym} of music expression @var{m}.
194 @defun ly-set-mus-property m sym val
195 Set property @var{sym} in music expression @var{m} to @var{val}.
198 @defun ly-make-music name
199 Make a music object/expression of type @var{name}. Warning: this
200 interface will likely change in the near future.
204 Type predicate, return true if @var{obj} is a music object.
207 @defun ly-music-name music
208 Print the name of @var{music}.
213 @section Music_iterator
215 Music_iterator is an object type that traverses the Music structure and
216 reports the events it finds to interpretation contexts. It is not yet
219 @defun c++-function? obj
220 Type predicate, return true if @var{obj} is a c++-function.
221 Music_iterator are created from schemified C++ constructors. Such a
222 constructor is a @code{c++-function}.
228 Translators are the building blocks of contexts. They are not yet user
231 @defun ly-get-trans-property tr sym
232 retrieve the value of @var{sym} from context @var{tr}
235 @defun ly-set-trans-property tr sym val
236 set value of property @var{sym} in context @var{tr} to @var{val}.
243 This section is about Grobs (short for Graphical Objects), which are
244 formatting objects used to create the final output. This material is
245 normally the domain of LilyPond gurus, but occasionally, a normal user
246 also has to deal with grobs.
248 The most simple interaction with Grobs are when you use
252 \property Voice.Stem \override #'direction = #1
255 This piece of lily input causes all stem objects to be stem-up
256 henceforth. In effect, you are telling lilypond to extend the definition
257 of the `Stem' grob with the setting @code{direction := 1}.
262 * Setting grob properties::
264 * Items and Spanners::
265 * Grob Scheme functions::
270 @node What is a grob?
271 @subsection What is a grob?
273 In music notation, lots of symbols are related in some way. You can
274 think of music notation as a graph where nodes are formed by the
275 symbols, and the arcs by their relations. A grob is a node in that graph.
276 The directed edges in the graph are formed by references to other grobs
278 This big graph of grobs specifies the notation problem. The solution of
279 this problem is a description of the printout in closed form, i.e. a
280 list of values. These values are Molecules. (see @ref{Molecules})
282 All grobs have an X and Y-position on the page. These X and Y positions
283 are stored in a relative format, so they can easily be combined by
284 stacking them, hanging one grob to the side of another, and coupling
285 them into a grouping-grob.
287 Each grob has a reference point (a.k.a. parent): the position of a grob
288 is stored relative to that reference point. For example the X-reference
289 point of a staccato dot usually is the note head that it applies
290 to. When the note head is moved, the staccato dot moves along
293 If you keep following offset reference points, you will always end up at
294 the root object. This root object is called @code{Line_of_score}, and it
295 represents a system (i.e. a line of music).
297 All grobs carry a set of grob-properties. In the Stem example above,
298 the property @code{direction} is set to value @code{1}. The function
299 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
300 @code{direction} to determine how to print the stem and the flag. The
301 appearance of a grob is determined solely by the values of its
304 A grob is often associated with a symbol, but some grobs do not print
305 any symbols. They take care of grouping objects. For example, there is a
306 separate grob that stacks staffs vertically. The @code{NoteCollision}
307 is also an abstract grob: it only moves around chords, but doesn't print
310 A complete list of grob types is found in the generated documentation.
314 @subsection Callbacks
316 Offsets of grobs are relative to a parent reference point. Most
317 positions are not known when an object is created, so these are
318 calculated as needed. This is done by adding a callback for a specific
321 Suppose you have the following code in a .ly file.
323 #(define (my-callback gr axis)
324 (* 2.0 (get-grob-property gr 'direction))
329 \property Voice.Stem \override #'Y-offset-callbacks = #(list
333 When the Y-offset of a Stem object is needed, LilyPond will
334 automatically execute all callbacks for that object. In this case, it
335 will find @code{my-callback}, and execute that. The result is that the
336 stem is translated by two staff spaces in its direction.
338 (note: @code{Y-offset-callbacks} is also a property)
342 Offset callbacks can be stacked, i.e.
345 \property .... \override #'Y-offset-callbacks = #(list
346 callback1 callback2 callback3)
350 The callbacks will be executed in the order @code{callback3 callback2
351 callback1}. This is used for quantized positioning: the staccato dot is
352 above or below a note head, and it must not be on a staff-line. To
353 achieve this, the staccato dot has two callbacks: one that positions the
354 grob above or below the note head, and one that rounds the Y-position of
355 the grob to the nearest open space.
357 Similarly, the size of a grob are determined through callbacks, settable
358 with grob properties @code{X-extent-callback} and
359 @code{Y-extent-callback}. There can be only one extent-callback for
360 each axis. No callback (Scheme value @code{#f}) means: "empty in this
361 direction". If you fill in a pair of numbers, that pair hard-codes the
362 extent in that coordinate.
365 @node Setting grob properties
366 @subsection Setting grob properties
368 Grob properties are stored as GUILE association lists, with symbols as
369 keys. In GUILE you can access these using functions described in
370 Section @ref{Grob Scheme functions}. From C++, grob properties can be
371 accessed using these functions:
374 SCM get_grob_property (SCM) const;
375 void set_grob_property (const char * , SCM val);
376 void set_immutable_grob_property (const char * , SCM val);
377 void set_immutable_grob_property (SCM key, SCM val);
378 void set_grob_property (SCM , SCM val);
379 void set_grob_pointer (const char*, SCM val);
380 SCM remove_grob_property (const char* nm);
383 All lookup functions identify undefined properties with end-of-list
384 (i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
386 Properties are stored in two ways:
388 @item mutable properties.
389 Grob properties that change from object to object. The storage of
390 these are private to a grob. For example pointers to other grobs are
391 always stored in the mutable properties.
393 @item immutable properties.
394 Grob properties that are shared across different grobs of the same
395 type. The storage is shared, and hence it is read-only. Typically, this
396 is used to store function callbacks, and default settings. They are
397 initially read from @file{scm/grob-description.scm}.
400 You can change immutable grob properties with the \override syntax:
403 \property Voice.Stem \override #'direction = #1
406 This will push the entry @code{'(direction . 1)} on the immutable
407 property list for stems, in effect overriding the setting from
408 @file{scm/grob-description.scm}. This can be undone by
411 \property Voice.stem \revert #'direction
414 There is also a shorthand,
417 \property Context.GrobType \set #'prop = #VAL
420 this does a @code{\revert} followed by a @code{\override}
422 You can change mutable properties with \outputproperty. This construct
426 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
429 In this case, in every grob that satisfies @var{pred}, the grob property
430 @var{sym} is set to @var{val}. For example
434 #(lambda (gr) (string? (ly-get-grob-property gr
436 #'extra-offset = #'(-1.0 . 0.0)
439 This shifts all grobs that have a @code{text} property one staff
440 space to the left. This mechanism is rather clumsy to use, but it allows
441 you tweak any setting of any grob.
444 @node Grob interfaces
445 @unnumberedsubsec Grob interfaces
447 Grob properties form a name space where you can set variables per
448 object. Each object however, may have multiple functions. For example,
449 consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
450 above or below the staff, it is a dynamic sign, and it is a kind of
453 To reflect this different functions of a grob, procedures and variables
454 are grouped into so-called interfaces. The dynamic text for example
455 supports the following interfaces:
458 The glyph is built from characters from a font, hence the
459 @code{font-interface}. For objects supporting @code{font-interface}, you
460 can select alternate fonts by setting @code{font-style},
461 @code{font-point-size}, etc.
463 @item dynamic-interface
464 Dynamic interface is not associated with any variable or function in
465 particular, but this makes it possible to distinguish this grob from
466 other similar grobs (like @code{TextScript}), that have no meaning of
470 This interface is for texts that are to be set using special routines
471 to stack text into lines, using kerning, etc.
473 @item general-grob-interface
474 This interface is supported by all grob types.
479 @node Items and Spanners
480 @unnumberedsubsec Items and Spanners
482 Grobs can also be distinguished in their role in the horizontal spacing.
483 Many grobs define constraints on the spacing by their sizes. For
484 example, note heads, clefs, stems, and all other symbols with a fixed
485 shape. These grobs form a subtype called @code{Item}.
487 Other grobs have a shape that depends on the horizontal spacing. For
488 example, slur, beam, tie, etc. These grobs form a subtype called
489 @code{Spanner}. All spanners have two span-points (these must be
490 @code{Item}s), one on the left and one on the right. The left bound is
491 also the X-reference point of the spanner.
493 Some items need special treatment for line breaking. For example, a
494 clef is normally only printed at the start of a line (i.e. after a line
495 break). To model this, `breakable' items (clef, key signature, bar lines,
496 etc.) are copied twice. Then we have three versions of each breakable
497 item: one version if there is no line break, one version that is printed
498 before the line break (at the end of a system), one version that is
499 printed after the line break.
501 Whether these versions are visible and take up space, is determined by
502 the outcome of the @code{visibility-lambda}. This grob property is a
503 function taking a direction (-1, 0 or 1) as argument. It returns a cons
504 of booleans, signifying whether this grob should be transparent and have
507 @node Grob Scheme functions
508 @unnumberedsubsec Grob Scheme functions
510 Grob properties can be manipulated from Scheme. In practice, most
511 manipulations are coded in C++ because of tradition.
513 @defun ly-get-grob-property g sym
514 Get the value of a value in grob @var{g} of property @var{sym}. It
515 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
518 @defun ly-set-grob-property g sym val
519 Set @var{sym} in grob @var{g} to value @var{val}
522 @defun ly-get-spanner-bound spanner dir
523 Get one of the bounds of @var{spanner}. @var{dir} may be @code{-1} for
524 left, and @code{1} for right.
528 Typecheck: is @var{g} a grob?
539 @cindex Output description
541 The objective of any typesetting system is to put ink on paper in the
542 right places. For LilyPond, this final stage is left to the @TeX{} and
543 the printer subsystem. For lily, the last stage in processing a score is
544 outputting a description of what to put where. This description roughly
553 you merely have to look at the tex output of lily to see this.
554 Internally these instructions are encoded in Molecules.@footnote{At some
555 point LilyPond also contained Atom-objects, but they have been replaced
556 by Scheme expressions, making the name outdated.} A molecule is
557 what-to-print-where information that also contains dimension information
558 (how large is this glyph?).
560 Conceptually, Molecules can be constructed from Scheme code, by
561 translating a Molecule and by combining two molecules. In BNF
565 Molecule :: COMBINE Molecule Molecule
566 | TRANSLATE Offset Molecule
571 If you are interested in seeing how this information is stored, you
572 can run with the @code{-f scm} option. The scheme expressions are then
573 dumped in the output file.
575 All visible, i.e. non-transparent, grobs have a callback to create a
576 Molecule. The name of the property is @code{molecule-callback}, and its
577 value should be a Scheme function taking one argument (the grob) and
578 returning a Molecule. Most molecule callbacks are written in C++, but
579 you can also write them in Scheme. An example is provided in
580 @code{input/regression/molecule-hacking.ly}.
587 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
588 Construct a molecule by putting @var{mol2} next to
589 @var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be
590 -1 (left or down) or 1 (right or up). @var{padding} specifies extra
591 space to add in between measured in global staff space.
594 @defun ly-get-molecule-extent! mol axis
595 Return a pair of numbers signifying the extent of @var{mol} in
596 @var{axis} direction (0 or 1 for x and y axis respectively).
599 @defun ly-set-molecule-extent! mol axis extent
600 Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in
601 @var{axis} direction (0 or 1 for x- and y-axis respectively).
603 Note that an extent @code{(A . B)} is an interval and hence @code{A} is
604 smaller than @code{B}, and is often negative.
609 @section Font metrics
611 The font object represents the metric information of a font. Every font
612 that is loaded into LilyPond can be accessed via Scheme.
614 LilyPond only needs to know the dimension of glyph to be able to process
615 them. This information is stored in font metric files. LilyPond can read
616 two types of font-metrics: @TeX{} Font Metric files (TFM files) and
617 Adobe Font Metric files (AFM files). LilyPond will always try to load
618 AFM files first since they are more versatile.
620 @defun ly-get-default-font gr
621 This returns the default font for grob @var{gr}.
624 @defun ly-find-glyph-by-name font name
625 This function retrieves a Molecule for the glyph named @var{name} in
626 @var{font}. The font must be available as an AFM file.
631 @node Miscellaneous Scheme functions
632 @section Miscellaneous Scheme functions
636 Scheme callable function to issue the warning @code{msg}.
640 Return the current lilypond version as a list, e.g.
641 @code{(1 3 127 uu1)}.
644 @defun ly-gulp-file name
645 Read the file named @var{name}, and return its contents in a string. The
646 file is looked up using the lilypond search path.
651 type predicate. A direction is a -1, 0 or 1, where -1 represents left or
652 down and 1 represents right or up.
655 @defun ly-number->string num
656 converts @var{num} to a string without generating many decimals. It
657 leaves a space at the end.
660 @defun set-lily-option sym val
661 Set a global option for the program. Supported options include
664 If set to true, generate human readable MIDI
667 This function is useful to call from the command line: @code{lilypond -e
668 "(set-lily-option 'midi-debug #t)"}