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
@item @code{@var{typeN?}}
@tab a Scheme @emph{type predicate} for which @code{@var{argN}}
-must return @code{#t}. Some of these predicates are specially
-recognized by the parser, see below. There is also a special form
+must return @code{#t}. There is also a special form
@code{(@emph{predicate?} @emph{default})} for specifying optional
arguments. If the actual argument is missing when the function is being
called, the default value is substituted instead. Default values are
@end multitable
@noindent
-Some type predicates are specially handled by the parser since it
-can't recognize the arguments reliably otherwise. Currently these are
-@code{ly:pitch?} and @code{ly:duration?}.
-
-Suitability of arguments for all other predicates is determined by
+Suitability of arguments for the predicates is determined by
actually calling the predicate after LilyPond has already converted them
into a Scheme expression. As a consequence, the argument can be
specified in Scheme syntax if desired (introduced with @code{#} or as
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 ``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 to LilyPond. There are also some other
-ambiguities that LilyPond sorts out by checking with predicate
+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
-event of duration @code{4}? LilyPond decides by asking the predicates.
-That means that you should avoid permissive predicates like
-@code{scheme?} if you have a particular use in mind instead of a general
-purpose function.
+event of duration @code{4}? LilyPond tries the argument
+predicate on successive interpretations until success, with an
+order designed to minimize inconsistent interpretations and
+lookahead.
+
+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 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.
For a list of available predefined type predicates, see
@ruser{Predefined type predicates}.
@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{_}}). Note that returning a post-event
-will be acceptable for music functions called as normal music, leading
-to a result roughly equivalent to
-@example
-s 1*0-\fun
-@end example
-
-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 leading arguments of markup functions that take a markup as
their last argument.
+@funindex \markup
+@cindex markup macro
+@funindex interpret-markup
+Markup commands have a rather complex life cycle. The body of a
+markup command definition is responsible for converting the
+arguments of the markup command into a stencil expression which is
+returned. Quite often this is accomplished by calling the
+@code{interpret-markup} function on a markup expression, passing
+the @var{layout} and @var{props} arguments on to it. Those
+arguments are usually only known at a very late stage in
+typesetting. Markup expressions have their components assembled
+into markup expressions already when @code{\markup} in a LilyPond
+expression or the @code{markup} macro in Scheme is expanded. The
+evaluation and typechecking of markup command arguments happens at
+the time @code{\markup}/@code{markup} are interpreted.
+
+But the actual conversion of markup expressions into stencil
+expressions by executing the markup function bodies only happens
+when @code{interpret-markup} is called on a markup expression.
+
@node On properties
@unnumberedsubsubsec On properties
@node New markup list command definition
@subsection New markup list command definition
+@funindex define-markup-list-command
+@funindex interpret-markup-list
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 latter returns
a single stencil, the former returns a list of stencils.
+In a similar vein, @code{interpret-markup-list} is used instead of
+@code{interpret-markup} for converting a markup list into a list
+of 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.
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
-TODO: the example for this section is ill-chosen since
-@example
-F = -\tweak font-size #-3 -\flageolet
-@end example
-(note the @samp{-} marking it as a post event) will actually work fine
-for the stated purpose. Until this section gets a rewrite, let's
-pretend we don't know.
+@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
+@emph{have} to revert to Scheme has become rather hard.
+
+Until this section gets a rewrite, let's pretend we don't know.
The main disadvantage of @code{\tweak} is its syntactical
-inflexibility. For example, the following produces a syntax error.
+inflexibility. For example, the following produces a syntax error
+(or rather, it did so at some point in the past).
@example
F = \tweak font-size #-3 -\flageolet
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