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
     (parser location arg1 arg2 …)
     (type1? type2? …)
   body)

where

`parser`	needs to be literally `parser` in order to give LilyPond code blocks (`#{`…`#}`) access to the parser.
`location`	needs 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.
`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 `location` parameter.
`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.

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.

2.2.1 Scheme function definitions

See also

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