| [ << 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 | nth 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.
See also
Notation Reference: Predefined type predicates.
Installed Files: ‘lily/music-scheme.cc’, ‘scm/c++.scm’, ‘scm/lily.scm’.
| [ << Interfaces for programmers ] | [Top][Contents][Index] | [ LilyPond Scheme interfaces >> ] |
| [ < Scheme functions ] | [ Up : Scheme functions ] | [ Scheme function usage > ] |