Extending LilyPond: 2.2.1 Scheme function definitions

[ << Interfaces for programmers ]	[Top][Contents][Index][ ? ]			[ LilyPond Scheme interfaces >> ]
[ < Scheme functions ]		[ Up : Scheme functions ]	[ Scheme function usage > ]

2.2.1 Scheme function definitions

The general form for defining scheme functions is:

function =
#(define-scheme-function
     (arg1 arg2 …)
     (type1? type2? …)
   body)

where

`argN`	`n`th 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 current input location.
`body`	A 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.

Some 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 will change that interpretation. 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.

2.2.1 Scheme function definitions

See also

LilyPond — Extending v2.21.0 (开发分支).