Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@c \version "2.19.2"
@node Interfaces for programmers
@chapter Interfaces for programmers
* Markup functions::
* Contexts for programmers::
* Callback functions::
-* Inline Scheme code::
* Difficult tweaks::
@end menu
lists, score, book, bookpart, context definition and output definition
blocks.
-For some kinds of expression (like most music not enclosed in braces)
-LilyPond needs to look further than the expression itself in order to
-determine its end. If such an expression were considered for an
-optional argument by evaluating its predicate, LilyPond would not be
-able to @q{backup} when it decides the expression does not fit the
-parameter. So some forms of music might need to be enclosed in braces
-to make them acceptable in some circumstances. Some other
+Some
ambiguities LilyPond sorts out by checking with predicate
functions: is @samp{-3} a fingering postevent or a negative number? Is
@code{"a" 4} in lyric mode a string followed by a number, or a lyric
For example, a predicate accepting both music expressions and
pitches will consider @code{c''} to be a pitch rather than a music
-expression. Immediately following durations or postevents might
-not work with that interpretation. So it's best to avoid overly
+expression. Immediately following durations or postevents will
+change that interpretation. It's best to avoid overly
permissive predicates like @code{scheme?} when the application
rather calls for more specific argument types.
@node Music function usage
@subsection Music function usage
-Music functions may currently be used in several 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.
+A @q{music function} has to return an expression matching the predicate
+@code{ly:music?}. This makes music function calls suitable as arguments
+of type @code{ly:music?} for another music function call.
+
+When using a music function call in other contexts, the context may
+cause further semantic restrictions.
@itemize
@item
-At top level in a music expression. No restriction apply here.
+At the top level in a music expression a post-event is not accepted.
@item
-As a post-event, explicitly started with a direction indicator (one of
-@code{-}, @code{^}, @w{and @code{_}}).
-
-In this case, you can't use an @emph{open} music expression as the last
-argument, one that would end with a music expression able to accept
-additional postevents.
+When a music function (as opposed to an event function) returns an
+expression of type post-event, LilyPond requires one of the named
+direction indicators (@code{-}, @code{^}, @w{and @code{_}})) in order to
+properly integrate the post-event produced by the music function call
+into the surrounding expression.
@item
-As a chord constituent. The returned expression must be of
+As a chord constituent. The returned expression must be of a
@code{rhythmic-event} type, most likely a @code{NoteEvent}.
@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.
+@q{Polymorphic} functions, like @code{\tweak}, can be applied to
+post-events, chord constituent and top level music expressions.
@node Simple substitution functions
@subsection Simple substitution functions
The procedure always takes a single argument, being the grob.
+That procedure may access the usual value of the property, by first
+calling the function that is the usual callback for that property, which
+can by found in the Internals Reference or the file 'define-grobs.scm':
+
+@example
+\relative c'' @{
+ \override Flag #'X-offset = #(lambda (flag)
+ (let ((default (ly:flag::calc-x-offset flag)))
+ (* default 4.0)))
+ c4. d8 a4. g8
+@}
+@end example
+
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},
(grob-interpret-markup grob (markup "foo")))
@end example
-@node Inline Scheme code
-@section Inline Scheme code
+@ignore
+
+@n ode Inline Scheme code
+@s ection Inline Scheme code
TODO: after this section had been written, LilyPond has improved
to the point that finding a @emph{simple} example where one would
written back with @code{set!}. The last element of the
@code{let} block is the return value, @code{m} itself.
+@end ignore
@node Difficult tweaks
\override Tie.after-line-breaking =
#my-callback
c1 ~ \break
- c2 ~ c
+ c2 ~ 2
}
@end lilypond
projects / lilypond.git / blobdiff