]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/programming-interface.itely
*** empty log message ***
[lilypond.git] / Documentation / user / programming-interface.itely
index 1f840e55c719cb98cf8ea0024440192bc9105fd6..535714da983c53fde169f9f9b0621f18c6d95282 100644 (file)
@@ -1,3 +1,4 @@
+@c -*-texinfo-*-
 @node Interfaces for programmers
 @appendix Interfaces for programmers
 
@@ -5,17 +6,19 @@
 
 @menu
 * Programmer interfaces for input ::  
-* Markup programmer interface::         
-* Contexts for programmers::   
+* Markup programmer interface::  
+* Contexts for programmers::    
 @end menu
 
 @node Programmer interfaces for input 
 @appendixsec Programmer interfaces for input 
 
 @menu
-* Input variables and Scheme:: 
+* Input variables and Scheme::  
 * Internal music representation::  
-* Manipulating music expressions::  
+* Extending music syntax::      
+* Manipulating music expressions:: 
+* Using LilyPond syntax inside Scheme::   
 @end menu
 
 @node Input variables and Scheme
@@ -83,6 +86,9 @@ 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
@@ -103,8 +109,10 @@ 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}.
+  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}.
@@ -133,14 +141,85 @@ and @internalsref{GraceMusic} has its single argument in
 @code{element}. The body of a repeat is in @code{element} property of
 @internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
 
+
+
+
+@node Extending music syntax
+@appendixsubsec Extending music syntax
+
+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
+argument. This is encoded in its first argument,
+
+@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 is function 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 (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
 
 Music objects and their properties can be accessed and manipulated
-directly, through the @code{\apply} mechanism.
-The syntax for @code{\apply} is
+directly, through the @code{\applymusic} mechanism.
+The syntax for @code{\applymusic} is
 @example
-\apply #@var{func} @var{music}
+\applymusic #@var{func} @var{music}
 @end example
 
 @noindent
@@ -157,7 +236,7 @@ its argument:
      (ly:music-set-property! m 'elements (reverse
        (ly:music-property m 'elements)))
      m)
-  \score { \notes \apply #rev-music-1 { c4 d4 } }
+  \score { \notes \applymusic #rev-music-1 { c4 d4 } }
 @end lilypond
 
 The use of such a function is very limited. The effect of this
@@ -165,13 +244,13 @@ function is void when applied to an argument which is does not have
 multiple children.  The following function application has no effect:
 
 @example
-  \apply #rev-music-1 \grace @{ c4 d4 @}
+  \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{\apply} must -- like music expressions
+applicable function for @code{\applymusic} must -- like music expressions
 themselves -- be recursive.
 
 The following example is such a recursive function: It first extracts
@@ -211,7 +290,7 @@ above by the internal equivalent of
     \context Voice = "2" @{ \voiceTwo b @} >>
 @end example
 
-Other applications of @code{\apply} are writing out repeats
+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
@@ -225,6 +304,112 @@ LilyPond input to other formats  (@inputfileref{input/test,to-xml.ly})
 @inputfileref{input/test,music-box.ly}.
 
 
+@node Using LilyPond syntax inside Scheme
+@appendixsubsec 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
@@ -232,7 +417,7 @@ LilyPond input to other formats  (@inputfileref{input/test,to-xml.ly})
 
 @menu
 * Markup construction in scheme::  
-* Markup command definition::  
+* Markup command definition::   
 @end menu
 
 @node Markup construction in scheme
@@ -455,13 +640,16 @@ to the @code{interpret-markup} function, with the @code{paper} and
 
 
 @menu
-* Context evaluation::         
+* Context evaluation::          
 * Running a function on all layout objects::  
 @end menu
 
 @node Context evaluation
 @appendixsubsec Context evaluation
 
+@cindex calling code during interpreting
+@cindex @code{\applycontext}
+
 Contexts can be modified during interpretation with Scheme code. The
 syntax for this is
 @example
@@ -484,6 +672,11 @@ 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
 
+
+@cindex calling code on layout objects
+@cindex @code{\applyoutput}
+
+
 The most versatile way of tuning an object is @code{\applyoutput}. Its
 syntax is
 @example