X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=da2960fd66dd4e5ad4df334e58e8b2d7044a2d69;hb=f4d3d9b17314df3095b017226bf19602f4ac540a;hp=fe2c884da2a1d8814e66ff942ee749f5bfa67a56;hpb=3733cad6c0b0654779b8c74c99a0bd7255ce4b82;p=lilypond.git diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index fe2c884da2..da2960fd66 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -1,10 +1,18 @@ @c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + @node Interfaces for programmers @chapter Interfaces for programmers Advanced tweaks may be performed by using Scheme. If you are not familiar with Scheme, you may wish to read our -@ref{Scheme tutorial}. +@rlearning{Scheme tutorial}. @menu * Music functions:: @@ -12,7 +20,7 @@ not familiar with Scheme, you may wish to read our * Building complicated functions:: * Markup programmer interface:: * Contexts for programmers:: -* OLD STUFF:: +* Scheme procedures as properties:: @end menu @@ -24,15 +32,17 @@ This section discusses how to create music functions within LilyPond. @menu * Overview of music functions:: * Simple substitution functions:: -* Paired substition functions:: +* Paired substitution functions:: * Mathematics in functions:: * Void functions:: +* Functions without arguments:: +* Overview of available music functions:: @end menu @node Overview of music functions @subsection Overview of music functions -Making a funcion which substitutes a variable into LilyPond +Making a function which substitutes a variable into LilyPond code is easy. The general form of these functions is @example @@ -73,7 +83,7 @@ The @code{parser} and @code{location} argument are mandatory, and are used in some advanced situations. The @code{parser} argument is used to access to the value of another LilyPond variable. The @code{location} argument -is used to set the ``origin'' of the music expression that is built +is used to set the @q{origin} of the music expression that is built by the music function, so that in case of a syntax error LilyPond can tell the user an appropriate place to look in the input file. @@ -122,7 +132,7 @@ tempoMark = #(define-music-function (parser location padding marktext) (number? string?) #{ \once \override Score . RehearsalMark #'padding = $padding - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $marktext } #}) @@ -134,8 +144,8 @@ g c @end lilypond -@node Paired substition functions -@subsection Paired substition functions +@node Paired substitution functions +@subsection Paired substitution functions Some @code{\override} commands require a pair of numbers (called a @code{cons cell} in Scheme). To pass these numbers @@ -211,7 +221,6 @@ withAlt = #(define-music-function (parser location mag music) (number? ly:music? \withAlt #1.5 {c' c'} c'2 } @end lilypond - @node Void functions @subsection Void functions @@ -221,7 +230,7 @@ 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 @code{(make-music ...)}. With the +that is returned is the @code{(make-music ...)}. 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 @@ -238,6 +247,45 @@ noPointAndClick = @end example +@node Functions without arguments +@subsection Functions without arguments + +In most cases a function without arguments should be written +with an variable, + +@example +dolce = \markup@{ \italic \bold dolce @} +@end example + +However, in rare cases it may be useful to create a music function +without arguments, + +@example +displayBarNum = +#(define-music-function (parser location) () + (if (eq? #t (ly:get-option 'display-bar-numbers)) + #@{ \once \override Score.BarNumber #'break-visibility = ##f #@} + #@{#@})) +@end example + +To actually display bar numbers where this function is called, +invoke @command{lilypond} with + +@example +lilypond -d display-bar-numbers FILENAME.ly +@end example + + +@node Overview of available music functions +@subsection Overview of available music functions + +@c fixme ; this should be move somewhere else? +The following commands are music functions + +@include identifiers.tely + + + @node Programmer interfaces @section Programmer interfaces @@ -285,7 +333,7 @@ traLaLa = @{ c'4 d'4 @} @noindent is internally converted to a Scheme definition @example -(define traLaLa @var{Scheme value of ``@code{... }''}) +(define traLaLa @var{Scheme value of `@code{... }'}) @end example This means that input variables and Scheme variables may be freely @@ -293,31 +341,43 @@ mixed. In the following example, a music fragment is stored in the variable @code{traLaLa}, and duplicated using Scheme. The result is imported in a @code{\score} block by means of a second variable @code{twice}: -@example -traLaLa = @{ c'4 d'4 @} + +@lilypond[verbatim] +traLaLa = { c'4 d'4 } + +%% dummy action to deal with parser lookahead +#(display "this needs to be here, sorry!") #(define newLa (map ly:music-deep-copy (list traLaLa traLaLa))) #(define twice (make-sequential-music newLa)) -@{ \twice @} -@end example +{ \twice } +@end lilypond + +Due to parser lookahead + +In this example, the assignment happens after parser has verified that +nothing interesting happens after @code{traLaLa = @{ ... @}}. Without +the dummy statement in the above example, the @code{newLa} definition +is executed before @code{traLaLa} is defined, leading to a syntax +error. -In the above example, music expressions can be `exported' from the +The above example shows how to @q{export} music expressions from the input to the Scheme interpreter. The opposite is also possible. By wrapping a Scheme value in the function @code{ly:export}, a Scheme -value is interpreted as if it were entered in LilyPond syntax. Instead -of defining @code{\twice}, the example above could also have been -written as +value is interpreted as if it were entered in LilyPond syntax. +Instead of defining @code{\twice}, the example above could also have +been written as @example @dots{} @{ #(ly:export (make-sequential-music (list newLa))) @} @end example Scheme code is evaluated as soon as the parser encounters it. To -define some scheme code in a macro (to be called later), use -@ref{Void functions} or +define some Scheme code in a macro (to be called later), use +@ref{Void functions}, or @example #(define (nopc) @@ -329,9 +389,9 @@ define some scheme code in a macro (to be called later), use @end example -@refbugs +@knownissues -Mixing Scheme and LilyPond identifiers is not possible with the +Mixing Scheme and LilyPond variables is not possible with the @code{--safe} option. @@ -344,20 +404,20 @@ it takes up time. Time is a rational number that measures the length of a piece of music in whole notes. A music object has three kinds of types: -@itemize @bullet +@itemize @item music name: Each music expression has a name. For example, a note leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to a @internalsref{SimultaneousMusic}. A list of all expressions -available is in the Program reference manual, under +available is in the Internals Reference manual, under @internalsref{Music expressions}. @item -`type' or interface: Each music name has several `types' or +@q{type} or interface: Each music name has several @q{types} or interfaces, for example, a note is an @code{event}, but it is also a @code{note-event}, a @code{rhythmic-event}, and a @code{melodic-event}. All classes of music are listed in the -Profram reference, under +Internals Reference, under @internalsref{Music classes}. @item @@ -373,7 +433,7 @@ under @internalsref{Music properties}. A compound music expression is a music object that contains other music objects in its properties. A list of objects can be stored in -the @code{elements} property of a music object, or a single `child' +the @code{elements} property of a music object, or a single @q{child} music object in the @code{element} object. For example, @internalsref{SequentialMusic} has its children in @code{elements}, and @internalsref{GraceMusic} has its single argument in @@ -488,7 +548,7 @@ someNote = c' @end example The @code{display-scheme-music} function is the function used by -@code{\displayMusic} to display the scheme representation of a music +@code{\displayMusic} to display the Scheme representation of a music expression. @example @@ -502,7 +562,7 @@ expression. (ly:make-pitch 0 0 0)) @end example -Then the note pitch is accessed thourgh the @code{'pitch} property +Then the note pitch is accessed through the @code{'pitch} property of the @code{NoteEvent} object, @example @@ -529,7 +589,7 @@ d' @subsection Doubling a note with slurs (example) Suppose we want to create a function which translates -input like ``@code{a}'' into ``@code{a( a)}''. We begin +input like @code{a} into @code{a( a)}. We begin by examining the internal representation of the music we want to end up with. @@ -568,7 +628,7 @@ we want to end up with. @end example The bad news is that the @code{SlurEvent} expressions -must be added ``inside'' the note (or more precisely, +must be added @q{inside} the note (or more precisely, inside the @code{EventChord} expression). Now we examine the input, @@ -594,7 +654,7 @@ have two notes to build the sequence), add @code{SlurEvents} to the @code{SequentialMusic} with the two @code{EventChords}. @example -doubleSlur = #(def-music-function (parser location note) (ly:music?) +doubleSlur = #(define-music-function (parser location note) (ly:music?) "Return: @{ note ( note ) @}. `note' is supposed to be an EventChord." (let ((note2 (ly:music-deep-copy note))) @@ -706,27 +766,27 @@ necessary, but just like clear variable names, it is good practice. (let ((result-event-chord (ly:music-deep-copy event-chord))) @end example -`@code{let}' is used to declare local variables. Here we use one local -variable, named `@code{result-event-chord}', to which we give the value -@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is +@code{let} is used to declare local variables. Here we use one local +variable, named @code{result-event-chord}, to which we give the value +@code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is a function specific to LilyPond, like all functions prefixed by -`@code{ly:}'. It is use to make a copy of a music -expression. Here we copy `@code{event-chord} (the parameter of the +@code{ly:}. It is use to make a copy of a music +expression. Here we copy @code{event-chord} (the parameter of the function). Recall that our purpose is to add a marcato to an @code{EventChord} expression. It is better to not modify the @code{EventChord} which was given as an argument, because it may be used elsewhere. Now we have a @code{result-event-chord}, which is a -@code{oteEventChord} expression and is a copy of @code{event-chord}. We +@code{NoteEventChord} expression and is a copy of @code{event-chord}. We add the marcato to its elements list property. @example (set! place new-value) @end example -Here, what we want to set (the "place") is the "elements" property of -@code{result-event-chord} expression +Here, what we want to set (the @q{place}) is the @q{elements} property of +@code{result-event-chord} expression. @example (ly:music-property result-event-chord 'elements) @@ -736,7 +796,7 @@ Here, what we want to set (the "place") is the "elements" property of (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we see in the @code{\displayMusic} output above). The new value is the former elements property, with an extra item: the -@code{MarcatoEvent} expression, which we copy from the +@code{ArticulationEvent} expression, which we copy from the @code{\displayMusic} output, @example @@ -745,12 +805,12 @@ former elements property, with an extra item: the (ly:music-property result-event-chord 'elements)) @end example -`@code{cons}' is used to add an element to a list without modifying the +@code{cons} is used to add an element to a list without modifying the original list. This is what we want: the same list as before, plus the new @code{ArticulationEvent} expression. The order inside the elements property is not important here. -Finally, once we have added the @code{MarcatoEvent} to its elements +Finally, once we have added the marcato articulation to its @code{elements} property, we can return @code{result-event-chord}, hence the last line of the function. @@ -787,6 +847,7 @@ Stencil object given a number of arguments. * Markup construction in Scheme:: * How markups work internally:: * New markup command definition:: +* New markup list command definition:: @end menu @@ -827,14 +888,14 @@ LilyPond markup syntax and Scheme markup syntax. @end multitable @end quotation -The whole scheme language is accessible inside the +The whole Scheme language is accessible inside the @code{markup} macro. For example, You may use function calls inside @code{markup} in order to manipulate character strings. This is useful when defining new markup commands (see @ref{New markup command definition}). -@refbugs +@knownissues The markup-list argument of commands such as @code{#:line}, @code{#:center}, and @code{#:column} cannot be a variable or @@ -893,7 +954,7 @@ of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}. @subsection New markup command definition New markup commands can be defined -with the @code{define-markup-command} scheme macro. +with the @code{define-markup-command} Scheme macro. @lisp (define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...) @@ -909,7 +970,7 @@ The arguments are @item argi-type? a type predicate for the i@var{th} argument @item layout -the `layout' definition +the @q{layout} definition @item props a list of alists, containing all active properties. @end table @@ -1051,9 +1112,59 @@ to the @code{interpret-markup} function, with the @code{layout} and Note: there is now an internal command @code{\smallCaps} which can be used to set text in small caps. See -@ref{Overview of text markup commands} for details. +@ref{Text markup commands}, for details. +@node New markup list command definition +@subsection New markup list command definition +Markup list commands are defined with the +@code{define-markup-list-command} Scheme macro, which is similar to the +@code{define-markup-command} macro described in +@ref{New markup command definition}, except that where the later returns +a single stencil, the former returns a list 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?) + (let ((indent (chain-assoc-get 'par-indent props 2))) + (interpret-markup-list layout props + (make-justified-lines-markup-list (cons (make-hspace-markup indent) + args))))) +@end example + +Besides the usual @code{layout} and @code{props} arguments, the +@code{paragraph} markup list command takes a markup list argument, named +@code{args}. The predicate for markup lists is @code{markup-list?}. + +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. An horizontal space is added at the +beginning using 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: +@example +\markuplines @{ + \paragraph @{ + The art of music typography is called \italic @{(plate) engraving.@} + The term derives from the traditional process of music printing. + Just a few decades ago, sheet music was made by cutting and stamping + the music into a zinc or pewter plate in mirror image. + @} + \override-lines #'(par-indent . 4) \paragraph @{ + The plate would be inked, the depressions caused by the cutting + and stamping would hold ink. An image was formed by pressing paper + to the plate. The stamping and cutting was completely done by + hand. + @} +@} +@end example @node Contexts for programmers @section Contexts for programmers @@ -1108,7 +1219,7 @@ where @var{proc} is a Scheme function, taking three arguments. When interpreted, the function @var{proc} is called for every layout object found in the context @var{context}, with the following arguments: -@itemize @bullet +@itemize @item the layout object itself, @item the context where the layout object was created, and @item the context where @code{\applyOutput} is processed. @@ -1133,264 +1244,72 @@ note-heads on the center-line: @end example -@node OLD STUFF -@section OLD STUFF - -This stuff is slated for deletion or merger into the earlier sections. - -@menu -* Extending music syntax:: -* Manipulating music expressions:: -* Using LilyPond syntax inside Scheme:: -@end menu - - -@node Extending music syntax -@subsection Extending music syntax - -@c TODO: rewrite example. -@c The use of FUNC as example argument is rather confusing. - -The syntax of composite music expressions, like @code{\repeat}, -@code{\transpose}, and @code{\context} follows the general form of - -@example -\@code{keyword} @var{non-music-arguments} @var{music-arguments} -@end example - -Such syntax can also be defined as user code. To do this it is -necessary to create a @emph{music function}. This is a specially marked -Scheme function. For example, the music function @code{\applyMusic} applies -a user-defined function to a music expression. Its syntax is - -@example -\applyMusic #@var{func} @var{music} -@end example - -A music function is created with @code{ly:make-music-function}, - -@example -(ly:make-music-function -@end example - -@code{\applyMusic} takes a Scheme function and a Music expression as -arguments. This is encoded in its parameter list, - -@example -(list procedure? ly:music?) -@end example - -The function itself takes another argument: an Input location -object. That object is used to provide error messages with file names -and line numbers. The definition is the second argument of -@code{ly:make-music-function}. The body simply calls the function - -@example -(lambda (where func music) - (func music)) -@end example - -The above Scheme code only defines the functionality. The tag -@code{\applyMusic} is selected by defining - -@example -applyMusic = #(ly:make-music-function - (list procedure? ly:music?) - (lambda (parser location func music) - (func music))) -@end example +@node Scheme procedures as properties +@section Scheme procedures as properties -A @code{define-music-function} macro is introduced on top of -@code{ly:make-music-function} to ease the definition of music -functions: +Properties (like thickness, direction, etc.) can be set at fixed values +with \override, e.g. @example -applyMusic = #(define-music-function (parser location func music) - (procedure? ly:music?) - (func music)) +\override Stem #'thickness = #2.0 @end example -Examples of the use of @code{\applyMusic} are in the next section. - -@seealso -@file{ly/@/music@/-functions@/-init@/.ly}. - +Properties can also be set to a Scheme procedure, -@node Manipulating music expressions -@subsection Manipulating music expressions - -Music objects and their properties can be accessed and manipulated -directly through the @code{\applyMusic} mechanism. -The syntax for @code{\applyMusic} is - -@example -\applyMusic #@var{func} @var{music} -@end example - -@noindent -This means that the Scheme function @var{func} is called with -@var{music} as its argument. The return value of @var{func} is the -result of the entire expression. @var{func} may read and write music -properties using the functions @code{ly:music-property} and -@code{ly:music-set-property!}. - -An example is a function that reverses the order of elements in -its argument, -@lilypond[quote,verbatim,ragged-right] -#(define (rev-music-1 m) - (ly:music-set-property! m 'elements - (reverse (ly:music-property m 'elements))) - m) - -\applyMusic #rev-music-1 { c'4 d'4 } +@lilypond[fragment,verbatim,quote,relative=2] +\override Stem #'thickness = #(lambda (grob) + (if (= UP (ly:grob-property grob 'direction)) + 2.0 + 7.0)) +c b a g b a g b @end lilypond -The use of such a function is very limited. The effect of this -function is void when applied to an argument that does not have -multiple children. The following function application has no effect - -@example -\applyMusic #rev-music-1 \grace @{ c4 d4 @} -@end example - @noindent -In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which -has no @code{elements}, only a single @code{element}. Every generally -applicable function for @code{\applyMusic} must -- like music expressions -themselves -- be recursive. - -The following example is such a recursive function: It first extracts -the @code{elements} of an expression, reverses them and puts them -back. Then it recurses, both on @code{elements} and @code{element} -children. - -@example -#(define (reverse-music music) - (let* ((elements (ly:music-property music 'elements)) - (child (ly:music-property music 'element)) - (reversed (reverse elements))) - - ; set children - (ly:music-set-property! music 'elements reversed) - - ; recurse - (if (ly:music? child) (reverse-music child)) - (map reverse-music reversed) +In this case, the procedure is executed as soon as the value of the +property is requested during the formatting process. + +Most of the typesetting engine is driven by such callbacks. +Properties that typically use callbacks include + +@table @code +@item stencil + The printing routine, that constructs a drawing for the symbol +@item X-offset + The routine that sets the horizontal position +@item X-extent + The routine that computes the width of an object +@end table - music)) -@end example +The procedure always takes a single argument, being the grob. -A slightly more elaborate example is in -@inputfileref{input/@/test,reverse@/-music@/.ly}. +If routines with multiple arguments must be called, the current grob +can be inserted with a grob closure. Here is a setting from +@code{AccidentalSuggestion}, -Some of the input syntax is also implemented as recursive music -functions. For example, the syntax for polyphony @example -<> +(X-offset . + ,(ly:make-simple-closure + `(,+ + ,(ly:make-simple-closure + (list ly:self-alignment-interface::centered-on-x-parent)) + ,(ly:make-simple-closure + (list ly:self-alignment-interface::x-aligned-on-self))))) @end example @noindent -is actually implemented as a recursive function that replaces the -above by the internal equivalent of -@example -<< \context Voice = "1" @{ \voiceOne a @} - \context Voice = "2" @{ \voiceTwo b @} >> -@end example - -Other applications of @code{\applyMusic} are writing out repeats -automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}), -saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and -exporting LilyPond input to other formats -@c no @inputfileref{} here -(eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}). - -@seealso - -@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm}, -@inputfileref{input/@/test,add@/-staccato@/.ly}, -@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and -@inputfileref{input/@/test,music@/-box@/.ly}. - - -@node Using LilyPond syntax inside Scheme -@subsection Using LilyPond syntax inside Scheme - -Creating music expressions in Scheme can be tedious, as they are -heavily nested and the resulting Scheme code is large. For some -simple tasks this can be avoided by using common LilyPond syntax inside -Scheme, with the dedicated @code{#@{ ... #@}} syntax. - -The following two expressions give equivalent music expressions: -@example -mynotes = @{ \override Stem #'thickness = #4 - @{ c'8 d' @} @} - -#(define mynotes #@{ \override Stem #'thickness = #4 - @{ c'8 d' @} #@}) -@end example - -The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{ -... @}} block, which is parsed. The resulting music expression, a -@code{SequentialMusic} music object, is then returned and usable in Scheme. - -Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}} -expressions with the @code{$} character (@code{$$} can be used to -produce a single @code{$} character). This makes the creation of simple -functions straightforward. In the following example, a function -setting the TextScript's padding is defined: - -@lilypond[quote,verbatim,ragged-right] -#(use-modules (ice-9 optargs)) -#(define* (textpad padding #:optional once?) - (ly:export ; this is necessary for using the expression - ; directly inside a block - (if once? - #{ \once \override TextScript #'padding = #$padding #} - #{ \override TextScript #'padding = #$padding #}))) - - { - c'^"1" - #(textpad 3.0 #t) % only once - c'^"2" - c'^"3" - #(textpad 5.0) - c'^"4" - c'^"5" - } -@end lilypond - -Here, the variable @code{padding} is a number; music expression -variables may also be used in a similar fashion, as in the following -example: - -@lilypond[quote,verbatim,ragged-right] -#(define (with-padding padding) - (lambda (music) - #{ \override TextScript #'padding = #$padding - $music - \revert TextScript #'padding #})) +In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and +@code{ly:self-alignment-interface::centered-on-x-parent} are called +with the grob as argument. The results are added with the @code{+} +function. To ensure that this addition is properly executed, the whole +thing is enclosed in @code{ly:make-simple-closure}. -{ - c'^"1" - \applyMusic #(with-padding 3) { c'^"2" c'^"3" } - c'^"4" -} -@end lilypond - -The function created by @code{(with-padding 3)} adds @code{\override} and -@code{\revert} statements around the music given as an argument, and returns -this new expression. Thus, this example is equivalent to: +In fact, using a single procedure as property value is equivalent to @example -@{ - c'^"1" - @{ \override TextScript #'padding = #3 - @{ c'^"2" c'^"3"@} - \revert TextScript #'padding - @} - c'^"4" -@} +(ly:make-simple-closure (ly:make-simple-closure (list @var{proc}))) @end example - - +@noindent +The inner @code{ly:make-simple-closure} supplies the grob as argument +to @var{proc}, the outer ensures that result of the function is +returned, rather than the @code{simple-closure} object.