2.2.2 Scheme function usage

Scheme functions can be called pretty much anywhere where a Scheme expression starting with ‘#’ can be written. You call a Scheme function from LilyPond by writing its name preceded by \, followed by its arguments. Once an optional argument predicate does not match an argument, LilyPond skips this and all following optional arguments, replacing them with their specified default, and ‘backs up’ the argument that did not match to the place of the next mandatory argument. Since the backed up argument needs to go somewhere, optional arguments are not actually considered optional unless followed by a mandatory argument.

There is one exception: if you write \default in the place of an optional argument, this and all following optional arguments are skipped and replaced by their default. This works even when no mandatory argument follows since \default does not need to get backed up. The mark and key commands make use of that trick to provide their default behavior when just followed by \default.

Apart from places where a Scheme value is required, there are a few places where ‘#’ expressions are currently accepted and evaluated for their side effects but otherwise ignored. Mostly those are the places where an assignment would be acceptable as well.

Since it is a bad idea to return values that can be misinterpreted in some context, you should use normal Scheme functions only for those cases where you always return a useful value, and use void Scheme functions (see Void Scheme functions) otherwise.

For convenience, Scheme functions may also be called directly from Scheme bypassing the LilyPond parser. Their name can be used like the name of an ordinary function. Typechecking of the arguments and skipping optional arguments will happen in the same manner as when called from within LilyPond, with the Scheme value *unspecified* taking the role of the \default reserved word for explicitly skipping optional arguments. Optional arguments at the end of an argument list can just be omitted without indication when called via Scheme.