1.2.7 LilyPond compound variables


Two-dimensional offsets (X and Y coordinates) are stored as pairs. The car of the offset is the X coordinate, and the cdr is the Y coordinate.

\override TextScript.extra-offset = #'(1 . 2)

This assigns the pair (1 . 2) to the extra-offset property of the TextScript object. These numbers are measured in staff-spaces, so this command moves the object 1 staff space to the right, and 2 spaces up.

Procedures for working with offsets are found in ‘scm/lily-library.scm’.


Fractions as used by LilyPond are again stored as pairs, this time of unsigned integers. While Scheme can represent rational numbers as a native type, musically ‘2/4’ and ‘1/2’ are not the same, and we need to be able to distinguish between them. Similarly there are no negative ‘fractions’ in LilyPond’s mind. So 2/4 in LilyPond means (2 . 4) in Scheme, and #2/4 in LilyPond means 1/2 in Scheme.


Pairs are also used to store intervals, which represent a range of numbers from the minimum (the car) to the maximum (the cdr). Intervals are used to store the X- and Y- extents of printable objects. For X extents, the car is the left hand X coordinate, and the cdr is the right hand X coordinate. For Y extents, the car is the bottom coordinate, and the cdr is the top coordinate.

Procedures for working with intervals are found in ‘scm/lily-library.scm’. These procedures should be used when possible to ensure consistency of code.

Property alists

A property alist is a LilyPond data structure that is an alist whose keys are properties and whose values are Scheme expressions that give the desired value for the property.

LilyPond properties are Scheme symbols, such as 'thickness.

Alist chains

An alist chain is a list containing property alists.

The set of all properties that will apply to a grob is typically stored as an alist chain. In order to find the value for a particular property that a grob should have, each alist in the chain is searched in order, looking for an entry containing the property key. The first alist entry found is returned, and the value is the property value.

The Scheme procedure chain-assoc-get is normally used to get grob property values.

LilyPond — Extending v2.24.3 (stable-branch).