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.
`argN`	`n`th argument
`typeN?`	a Scheme type predicate for which `argN` must return `#t`. Some of these predicates are specially recognized by the parser, see below. 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`.

Some type predicates are specially handled by the parser since it can’t recognize the arguments reliably otherwise. Currently these are ly:pitch? and ly:duration?.

Suitability of arguments for all other 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 to Lilypond. There are also some other ambiguities that 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 decides by asking the predicates. That means that you should avoid permissive predicates like scheme? if you have a particular use in mind instead of a general purpose function.

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

2.2.1 Scheme function definitions

See also

LilyPond — Extending