X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fextending%2Fprogramming-interface.itely;h=1e8e92dbbd8f084ea6f6e9684dc1049d4a98a67c;hb=abf44faa7aff3481efcd8b241c352c6d5080ccd5;hp=32c33634a1a48935b00690224a52829129531a9b;hpb=235de94b7408e9badc7b82c8e0dae8f05009adc3;p=lilypond.git diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely index 32c33634a1..1e8e92dbbd 100644 --- a/Documentation/extending/programming-interface.itely +++ b/Documentation/extending/programming-interface.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.13.36" +@c \version "2.14.0" @node Interfaces for programmers @chapter Interfaces for programmers @@ -18,7 +18,10 @@ not familiar with Scheme, you may wish to read our @ref{Scheme tutorial}. @menu +* Lilypond code blocks:: +* Scheme functions:: * Music functions:: +* Event functions:: * Markup functions:: * Contexts for programmers:: * Callback functions:: @@ -26,63 +29,238 @@ not familiar with Scheme, you may wish to read our * Difficult tweaks:: @end menu +@node Lilypond code blocks +@section Lilypond code blocks -@node Music functions -@section Music functions +Lilypond code blocks look like +@example + #@{ @var{Lilypond code} #@} +@end example +They can be used anywhere where you can write Scheme code: the Scheme +reader actually is changed for accommodating LilyPond code blocks. When +the LilyPond code block is being read, it is parsed superficially and +replaced by a call to the LilyPond @code{parser} which is executed at +runtime to interpret the LilyPond code block. -@emph{Music functions} are scheme procedures that can create music -expressions automatically, and can be used to greatly simplify the -input file. +The point of the superficial parsing is the interpretation of @code{$} +signs which can be used for splicing in expressions from the surrounding +lexical Scheme context (like @code{let} variables and function +parameters). @code{$} can be used in the following ways: + +@table @code +@item $$ +just passes a single @code{$} to the LilyPond parser. +@item $@var{form} +will evaluate the Scheme form at runtime and splice its value as an +identifier @code{\form} into the LilyPond parser. Depending on the +value type, it may be interpreted as several different syntactic +entities. +@item #$@var{form} +will evaluate the Scheme form at runtime and splice its value as a +Scheme expression into the LilyPond parser. +@item #@var{form} +Forms in Scheme expressions started with @code{#} are read and parsed +recursively for @code{$} signs. Those are treated as follows: +@item #@dots{}$@var{variable} +splices the value of the variable into the surrounding expression. +@item #@dots{}($ @var{form} @dots{}) +splices the value of the form into the surrounding expression. As +opposed to a LilyPond level @code{$@var{form}}, you need to separate the +form with a blank, making @code{$} be recognizable as a separate Scheme +symbol. +@end table + +A LilyPond code block may contain anything that you can use on the right +side of an assignment. In addition, an empty LilyPond block corresponds +to a void music expression, and a LilyPond block containing multiple +music events gets turned into a sequential music expression. + +@node Scheme functions +@section Scheme functions +@cindex Scheme functions (LilyPond syntax) + +@emph{Scheme functions} are Scheme procedures that can create Scheme +expressions from input written in LilyPond syntax. They can be called +in pretty much all places where using @code{#} for specifying a value in +Scheme syntax is allowed. While Scheme has functions of its own, this +chapter is concerned with @emph{syntactic} functions, functions that +receive arguments specified in LilyPond syntax. @menu -* Music function syntax:: -* Simple substitution functions:: -* Intermediate substitution functions:: -* Mathematics in functions:: -* Functions without arguments:: -* Void functions:: +* Scheme function definitions:: +* Scheme function usage:: +* Void scheme functions:: @end menu +@node Scheme function definitions +@subsection Scheme function definitions +@funindex define-scheme-function -@node Music function syntax -@subsection Music function syntax - -The general form for music functions is: +The general form for defining scheme functions is: @example function = -#(define-music-function +#(define-scheme-function (parser location @var{arg1} @var{arg2} @dots{}) (@var{type1?} @var{type2?} @dots{}) - @var{music}) + @var{body}) @end example @noindent where @multitable @columnfractions .33 .66 +@item @code{parser} +@tab needs to be literally @code{parser} in order to give LilyPond code +blocks (@code{#@{}@dots{}@code{#@}}) access to the parser. + @item @code{@var{argN}} @tab @var{n}th argument @item @code{@var{typeN?}} -@tab a scheme @emph{type predicate} for which @code{@var{argN}} -must return @code{#t}. - -@item @code{@var{music}} -@tab A music expression, optionally written in scheme, with any -LilyPond code enclosed in hashed braces -(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Within LilyPond code -blocks, use @code{$} to reference function arguments (eg., -@samp{$arg1}) or to start an inline scheme expression containing -function arguments (eg., @w{@samp{$(cons arg1 arg2)}}). - +@tab a Scheme @emph{type predicate} for which @code{@var{argN}} +must return @code{#t}. Some of these predicates are specially +recognized by the parser, see below. There is also a special form +@code{(@emph{predicate?} @emph{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, @code{#f} is used as the default. +Default values are not verified with @emph{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 @code{origin} to the @code{location} parameter. + +@item @code{@var{body}} +@tab 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 +(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in @ref{Lilypond +code blocks}. Within LilyPond code blocks, use @code{$} to reference +function arguments (eg., @samp{$arg1}) or to start an inline Scheme +expression containing function arguments (eg., @w{@samp{$(cons arg1 +arg2)}}). If your function returns a music expression, it is cloned and +given the correct @code{origin}. @end multitable @noindent +Some type predicates are specially recognized by the parser and will +make the parser look for the respective arguments in LilyPond syntax +rather than in Scheme syntax. Currently these are @code{ly:music?}, +@code{markup?}, @code{ly:pitch?}, and @code{ly:duration?}. + +If you really want to input one of the special items as a Scheme rather +than a LilyPond expression, you may write them as a Scheme expression +that calls @code{ly:export} at its outermost level. + +Other type predicates, including user-defined ones, will make the +respective argument only be accepted as a Scheme expression, usually +introduced with @code{#} or as the result of calling a scheme function +itself. + For a list of available type predicates, see -@ruser{Predefined type predicates}. User-defined type predicates -are also allowed. +@ruser{Predefined type predicates}. + +@seealso + +Notation Reference: +@ruser{Predefined type predicates}. + +Installed Files: +@file{lily/music-scheme.cc}, +@file{scm/c++.scm}, +@file{scm/lily.scm}. + +@node Scheme function usage +@subsection Scheme function usage + +Scheme functions can be called pretty much anywhere where a Scheme +expression starting with @code{#} can be written. You call a scheme +function by writing its name preceded by @code{\}, followed by its +arguments. The last argument can't be an optional argument. If there +are several optional arguments in a row, they are filled with values +left to right. Once an optional argument can't match input, it and all +immediately following optional arguments are replaced with their default +values, and the matching continues with the next non-optional argument. + +Apart from places where a Scheme value is required, there are a few +places where @code{#} expressions are accepted and evaluated for their +side effects but otherwise ignored. Mostly those are the places where +an assignment would be acceptable as well. + +There are a few special places where an argument matching +@code{ly:music?} has to be either a music identifier or a music +expression enclosed in @code{@{}@dots{}@code{@}} or +@code{<<}@dots{}@code{>>} explicitly, so that possibly following +optional durations or postevents can't be confused with additional +arguments. One obvious place is before a @code{ly:duration?} +predicate. Another is as the last argument of a scheme function when it +is used in a place where such optional parts could be considered either +part of the music argument or not. + +In those rare cases, you have to delimit your music arguments +appropriately to spare LilyPond from getting confused. + +@node Void scheme functions +@subsection Void scheme functions + +Sometimes a function is only executed for its side effects. In that +case, using a scheme function means that its value will not usually be +considered: + +@example +noPointAndClick = +#(define-scheme-function + (parser location) + () + (ly:set-option 'point-and-click #f)) +... +\noPointAndClick % disable point and click +@end example + +@node Music functions +@section Music functions +@cindex music functions + +@emph{Music functions} are Scheme procedures that can create music +expressions automatically, and can be used to greatly simplify the +input file. + +@menu +* Music function definitions:: +* Music function usage:: +* Simple substitution functions:: +* Intermediate substitution functions:: +* Mathematics in functions:: +* Functions without arguments:: +* Void music functions:: +@end menu + + +@node Music function definitions +@subsection Music function definitions +@cindex defining music functions +@funindex define-music-function + +The general form for defining music functions is: + +@example +function = +#(define-music-function + (parser location @var{arg1} @var{arg2} @dots{}) + (@var{type1?} @var{type2?} @dots{}) + @var{body}) +@end example + +@noindent +quite in analogy to @ref{Scheme function definitions}. More often than +not, @var{body} will be a @ref{Lilypond code blocks, Lilypond code block}. + +For a list of available type predicates, see +@ruser{Predefined type predicates}. @seealso @@ -95,6 +273,42 @@ Installed Files: @file{scm/lily.scm}. +@node Music function usage +@subsection Music function usage +Music functions may currently be used in three places. Depending on +where they are used, restrictions apply in order to be able to parse +them unambiguously. The result a music function returns must be +compatible with the context in which it is called. + +@itemize +@item +At top level in a music expression. There are no special restrictions +on the argument list. + +@item +As a post-event, explicitly started with a direction indicator (one of +@code{-}, @code{^}, @w{and @code{_}}). All trailing arguments of the +music function with the predicate @code{ly:music?} will get parsed also +as post-events (if the last argument is a scheme function, this will +hold for trailing @code{ly:music?} arguments of the scheme function +instead). Note that returning a post-event will be acceptable for music +functions called as normal music, leading to a result roughly equivalent +to +@example +s 1*0-\fun +@end example + +@item +As a chord constituent. All trailing arguments of the music function +with the predicate @code{ly:music?} will get parsed also as chord +constituents. +@end itemize + +@noindent +The special rules for trailing arguments make it possible to write +polymorphic functions like @code{\tweak} that can be applied to +different constructs. + @node Simple substitution functions @subsection Simple substitution functions @@ -233,31 +447,35 @@ lilypond -d display-bar-numbers FILENAME.ly @end example -@node Void functions -@subsection Void functions - -A music function must return a music expression, but sometimes we -may want to have a function that does not involve music (such as -turning off Point and Click). To do this, we return a @code{void} -music expression. - -That is why the form that is returned is the -@w{@code{(make-music @dots{})}}. With the @code{'void} property -set to @code{#t}, the parser is told to actually disregard this -returned music expression. Thus the important part of the void -music function is the processing done by the function, not the -music expression that is returned. - -@example -noPointAndClick = -#(define-music-function - (parser location) - () - (ly:set-option 'point-and-click #f) - (make-music 'SequentialMusic 'void #t)) -... -\noPointAndClick % disable point and click -@end example +@node Void music functions +@subsection Void music functions + +A music function must return a music expression. If you want to execute +a function only for its side effect, it might make more sense to use a +scheme function instead. But there may be cases where you sometimes +want to produce a music expression, and sometimes not (like in the +previous example). Returning a @code{void} music expression via +@code{#@{ #@}} will do that. + +@node Event functions +@section Event functions +@funindex define-event-function +@cindex event functions + +To use a music function in the place of an event, you need to write a +direction indicator before it. But sometimes, this does not quite match +the syntax of constructs you want to replace. For example, if you want +to write dynamics commands, those are usually attached without direction +indicator, like @code{c'\pp}. Here is a way to write arbitrary +dynamics: +@lilypond[quote,verbatim,raggedright] +dyn=#(define-event-function (parser location arg) (markup?) + (make-dynamic-script arg)) +\relative c' { c\dyn pfsss } +@end lilypond +You could do the same using a music function, but then you always would +have to write a direction indicator before calling it, like +@code{@w{c-\dyn pfsss}}. @node Markup functions @@ -289,13 +507,16 @@ providing a LilyPond-like syntax. For example, @noindent is equivalent to: @example -\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @} - \larger \line @{ foo bar baz @} @} +#@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @} + \larger \line @{ foo bar baz @} @} #@} @end example @noindent This example demonstrates the main translation rules between regular -LilyPond markup syntax and Scheme markup syntax. +LilyPond markup syntax and Scheme markup syntax. Using @code{#@{ +@dots{} #@}} for entering in LilyPond syntax will often be most +convenient, but we explain how to use the @code{markup} macro to get a +Scheme-only solution. @quotation @multitable @columnfractions .3 .3 @@ -370,7 +591,7 @@ The @code{raise-markup} function first creates the stencil for the @code{text example} string, and then it raises that Stencil by 0.5 staff space. This is a rather simple example; more complex examples are in the rest -of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}. +of this section, and in @file{scm/define-markup-commands.scm}. @node New markup command definition @@ -498,7 +719,8 @@ Then, the padding between the two boxes is considered too small, so we override it too: @lilypond[quote,verbatim,ragged-right] -\markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A +\markup \override #'(box-padding . 0.4) \box + \override #'(box-padding . 0.6) \box A @end lilypond Repeating this lengthy markup would be painful. This is where a markup @@ -506,6 +728,16 @@ command is needed. Thus, we write a @code{double-box} markup command, taking one argument (the text). This draws the two boxes, with some padding. +@lisp +#(define-markup-command (double-box layout props text) (markup?) + "Draw a double box around text." + (interpret-markup layout props + #@{\markup \override #'(box-padding . 0.4) \box + \override #'(box-padding . 0.6) \box @{ $text @}#@})) +@end lisp + +or, equivalently + @lisp #(define-markup-command (double-box layout props text) (markup?) "Draw a double box around text." @@ -517,10 +749,10 @@ padding. @code{text} is the name of the command argument, and @code{markup?} its type: it identifies it as a markup. The @code{interpret-markup} function is used in most of markup commands: it builds a stencil, using -@code{layout}, @code{props}, and a markup. Here, this markup is built -using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}. -The transformation from @code{\markup} expression to scheme -markup expression is straight-forward. +@code{layout}, @code{props}, and a markup. In the second case, this +markup is built using the @code{markup} scheme macro, see @ref{Markup +construction in Scheme}. The transformation from @code{\markup} +expression to scheme markup expression is straight-forward. The new command can be used as follow: @@ -537,6 +769,19 @@ and the text. So we will introduce a new property, @code{box-padding} will be used for the inner padding. The new code is now as follows: +@lisp +#(define-markup-command (double-box layout props text) (markup?) + #:properties ((inter-box-padding 0.4) + (box-padding 0.6)) + "Draw a double box around text." + (interpret-markup layout props + #@{\markup \override #`(box-padding . ,$inter-box-padding) \box + \override #`(box-padding . ,$box-padding) \box + @{ $text @} #@})) +@end lisp + +Again, the equivalent version using the markup macro would be: + @lisp #(define-markup-command (double-box layout props text) (markup?) #:properties ((inter-box-padding 0.4) @@ -566,8 +811,9 @@ customized: (box-padding 0.6)) "Draw a double box around text." (interpret-markup layout props - (markup #:override `(box-padding . ,inter-box-padding) #:box - #:override `(box-padding . ,box-padding) #:box text))) + #{\markup \override #`(box-padding . ,$inter-box-padding) \box + \override #`(box-padding . ,$box-padding) \box + { $text } #})) \markup \double-box A \markup \override #'(inter-box-padding . 0.8) \double-box A @@ -579,7 +825,7 @@ customized: A good way to start writing a new markup command, is to take example on a builtin one. Most of the markup commands provided with LilyPond can be -found in file @file{scm/@/define@/-markup@/-commands@/.scm}. +found in file @file{scm/define-markup-commands.scm}. For instance, we would like to adapt the @code{\draw-line} command, to draw a double line instead. The @code{\draw-line} command is defined as @@ -668,6 +914,16 @@ a single stencil, the former returns a list of stencils. In the following example, a @code{\paragraph} markup list command is defined, which returns a list of justified lines, the first one being indented. The indent width is taken from the @code{props} argument. + +@example +#(define-markup-list-command (paragraph layout props args) (markup-list?) + #:properties ((par-indent 2)) + (interpret-markup-list layout props + #@{\markuplines \justified-lines @{ \hspace #$par-indent $args @} #@})) +@end example + + +The version using just Scheme is more complex: @example #(define-markup-list-command (paragraph layout props args) (markup-list?) #:properties ((par-indent 2)) @@ -683,11 +939,11 @@ Besides the usual @code{layout} and @code{props} arguments, the First, the function gets the indent width, a property here named @code{par-indent}, from the property list @code{props}. If the property is not found, the default value is @code{2}. Then, a -list of justified lines is made using the -@code{make-justified-lines-markup-list} function, which is related -to the @code{\justified-lines} built-in markup list command. A -horizontal space is added at the beginning using the -@code{make-hspace-markup} function. Finally, the markup list is +list of justified lines is made using the built-in markup list command +@code{\justified-lines}, which is related to the +@code{make-justified-lines-markup-list} function. A +horizontal space is added at the beginning using @code{\hspace} (or the +@code{make-hspace-markup} function). Finally, the markup list is interpreted using the @code{interpret-markup-list} function. This new markup list command can be used as follows: