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 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, eg. 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 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 @section input location
97 Input location objects point to a lcoation in the input file. This
98 location is used to generate error messages and to enable the point and
101 @defun ly-input-location?
111 Moment is a rational number. Since GUILE doesn't support them natively,
112 so we created our own rational data type.
117 @defun make-moment num den
118 create the rational number @var{num}/@var{den}.
124 A duration is a musical duration, i.e. a length of time described by a
125 power of two (whole, half, quarter, etc.) and a number of augmentation
128 @defun make-duration length dotcount
130 @var{length} is the negative logarithm (base 2) of the duration:
131 1 is a half note, 2 is a quarter note, 3 is an eighth
132 note, etc. The number of dots after the note is given by
138 type predicate for Duration
141 @node Pitch data type
142 @section Pitch data type
146 @defun make-pitch octave note shift
148 @var{octave} is specified by an integer, zero for the octave containing
149 middle C. @var{note} is a number from 0 to 6, with 0 corresponding to C
150 and 6 corresponding to B. The shift is zero for a natural, negative for
151 flats, or positive for sharps.
154 @defun pitch-octave p
155 extract the octave from pitch @var{p}.
158 @defun pitch-notename p
159 extract the note name from pitch @var{p}.
162 @defun pitch-alteration p
163 extract the alteration from pitch @var{p}.
166 @defun pitch-semitones p
167 calculate the number of semitones of @var{p} from central C.
170 @defun Pitch::transpose t p
171 Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that
172 central C is transposed to.
179 Music is the data type that music expressions are stored in. The data
180 type does not yet offer many manipulations.
182 @defun ly-get-mus-property m sym
183 Get the property @var{sym} of music expression @var{m}.
186 @defun ly-set-mus-property m sym val
187 Set property @var{sym} in music expression @var{m} to @var{val}.
190 @defun ly-make-music name
191 Make a music object/expression of type @var{name}. Warning: this
192 interface will likely change in the near future.
196 A type predicate, return true if @var{obj} is a music object.
199 @defun ly-music-name music
200 Print the name of @var{music}.
205 @section Music_iterator
207 Music_iterator is an object type that traverses the Music structure and
208 reports the events it finds to interpretation contexts. It is not yet
212 type predicate for c++-function. Music_iterator are created from
213 schemified C++ constructors. Such a constructor is a @code{c++-function}.
219 Translators are the building blocks of contexts. They are not yet user
222 @defun ly-get-trans-property tr sym
223 retrieve the value of @var{sym} from context @var{tr}
226 @defun ly-set-trans-property tr sym val
227 set value of property @var{sym} in context @var{tr} to @var{val}.
234 This section is about Grobs (short for Graphical Objects), which are
235 formatting objects used to create the final output. This material is
236 normally the domain of LilyPond gurus, but occasionally, a normal user
237 also has to deal with grobs.
239 The most simple interaction with Grobs are when you use
243 \property Voice.Stem \override #'direction = #1
246 This piece of lily input causes all stem objects to be stem-up
247 henceforth. In effect, you are telling lilypond to extend the definition
248 of the `Stem' grob with the setting @code{direction := 1}.
253 * Setting grob properties::
255 * Items and Spanners::
256 * Grob Scheme functions::
261 @node What is a grob?
262 @subsection What is a grob?
264 In music notation, lots of symbols are related in some way. You can
265 think of music notation as a graph where nodes are formed by the
266 symbols, and the arcs by their relations. A grob is node in that graph.
267 The directed edges in the graph are formed by references to other grobs
270 This big graph of grobs specifies the notation problem. The solution of
271 this problem is a description of the printout in closed form, i.e. a
272 list of values. These values are Molecules. (see @ref{Molecules})
274 All grobs have an X and Y-position on the page. These X and Y positions
275 are stored in a relative format, so they can easily be combined by
276 stacking them, hanging one grob to the side of another, and coupling
277 them into a grouping-grob.
279 Each grob has a reference point (a.k.a. parent): the position of a grob
280 is stored relative to that reference point. For example the X-reference
281 point of a staccato dot usually is the note head that it applies
282 to. When the note head is moved, the staccato dot moves along
285 If you keep following offset reference points, you will always end up at
286 the root object. This root object is called @code{Line_of_score}, and it
287 represents a system (ie. a line of music).
289 All grobs carry a set of grob-properties. In the Stem example above,
290 the property @code{direction} is set to value @code{1}. The function
291 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
292 @code{direction} to determine how to print the stem and the flag. The
293 appearance of a grob is determined solely by the values of its
296 A grob is often associated with a symbol, but some grobs do not print
297 any symbols. They take care of grouping objects. For example, there is a
298 separate grob that stacks staffs vertically. The @code{NoteCollision}
299 also is an abstract grob: it only moves around chords, but doesn't print
302 A complete list of grob types is found in the generated documentation.
306 @subsection Callbacks
308 Offsets of grobs are relative to a parent reference point. Most
309 positions are not known when an object is created, so these are
310 calculated as needed. This is done by adding a callback for a specific
313 Suppose you have the following code in a .ly file.
315 #(define (my-callback gr axis)
316 (* 2.0 (get-grob-property gr 'direction))
321 \property Voice.Stem \override #'Y-offset-callbacks = #(list
325 When the Y-offset of a Stem object is needed, LilyPond will
326 automatically execute all callbacks for that object. In this case, it
327 will find @code{my-callback}, and execute that. The result is that the
328 stem is translated by two staff spaces in its direction.
330 (note: @code{Y-offset-callbacks} is also a property)
334 Offset callbacks can be stacked, ie.
337 \property .... \override #'Y-offset-callbacks = #(list
338 callback1 callback2 callback3)
342 The callbacks will be executed in the order @code{callback3 callback2
343 callback1}. This is used for quantized positioning: the staccato dot is
344 above or below a note head, and it must not be on a staff-line. To
345 achieve this, the staccato dot has two callbacks: one that positions the
346 grob above or below the note head, and one that rounds the Y-position of
347 the grob to the nearest open space.
349 Similarly, the size of a grob are determined through callbacks, settable
350 with grob properties @code{X-extent-callback} and
351 @code{Y-extent-callback}. There can be only one extent-callback for
352 each axis. No callback (Scheme value @code{#f}) means: "empty in this
353 direction". If you fill in a pair of numbers, that pair hard-codes the
354 extent in that coordinate.
357 @node Setting grob properties
358 @subsection Setting grob properties
360 Grob properties are stored as GUILE association lists, with symbols as
361 keys. In GUILE you can access these using functions described @ref{Grob
362 Scheme functions}. From C++, grob properties can be accessed using
366 SCM get_grob_property (SCM) const;
367 void set_grob_property (const char * , SCM val);
368 void set_immutable_grob_property (const char * , SCM val);
369 void set_immutable_grob_property (SCM key, SCM val);
370 void set_grob_property (SCM , SCM val);
371 void set_grob_pointer (const char*, SCM val);
372 SCM remove_grob_property (const char* nm);
375 All lookup functions identify undefined properties with end-of-list
376 (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
378 Properties are stored in two ways:
380 @item mutable properties.
381 grob properties that change from object to object. The storage of
382 these are private to a grob. For example pointers to other grobs are
383 always stored in the mutable properties.
385 @item immutable properties.
386 Grob properties that are shared across different grobs of the same
387 type. The storage is shared, and hence it is read-only. Typically, this
388 is used to store function callbacks, and default settings. They are
389 initially read from from @file{scm/grob-description.scm}.
392 You can change immutable grob properties with the \override syntax:
395 \property Voice.Stem \override #'direction = #1
398 This will push the entry @code{'(direction . 1)} on the immutable
399 property list for stems, in effect overriding the setting from
400 @file{scm/grob-description.scm}. This can be undone by
403 \property Voice.stem \revert #'direction
406 If you use this a lot, this gets old quickly. So we also have a
410 \property Context.GrobType \set #'prop = #VAL
413 this does a @code{\revert} followed by a @code{\override}
415 You can change mutable properties with \outputproperty. This construct
419 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
422 In this case, in every grob that satisfies @var{pred}, the grob property
423 @var{sym} is set to @var{val} is done. For example
427 #(lambda (gr) (string? (ly-get-grob-property gr
429 #'extra-offset = #'(-1.0 . 0.0)
432 This shifts all grobs that have a @code{text} property one staff
433 space to the left. This mechanism is rather clumsy to use, but it allows
434 you tweak any setting of any grob.
437 @node Grob interfaces
438 @unnumberedsubsec Grob interfaces
440 Grob properties form a namespace where you can set variables per
441 object. Each object however, may have multiple functions. For example,
442 consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
443 above or below the staff, it is a dynamic sign, and it is a kind of
446 To reflect this different functions of a grob, procedures and variables
447 are grouped into so-called interfaces. The dynamic text for example
448 supports the following interfaces:
451 The glyph is built from characters from a font, hence the
452 @code{font-interface}. For objects supporting @code{font-interface}, you
453 can select alternate fonts by setting @code{font-style},
454 @code{font-point-size}, etc.
456 @item dynamic-interface
457 Dynamic interface is not associated with any variable or function in
458 particular, but this makes it possible to distinguish this grob from
459 other similar grobs (like @code{TextScript}), that have no meaning of
463 This interface is for texts that are to be set using special routines
464 to stack text into lines, using kerning, etc.
466 @item general-grob-interface
467 This interface is supported by all grob types.
472 @node Items and Spanners
473 @unnumberedsubsec Items and Spanners
475 Grobs can also be distinguished in their role in the horizontal spacing.
476 A lot of grobs define constraints on the spacing by their sizes. For
477 example, note heads, clefs, stems, and all other symbols with a fixed
478 shape. These grobs form a subtype called @code{Item}.
480 Other grobs have a shape that depends on the horizontal spacing. For
481 example, slur, beam, tie, etc. These grobs form a subtype called
482 @code{Spanner}. All spanners have two span-points (these must be
483 @code{Item}s), one on the left and one on the right. The left bound is
484 also the X-reference point of the spanner.
486 Some items need special treatment for line breaking. For example, a
487 clef is normally only printed at the start of a line (ie. after a line
488 break). To model this, `breakable' items (clef, key signature, bar lines,
489 etc.) are copied twice. Then we have three versions of each breakable
490 item: one version if there is no line break, one version that is printed
491 before the line break (at the end of a system), one version that is
492 printed after the line break.
494 Whether these versions are visible and take up space, is determined by
495 the outcome of the @code{visibility-lambda}. This grob property is a
496 function taking a direction (-1, 0 or 1) as argument. It returns a cons
497 of booleans, signifying whether this grob should be transparent and have
500 @node Grob Scheme functions
501 @unnumberedsubsec Grob Scheme functions
503 Grob properties can be manipulated from Scheme. In practice, most
504 manipulations are coded in C++ because of tradition.
506 @defun ly-get-grob-property g sym
507 Get the value of a value in grob @var{g} of property @var{sym}. It
508 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
511 @defun ly-set-grob-property g sym val
512 Set @var{sym} in grob @var{g} to value @var{val}
515 @defun ly-get-spanner-bound spanner dir
516 Get one of the bounds of @var{spanner}. @var{dir} may be @code{-1} for
517 left, and @code{1} for right.
521 Typecheck: is @var{g} a grob?
532 @cindex Output description
534 The objective of any typesetting system is to put ink on paper in the
535 right places. For LilyPond, this final stage is left to the @TeX{} and
536 the printer subsystem. For lily, the last stage in processing a score is
537 outputting a description of what to put where. This description roughly
546 you merely have to look at the tex output of lily to see this.
547 Internally these instructions are encoded in Molecules.@footnote{At some
548 point LilyPond also contained Atom-objects, but they have been replaced
549 by Scheme expressions, making the name outdated.} A molecule is
550 what-to-print-where information that also contains dimension information
551 (how large is this glyph?).
553 Conceptually, Molecules can be constructed from Scheme code, by
554 translating a Molecule and by combining two molecules. In BNF
558 Molecule :: COMBINE Molecule Molecule
559 | TRANSLATE Offset Molecule
564 If you are interested in seeing how this information is stored, you
565 can run with the @code{-f scm} option. The scheme expressions are then
566 dumped in the output file.
568 All visible, i.e. non-transparant, grobs have a callback to create a
569 Molecule. The name of the property is @code{molecule-callback}, and its
570 value should be a Scheme function taking one argument (the grob) and
571 returning a Molecule. Most molecule callbacks are written in C++, but
572 you can also write them in Scheme. An example is provided in
573 @code{input/regression/molecule-hacking.ly}.
580 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
581 Construct a molecule by putting @var{mol2} next to
582 @var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be
583 -1 (left or down) or 1 (right or up). @var{padding} specifies extra
584 space to add in between measured in global staff space.
587 @defun ly-get-molecule-extent! mol axis
588 Return a pair of numbers signifying the extent of @var{mol} in
589 @var{axis} direction (0 or 1 for x and y axis respectively).
592 @defun ly-set-molecule-extent! mol axis extent
593 Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in
594 @var{axis} direction (0 or 1 for x- and y-axis respectively).
596 Note that an extent @code{(A . B)} is an interval and hence @code{A} is
597 smaller than @code{B}, and is often negative.
602 @section Font metrics
604 The font object represents the metric information of a font. Every font
605 that is loaded into LilyPond can be accessed via Scheme.
607 LilyPond only needs to know the dimension of glyph to be able to process
608 them. This information is stored in font metric files. LilyPond can read
609 two types of font-metrics: @TeX{} Font Metric files (TFM files) and
610 Adobe Font Metric files (AFM files). LilyPond will always try to load
611 AFM files first they files are more versatile.
613 @defun ly-get-default-font gr
614 This returns the default font for grob @var{gr}.
617 @defun ly-find-glyph-by-name font name
618 This function retrieves a Molecule for the glyph named @var{name} in
619 @var{font}. The font must be available as an AFM file.
624 @node Miscellaneous Scheme functions
625 @section Miscellaneous Scheme functions
629 Scheme callable function to issue the warning @code{msg}.
633 Return the current lilypond version as a list, e.g.
634 @code{(1 3 127 uu1)}.
637 @defun ly-gulp-file name
638 Read the file named @var{name}, and return its contents in a string. The
639 file is looked up using the lilypond search path.
644 type predicate. A direction is a -1, 0 or 1.
647 @defun ly-number->string num
648 converts @var{num} to a string without generating many decimals. It
649 leaves a space at the end.
652 @defun set-lily-option sym val
653 Set a global option for the program. Supported options include
656 If set to true, generate human readable MIDI
659 This function is useful to call from the command line: @code{lilypond -e
660 "(set-lily-option 'midi-debug #t)"}