A.21 Technical glossary

This glossary lists some the technical terms and concepts used internally in LilyPond. These terms may appear in the manuals, on mailing lists or in the source code.

alist

An association list or alist for short is a Scheme pair that associates a value with a key: (key . value). For example, in scm/lily.scm, the alist type-p-name-alist associates certain type predicates (e.g., ly:music?) with names (e.g., “music”) so that type check failures can be reported with a console message that includes the name of the expected type predicate.

callback

A callback is a routine, function or method whose reference is passed as an argument in a call to another routine, thus allowing the called routine to invoke it. The technique enables a lower-level software layer to call a function defined in a higher layer. Callbacks are used extensively in LilyPond to make user-level Scheme code control many low-level actions.

closure

In Scheme, a closure is created when a function, usually a lambda expression (i.e., an ad-hoc, anonymous function), is passed as a variable. The closure contains the function’s code plus references to the lexical bindings of the function’s free variables (i.e., those variables used in the expression but defined outside it). When this function is applied to different arguments later, the free variable bindings that were captured in the closure are used to obtain the values of the free variables, which in turn are used in the calculation. One useful property of closures is the preservation of internal variable values between invocations, thus permitting state to be maintained.

glyph

A glyph is a particular graphical representation of a typographic character, or a combination of two (or more) characters forming a ligature. A set of glyphs with a single style and shape comprise a font, and a set of fonts covering several styles and sizes comprise a typeface.

See also: Fonts, Special characters.

grob

LilyPond objects that represent items of notation in the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc., are called ‘Layout objects’, often known as ‘GRaphical OBjects’, or grobs for short. They are represented by instances of the Grob class.

See also: Objects and interfaces, Properties of layout objects.
Naming conventions.
grob-interface, All layout objects.

immutable

An immutable object is one whose state cannot be modified after creation, in contrast to a mutable object, which can be modified after creation.

In LilyPond, immutable or shared properties define the default style and behavior of grobs. They are shared between many objects. In apparent contradiction to the name, they can be changed using \override and \revert.

See also below for mutable objects.

interface

Actions and properties that are common to a number of grobs are grouped together in an object called a grob-interface, or just interface for short.

See also: Naming conventions, Layout interfaces.
Objects and interfaces, Properties found in interfaces.
Graphical Object Interfaces.

lexer

A lexer is a program that converts a sequence of characters into a sequence of tokens, a process called lexical analysis. The LilyPond lexer converts the stream obtained from an input .ly file into a tokenized stream more suited to the next stage of processing – parsing (see below). The LilyPond lexer is built using the flex program from the lexer file lily/lexer.ll, which contains the lexical rules. This file is part of the source code and not included in the LilyPond binary installation.

mutable

A mutable object is one whose state can be modified after creation, in contrast to an immutable object, whose state is fixed at the time of creation.

In LilyPond, mutable properties contain values that are specific to one grob. Typically, lists of other objects or results from computations are stored in mutable properties.

See also above for immutable objects.

output-def

An instance of the Output-def class contains the methods and data structures associated with an output block. Instances are created for MIDI, layout, and paper blocks.

parser

A parser analyzes the sequence of tokens produced by a lexer to determine its grammatical structure, grouping the tokens progressively into larger groupings according to the rules of the grammar. If the sequence of tokens is valid the end product is a tree of tokens whose root is the grammar’s start symbol. If this cannot be achieved the file is invalid and an appropriate error message is produced. The syntactic groupings and the rules for constructing the groupings from their parts for the LilyPond syntax are defined in file lily/parser.yy. During compilation, this file gets processed by a parser generator, bison, to build the parser. It is part of the source code and not included in the LilyPond binary installation.

parser variable

These are variables defined directly in Scheme. Their direct use by users is strongly discouraged because their scoping semantics can be confusing.

When the value of such a variable is changed in a .ly file, the change is global, and unless explicitly reverted, the new value persists to the end of the file, affecting subsequent \score blocks as well as external files added with the \include command. This can lead to unintended consequences, and in complex typesetting projects the consequent errors can be difficult to track down.

Among others, the following parser variables are used by LilyPond:

• afterGraceFraction
• musicQuotes
• output-count
• output-suffix
• partCombineListener
• pitchnames
• toplevel-bookparts
• toplevel-scores
• showLastLength
• showFirstLength

prob

PRoperty OBjects, or probs for short, are instances of the Prob class, a simple base class for objects that have mutable and immutable property alists and the methods to manipulate them. The Music and Stream_event classes derive from Prob. Instances of the Prob class are also created to hold the formatted content of system grobs and titling blocks during page layout.

smob

Smobs, or ScheMe OBjects, are part of the mechanism used by Guile to export C and C++ objects to Scheme code. In LilyPond, smobs are created from C++ objects through macros. There are two types of smob objects: simple smobs, intended for simple immutable objects like numbers, and complex smobs, used for objects with identities. If you have access to the LilyPond sources, more information can be found in file lily/includes/smob.hh.

spanner

Spanners are a class of grobs that are not horizontally fixed on one point of the score but extend from one point to another. Examples include beams, ties, and slurs, as well as hairpins and staff lines. Whereas non-spanners can only be broken into at most two visible pieces (for example, a clef duplicated at the end of the line and the beginning of the next line), spanners are broken into as many pieces as required by their start and end points (such as a long crescendo extending on three systems, or staff lines, which always span the whole score).

Technically, spanners are defined as grobs having the spanner-interface; on the C++ side of LilyPond, they are instances of the Spanner subclass of Grob. The left and right bounds of a spanner can be retrieved and set using ly:spanner-bound and ly:spanner-set-bound!, respectively. The bounds are always items. The X parent of a spanner has little musical sense, but is usually set to the left bound.

See also: Spanners.
all-layout-objects, spanner-interface.

stencil

An instance of the Stencil class holds the information required to print a typographical object, a stencil. It is a simple smob containing a confining box, which defines the vertical and horizontal extents of the object, and a Scheme expression, which prints the object when evaluated. Stencils may be combined to form more complex stencils defined by a tree of Scheme expressions, which in turn are formed from the Scheme expressions of the component stencils.

The stencil property, which connects a grob to its stencil, is defined in the grob-interface interface.

See also grob-interface.