]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/extending/programming-interface.itely
Merge branch 'master' of git://git.savannah.gnu.org/lilypond.git
[lilypond.git] / Documentation / extending / programming-interface.itely
index 7c8b287552fede93f24346adeaf14aca550302f8..71865e7788d009dbe7bfe55f25f539128fb3cf39 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.14.0"
 
 @node Interfaces for programmers
 @chapter Interfaces for programmers
@@ -35,7 +35,8 @@ expressions automatically, and can be used to greatly simplify the
 input file.
 
 @menu
-* Music function syntax::
+* Music function definitions::
+* Music function usage::
 * Simple substitution functions::
 * Intermediate substitution functions::
 * Mathematics in functions::
@@ -44,10 +45,10 @@ input file.
 @end menu
 
 
-@node Music function syntax
-@subsection Music function syntax
+@node Music function definitions
+@subsection Music function definitions
 
-The general form for music functions is:
+The general form for defining music functions is:
 
 @example
 function =
@@ -66,7 +67,8 @@ where
 
 @item @code{@var{typeN?}}
 @tab a scheme @emph{type predicate} for which @code{@var{argN}}
-must return @code{#t}.
+must return @code{#t}.  Some of these predicates are specially
+recognized by the parser, see below.
 
 @item @code{@var{music}}
 @tab A music expression, optionally written in scheme, with any
@@ -79,10 +81,20 @@ function arguments (eg., @w{@samp{$(cons arg1 arg2)}}).
 @end multitable
 
 @noindent
-For a list of available type predicates, see
-@ruser{Predefined type predicates}.  User-defined type predicates
-are also allowed.
+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 those 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.
 
+For a list of available type predicates, see
+@ruser{Predefined type predicates}.
 
 @seealso
 
@@ -95,6 +107,48 @@ 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.  Using the @code{#@{}@dots{}@code{#@}} construct
+produces a sequential music expression and consequently can only applied
+in this context.
+
+@item
+As a post-event.  All trailing arguments of the music function with the
+predicate @code{ly:music?} will get parsed also as post-events.  Note
+that returning post-events will also be acceptable for music functions
+called at top level, 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.
+
+There is another somewhat special rule: if you have a predicate
+@code{ly:music?} directly before a @code{ly:duration?} predicate, then
+the corresponding music expression must be either a music identifier, or
+literal sequential or parallel music enclosed in
+@code{@{}@dots{}@code{@}} or @code{<<}@dots{}@code{>>} explicitly.
+Otherwise, Lilypond could get confused about where the music ends and
+the duration starts.
+
 @node Simple substitution functions
 @subsection Simple substitution functions
 
@@ -111,7 +165,7 @@ Intermediate substitution functions involve a mix of Scheme code
 and LilyPond code in the music expression to be returned.
 
 Some @code{\override} commands require an argument consisting of
-a pair of numbers (called a @code{cons cell} in Scheme).
+a pair of numbers (called a @emph{cons cell} in Scheme).
 
 The pair can be directly passed into the music function,
 using a @code{pair?} variable:
@@ -370,7 +424,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
@@ -401,76 +455,45 @@ New markup commands can be defined using the
 
 The arguments are
 
-@table @var
-@item command-name
+@table @code
+@item @var{command-name}
 the markup command name
 @item layout
 the @q{layout} definition.
 @item props
 a list of associative lists, containing all active properties.
-@item argi
+@item @var{argi}
 @var{i}th command argument
-@item argi-type?
+@item @var{argi-type?}
 a type predicate for the i@var{th} argument
 @end table
 
-If the command uses properties from the @var{props} arguments, the
-@code{#:properties} keyword can be used, to specify which properties are
-used, and their default values.
+If the command uses properties from the @code{props} arguments,
+the @code{#:properties} keyword can be used to specify which
+properties are used along with their default values.
 
-@knownissues
-There are restrictions on the possible arguments to a markup command.
-
-Arguments are distingued according to their type:
+Arguments are distinguished according to their type:
 @itemize
 @item a markup, corresponding to type predicate @code{markup?};
-@item a list of markup, corresponding to type predicate
+@item a list of markups, corresponding to type predicate
 @code{markup-list?};
 @item any other scheme object, corresponding to type predicates such as
 @code{list?}, @code{number?}, @code{boolean?}, etc.
 @end itemize
 
-The available combinations of arguments (after the standard @var{layout}
-and @var{props} arguments) to a markup command defined with
-@code{define-markup-command} are limited as follows.
-
-@table @asis
-@item (no argument)
-@itemx @var{markup-list}
-@itemx @var{markup}
-@itemx @var{markup markup}
-@itemx @var{scheme}
-@itemx @var{scheme markup}
-@itemx @var{scheme scheme}
-@itemx @var{scheme scheme markup}
-@itemx @var{scheme scheme markup markup}
-@itemx @var{scheme markup markup}
-@itemx @var{scheme scheme scheme}
-@end table
+There is no limitation on the order of arguments (after the
+standard @code{layout} and @code{props} arguments).  However,
+markup functions taking a markup as their last argument are
+somewhat special as you can apply them to a markup list, and the
+result is a markup list where the markup function (with the
+specified leading arguments) has been applied to every element of
+the original markup list.
 
-@noindent
-This means that it is not possible to define with e.g. three scheme
-arguments and a markup arguments, like:
-
-@example
-#(define-markup-command (foo layout props
-                         num1    num2    a-list a-markup)
-                        (number? number? list?  markup?)
-  ...)
-@end example
-
-@noindent
-If you apply it as, say,
-
-@example
-\markup \foo #1 #2 #'(bar baz) Blah
-@end example
-
-@cindex Scheme signature
-@cindex signature, Scheme
-@noindent
-@command{lilypond} complains that it cannot parse @code{foo} due to its
-unknown Scheme signature.
+Since replicating the leading arguments for applying a markup
+function to a markup list is cheap mostly for Scheme arguments,
+you avoid performance pitfalls by just using Scheme arguments for
+the leading arguments of markup functions that take a markup as
+their last argument.
 
 @node On properties
 @unnumberedsubsubsec On properties
@@ -563,8 +586,8 @@ It would be nice to make the @code{double-box} command customizable:
 here, the @code{box-padding} values are hard coded, and cannot be
 changed by the user.  Also, it would be better to distinguish the
 padding between the two boxes, from the padding between the inner box
-and the text. So we will introduce a new property,
-@code{inter-box-padding}, for the padding between the two boxes. The
+and the text.  So we will introduce a new property,
+@code{inter-box-padding}, for the padding between the two boxes.  The
 @code{box-padding} will be used for the inner padding.  The new code is
 now as follows:
 
@@ -610,7 +633,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
@@ -759,10 +782,10 @@ syntax for this is
 \applyContext @var{function}
 @end example
 
-@var{function} should be a Scheme function that takes a single
-argument: the context in which the @code{\applyContext} command is
-being called.  The following code will print the current bar
-number on the standard output during the compile:
+@code{@var{function}} should be a Scheme function that takes a
+single argument: the context in which the @code{\applyContext}
+command is being called.  The following code will print the
+current bar number on the standard output during the compile:
 
 @example
 \applyContext
@@ -781,18 +804,19 @@ number on the standard output during the compile:
 @funindex \applyOutput
 
 
-The most versatile way of tuning an object is @code{\applyOutput}.  Its
-syntax is
+The most versatile way of tuning an object is @code{\applyOutput} which
+works by inserting an event into the specified context
+(@rinternals{ApplyOutputEvent}).  Its syntax is
 @example
 \applyOutput @var{context} @var{proc}
 @end example
 
 @noindent
-where @var{proc} is a Scheme function, taking three arguments.
+where @code{@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:
+When interpreted, the function @code{@var{proc}} is called for
+every layout object found in the context @code{@var{context}} at
+the current time step, with the following arguments:
 @itemize
 @item the layout object itself,
 @item the context where the layout object was created, and
@@ -803,20 +827,20 @@ arguments:
 In addition, the cause of the layout object, i.e., the music
 expression or object that was responsible for creating it, is in the
 object property @code{cause}.  For example, for a note head, this is a
-@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
-this is a @rinternals{NoteHead} object.
+@rinternals{NoteHead} event, and for a stem object,
+this is a @rinternals{Stem} object.
 
 Here is a function to use for @code{\applyOutput}; it blanks
-note-heads on the center-line:
+note-heads on the center-line and next to it:
 
 @lilypond[quote,verbatim,ragged-right]
 #(define (blanker grob grob-origin context)
    (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
-            (eq? (ly:grob-property grob 'staff-position) 0))
+            (< (abs (ly:grob-property grob 'staff-position)) 2))
        (set! (ly:grob-property grob 'transparent) #t)))
 
 \relative c' {
-  e4 g8 \applyOutput #'Voice #blanker b d2
+  a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
 }
 @end lilypond
 
@@ -991,33 +1015,36 @@ of the broken tie is repositioned.
 
 @lilypond[quote,verbatim,ragged-right]
 #(define (my-callback grob)
-  (let* (
-         ; have we been split?
-         (orig (ly:grob-original grob))
+   (let* (
+          ;; have we been split?
+          (orig (ly:grob-original grob))
 
-         ; if yes, get the split pieces (our siblings)
-         (siblings (if (ly:grob? orig)
-                     (ly:spanner-broken-into orig) '() )))
+          ;; if yes, get the split pieces (our siblings)
+          (siblings (if (ly:grob? orig)
+                        (ly:spanner-broken-into orig)
+                        '())))
 
-   (if (and (>= (length siblings) 2)
-             (eq? (car (last-pair siblings)) grob))
-     (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+     (if (and (>= (length siblings) 2)
+              (eq? (car (last-pair siblings)) grob))
+         (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
 
 \relative c'' {
   \override Tie #'after-line-breaking =
   #my-callback
-  c1 ~ \break c2 ~ c
+  c1 ~ \break
+  c2 ~ c
 }
 @end lilypond
 
 @noindent
 When applying this trick, the new @code{after-line-breaking} callback
-should also call the old one @code{after-line-breaking}, if there is
-one.  For example, if using this with @code{Hairpin},
-@code{ly:hairpin::after-line-breaking} should also be called.
+should also call the old one, if such a default exists.  For example,
+if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
+should also be called.
 
 
-@item Some objects cannot be changed with @code{\override} for
+@item
+Some objects cannot be changed with @code{\override} for
 technical reasons.  Examples of those are @code{NonMusicalPaperColumn}
 and @code{PaperColumn}.  They can be changed with the
 @code{\overrideProperty} function, which works similar to @code{\once