5.3.8 Modifying alists

Some user-configurable properties are internally represented as alists (association lists), which store pairs of keys and values. The structure of an alist is:

'((key1 . value1)
  (key2 . value2)
  (key3 . value3)
  …)

If an alist is a grob property or \paper variable, its keys can be modified individually without affecting other keys.

For example, to reduce the space between adjacent staves in a staff group, use the staff-staff-spacing property of the StaffGrouper grob. The property is an alist with four keys: basic-distance, minimum-distance, padding, and stretchability. The standard settings for this property are listed in the “Backend” section of the Internals Reference (see StaffGrouper):

'((basic-distance . 9)
  (minimum-distance . 7)
  (padding . 1)
  (stretchability . 5))

One way to bring the staves closer together is by reducing the value of the basic-distance key (9) to match the value of minimum-distance (7). To modify a single key individually, use a nested declaration:

% default space between staves
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% reduced space between staves
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper.staff-staff-spacing.basic-distance = 7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

Using a nested declaration will update the specified key (such as basic-distance in the above example) without altering any other keys already set for the same property.

Now suppose we want the staves to be as close as possible without overlapping. The simplest way to do this is to set all four alist keys to zero. However, it is not necessary to enter four nested declarations, one for each key. Instead, the property can be completely redefined with one declaration, as an alist:

\new PianoStaff \with {
  \override StaffGrouper.staff-staff-spacing =
    #'((basic-distance . 0)
       (minimum-distance . 0)
       (padding . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

Note that any keys not explicitly listed in the alist definition will be reset to their default-when-unset values. In the case of staff-staff-spacing, any unset key values would be reset to zero (except stretchability, which takes the value of basic-distance when unset). Thus the following two declarations are equivalent:

\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7))

\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7)
     (minimum-distance . 0)
     (padding . 0)
     (stretchability . 7))

One (possibly unintended) consequence of this is the removal of any standard settings that are set in an initialization file and loaded each time an input file is compiled. In the above example, the standard settings for padding and minimum-distance (defined in scm/define-grobs.scm) are reset to their default-when-unset values (zero for both keys). Defining a property or variable as an alist (of any size) will always reset all unset key values to their default-when-unset values. Unless this is the intended result, it is safer to update key values individually with a nested declaration.