2.2.1 Scheme function definitions

The general form for defining scheme functions is:

function =
     (parser location arg1 arg2 …)
     (type1? type2? …)


parserneeds to be literally parser in order to give LilyPond code blocks (#{#}) access to the parser.
locationneeds to be literally location in order to provide access to the input location object, which is used to provide error messages with file names and line numbers.
argNnth argument
typeN?a Scheme type predicate for which argN must return #t. There is also a special form (predicate? default) for specifying optional arguments. If the actual argument is missing when the function is being called, the default value is substituted instead. Default values are evaluated at definition time (including LilyPond code blocks!), so if you need a default calculated at runtime, instead write a special value you can easily recognize. If you write the predicate in parentheses but don’t follow it with a default value, #f is used as the default. Default values are not verified with predicate? at either definition or run time: it is your responsibility to deal with the values you specify. Default values that happen to be music expressions are copied while setting origin to the location parameter.
bodyA sequence of Scheme forms evaluated in order, the last one being used as the return value of the scheme function. It may contain LilyPond code blocks enclosed in hashed braces ( #{…#} ), like described in LilyPond code blocks. Within LilyPond code blocks, use # to reference function arguments (eg., ‘#arg1’) or to start an inline Scheme expression containing function arguments (eg., ‘#(cons arg1 arg2)’). Where normal Scheme expressions using # don’t do the trick, you might need to revert to immediate Scheme expressions using $, for example as ‘$music’. If your function returns a music expression, it is given a useful value of origin.

Suitability of arguments for the predicates is determined by actually calling the predicate after LilyPond has already converted them into a Scheme expression. As a consequence, the argument can be specified in Scheme syntax if desired (introduced with # or as the result of calling a scheme function), but LilyPond will also convert a number of LilyPond constructs into Scheme before actually checking the predicate on them. Currently, those include music, postevents, simple strings (with or without quotes), numbers, full markups and markup lists, score, book, bookpart, context definition and output definition blocks.

For some kinds of expression (like most music not enclosed in braces) LilyPond needs to look further than the expression itself in order to determine its end. If such an expression were considered for an optional argument by evaluating its predicate, LilyPond would not be able to ‘backup’ when it decides the expression does not fit the parameter. So some forms of music might need to be enclosed in braces to make them acceptable in some circumstances. Some other ambiguities LilyPond sorts out by checking with predicate functions: is ‘-3’ a fingering postevent or a negative number? Is "a" 4 in lyric mode a string followed by a number, or a lyric event of duration 4? LilyPond tries the argument predicate on successive interpretations until success, with an order designed to minimize inconsistent interpretations and lookahead.

For example, a predicate accepting both music expressions and pitches will consider c'' to be a pitch rather than a music expression. Immediately following durations or postevents might not work with that interpretation. So it’s best to avoid overly permissive predicates like scheme? when the application rather calls for more specific argument types.

For a list of available predefined type predicates, see Predefined type predicates.

See also

Notation Reference: Predefined type predicates.

Installed Files: ‘lily/music-scheme.cc’, ‘scm/c++.scm’, ‘scm/lily.scm’.

Other languages: deutsch, español, français.
About automatic language selection.

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