LilyPond Notation Reference: A.20 Technical glossary

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < Default values for outside-staff-priority ]	[ Up : Notation manual tables ]	[ alist > ]

A.20 Technical glossary

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

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < Technical glossary ]	[ Up : Technical glossary ]	[ callback > ]

alist

An association list or alist for short is a Scheme pair which 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.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < alist ]	[ Up : Technical glossary ]	[ closure > ]

callback

A callback is a routine, function or method whose reference is passed as an argument in a call to another routine, so 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 permit user-level Scheme code to define how many low-level actions are performed.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < callback ]	[ Up : Technical glossary ]	[ glyph > ]

closure

In Scheme, a closure is created when a function, usually a lambda expression, 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 to be used in the calculation. One useful property of closures is the retention of internal variable values between invocations, so permitting state to be maintained.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < closure ]	[ Up : Technical glossary ]	[ grob > ]

glyph

A glyph is a particular graphical representation of a typographic character, or a combination of two characters formating 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.

grob

LilyPond objects which 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.

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.

interface

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

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 parser). The LilyPond lexer is built with Flex from the lexer file ‘lily/lexer.ll’, which contains the lexical rules. This file is part of the source code and is not included in the LilyPond binary installation.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < lexer ]	[ Up : Technical glossary ]	[ output-def > ]

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.

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.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < output-def ]	[ Up : Technical glossary ]	[ parser variable > ]

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 ‘lily/parser.yy’ and shown in Backus Normal Form (BNF) in LilyPond grammar. This file is used to build the parser during the program build by the parser generator, Bison. It is part of the source code and is not included in the LilyPond binary installation.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < parser ]	[ Up : Technical glossary ]	[ prob > ]

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 will persist 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.

LilyPond uses the following parser variables:

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

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < parser variable ]	[ Up : Technical glossary ]	[ smob > ]

prob

PRoperty OBjects, or probs for short, are instances of the Prob class, a simple base class for objects which 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.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < prob ]	[ Up : Technical glossary ]	[ spanner > ]

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 ‘lily/includes/smob.hh’.

[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < smob ]	[ Up : Technical glossary ]	[ stencil > ]

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.

stencil

An instance of the stencil class holds the information required to print a typographical object. It is a simple smob containing a confining box, which defines the vertical and horizontal extents of the object, and a Scheme expression which will print the object when evaluated. Stencils may be combined to form more complex stencils defined by a tree of Scheme expressions 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.

A.20 Technical glossary

alist

callback

closure

glyph

See also

grob

See also

immutable

See also

interface

See also

lexer

mutable

See also

output-def

parser

parser variable

prob

smob

spanner

See also

stencil

See also

LilyPond — Notation Reference v2.23.82 (development-branch).