X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=83db8292dd370c4d49fd3d91b1b3b2ef56e2f5de;hb=93b9f6c30cbeec39615b485f6c2f2a4dd50f5993;hp=7b08550748a60fbb4a6209a8ebd6a065923ee6d0;hpb=8ba703bba8ce73a55673ba3657647481f4846c39;p=lilypond.git diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index 7b08550748..83db8292dd 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -1,6 +1,6 @@ @c -*-texinfo-*- @node Interfaces for programmers -@appendix Interfaces for programmers +@chapter Interfaces for programmers @@ -11,17 +11,18 @@ @end menu @node Programmer interfaces for input -@appendixsec Programmer interfaces for input +@section Programmer interfaces for input @menu * Input variables and Scheme:: * Internal music representation:: * Extending music syntax:: -* Manipulating music expressions:: +* Manipulating music expressions:: +* Using LilyPond syntax inside Scheme:: @end menu @node Input variables and Scheme -@appendixsubsec Input variables and Scheme +@subsection Input variables and Scheme The input format supports the notion of variable: in the following @@ -85,9 +86,12 @@ written as \score @{ #(ly:export (make-sequential-music newLa)) @} @end example +@refbugs + +Mixing Scheme and lily identifiers is not possible with @code{--safe}. @node Internal music representation -@appendixsubsec Internal music representation +@subsection Internal music representation When a music expression is parsed, it is converted into a set of Scheme music objects. The defining property of a music object is that @@ -100,21 +104,22 @@ A music object has three kinds of types: 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 internals manual, under @internalsref{Music -expressions}. +available is in the internals manual, under +@hyphenatedinternalsref{Music expressions,Music-expressions}. @item - `type' or interface: Each music name has several `types' or interface, - 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}. + `type' or interface: Each music name has several `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 internals manual, under - @internalsref{Music classes}. -@item -C++ object: Each music object is represented by a C++ object. For technical -reasons, different music objects may be represented by different C++ -object types. For example, a note is @code{Event} object, while -@code{\grace} creates a @code{Grace_music} object. + @hyphenatedinternalsref{Music classes,Music-classes}. + + @item +C++ object: Each music object is represented by a C++ object. For +technical reasons, different music objects may be represented by +different C++ object types. For example, a note is @code{Event} +object, while @code{\grace} creates a @code{Grace_music} object. We expect that distinctions between different C++ types will disappear in the future. @@ -139,7 +144,7 @@ and @internalsref{GraceMusic} has its single argument in @node Extending music syntax -@appendixsubsec Extending music syntax +@subsection Extending music syntax The syntax of composite music expressions, like @code{\repeat}, @code{\transpose} and @code{\context} @@ -186,17 +191,28 @@ The above Scheme code only defines the functionality. The tag @code{\applymusic} is selected by defining @example - apply = #(ly:make-music-function - (list procedure? ly:music?) - (lambda (where func music) - (func music))) + applymusic = #(ly:make-music-function + (list procedure? ly:music?) + (lambda (location func music) + (func music))) +@end example + +A @code{def-music-function} macro is introduced on top of +@code{ly:make-music-function} to ease the definition of music +functions: + +@example + applymusic = #(def-music-function (location func music) (procedure? ly:music?) + (func music)) @end example Examples of the use of @code{\applymusic} are in the next section. +@seealso +@file{ly/music-functions-init.ly}. @node Manipulating music expressions -@appendixsubsec Manipulating music expressions +@subsection Manipulating music expressions Music objects and their properties can be accessed and manipulated directly, through the @code{\applymusic} mechanism. @@ -287,9 +303,115 @@ LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) @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, using LilyPond usual syntax inside +scheme, with the dedicated @code{#@{ ... #@}} syntax. + +The following two expressions give equivalent music expressions: +@example + mynotes = @{ \override Stem #'thickness = #4 + \notes @{ c'8 d' @} @} + + #(define mynotes #@{ \override Stem #'thickness = #4 + \notes @{ 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 $ character). This makes the creation of simple +functions straightforward. In the following example, a function +setting the TextScript's padding is defined: + +@lilypond[verbatim,raggedright] + #(use-modules (ice-9 optargs)) + #(define* (textpad padding #:optional once?) + (ly:export ; this is necessary for using the expression + ; directly inside a \notes block + (if once? + #{ \once \override TextScript #'padding = #$padding #} + #{ \override TextScript #'padding = #$padding #}))) + + \score { + \notes { + 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[verbatim,raggedright] + #(define (with-padding padding) + (lambda (music) + #{ \override TextScript #'padding = #$padding + $music + \revert TextScript #'padding #})) + + \score { + \notes { + 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: + +@example + \score @{ + \notes @{ + c'^"1" + @{ \override TextScript #'padding = #3 + @{ c'^"2" c'^"3"@} + \revert TextScript #'padding + @} + c'^"4" + @} + @} +@end example + +This function may also be defined as a music function: + +@lilypond[verbatim,raggedright] + withPadding = #(def-music-function (location padding music) (number? ly:music?) + #{ \override TextScript #'padding = #$padding + $music + \revert TextScript #'padding #}) + + \score { + \notes { + c'^"1" + \withPadding #3 + { c'^"2" c'^"3"} + c'^"4" + } + } +@end lilypond + @node Markup programmer interface -@appendixsec Markup programmer interface +@section Markup programmer interface @menu @@ -298,7 +420,7 @@ LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) @end menu @node Markup construction in scheme -@appendixsubsec Markup construction in scheme +@subsection Markup construction in scheme @cindex defining markup commands @@ -352,7 +474,7 @@ instead: @end lisp @node Markup command definition -@appendixsubsec Markup command definition +@subsection Markup command definition New markup commands can be defined with the @code{def-markup-command} scheme macro. @@ -513,7 +635,7 @@ to the @code{interpret-markup} function, with the @code{paper} and @node Contexts for programmers -@appendixsec Contexts for programmers +@section Contexts for programmers @menu @@ -522,7 +644,10 @@ to the @code{interpret-markup} function, with the @code{paper} and @end menu @node Context evaluation -@appendixsubsec Context evaluation +@subsection Context evaluation + +@cindex calling code during interpreting +@cindex @code{\applycontext} Contexts can be modified during interpretation with Scheme code. The syntax for this is @@ -544,7 +669,12 @@ current bar number on the standard output during the compile: @node Running a function on all layout objects -@appendixsubsec Running a function on all layout objects +@subsection Running a function on all layout objects + + +@cindex calling code on layout objects +@cindex @code{\applyoutput} + The most versatile way of tuning an object is @code{\applyoutput}. Its syntax is