used as the return value of the scheme function. It may contain
LilyPond code blocks enclosed in hashed braces
(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in @ref{Lilypond
-code blocks}. Within LilyPond code blocks, use @code{$} to reference
-function arguments (eg., @samp{$arg1}) or to start an inline Scheme
-expression containing function arguments (eg., @w{@samp{$(cons arg1
-arg2)}}). If your function returns a music expression, it is cloned and
-given the correct @code{origin}.
+code blocks}. Within LilyPond code blocks, use @code{#} to reference
+function arguments (eg., @samp{#arg1}) or to start an inline Scheme
+expression containing function arguments (eg., @w{@samp{#(cons arg1
+arg2)}}). Where normal Scheme expressions using @code{#} don't do the
+trick, you might need to revert to immediate Scheme expressions using
+@code{$}, for example as @samp{$music}.
+
+If your function returns a music expression, it is given a useful value
+of @code{origin}.
@end multitable
@noindent
@code{ly:pitch?} and @code{ly:duration?}.
Suitability of arguments for all other 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
+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
-the result of calling a scheme function), but Lilypond will also
-convert a number of Lilypond constructs into Scheme before actually
-checking the predicate on them. Currently, those include music,
-simple strings (with or without quotes), numbers, full markups and markup
+the result of calling a scheme function), but Lilypond will also convert
+a number of Lilypond constructs into Scheme before actually checking the
+predicate on them. Currently, those include music, postevents, simple
+strings (with or without quotes), numbers, full markups and markup
lists, score, book, bookpart, context definition and output definition
blocks.
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
-complications that may cause a predicate function to be called several
-times on successive versions of an argument (like @code{3} and
-@code{3\cm}) or several interpretations (like @code{"a" 4} in lyric
-mode, which can either be a string followed by a number, or a lyric
-event of duration @code{4}).
-
-Music arguments preceding @code{ly:duration?} arguments must also be
-lookahead-free. This may also hold for the last argument of a scheme
-function that is used as the last part of another expression, since
-otherwise Lilypond won't know whether following postevents or
-durations apply to the argument of the Scheme function, or to the
-containing music expression.
-
-For a list of available type predicates, see
+ambiguities that 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.
+
+For a list of available predefined type predicates, see
@ruser{Predefined type predicates}.
@seealso
Scheme functions can be called pretty much anywhere where a Scheme
expression starting with @code{#} can be written. You call a scheme
function by writing its name preceded by @code{\}, followed by its
-arguments. The last argument can't be an optional argument. If there
-are several optional arguments in a row, they are filled with values
-left to right. Once an optional argument can't match input, it and all
-immediately following optional arguments are replaced with their default
-values, and the matching continues with the next non-optional argument.
+arguments. Once an optional argument predicate does not match an
+argument, Lilypond skips this and all following optional arguments,
+replacing them with their specified default, and @q{backs up} the
+argument that did not match to the place of the next mandatory argument.
+Since the backed up argument needs to go somewhere, optional arguments
+are not actually considered optional unless followed by a mandatory
+argument.
+
+There is one exception: if you write @code{\default} in the place of an
+optional argument, this and all following optional arguments are skipped
+and replaced by their default. This works even when no mandatory
+argument follows since @code{\default} does not need to get backed up.
+The @code{mark} and @code{key} commands make use of that trick to
+provide their default behavior when just followed by @code{\default}.
Apart from places where a Scheme value is required, there are a few
places where @code{#} expressions are currently accepted and evaluated
@funindex \void
Sometimes a procedure is executed in order to perform an action rather
-than return a value. Some programming languages (like C and Scheme)
-use functions for either concept and just discard the returned value
+than return a value. Some programming languages (like C and Scheme) use
+functions for either concept and just discard the returned value
(usually by allowing any expression to act as statement, ignoring the
result). This is clever but error-prone: most C compilers nowadays
offer warnings for various non-``void'' expressions being discarded.
-For many functions executing an action, the Scheme standards declare
-the return value to be unspecified. Lilypond's Scheme interpreter
-Guile has a unique ``unspecified'' value that it usually (such when
-using @code{set!} directly on a variable) but unfortunately not
-consistently returns in such cases.
+For many functions executing an action, the Scheme standards declare the
+return value to be unspecified. Lilypond's Scheme interpreter Guile has
+a unique value @code{*unspecified*} that it usually (such when using
+@code{set!} directly on a variable) but unfortunately not consistently
+returns in such cases.
Defining a Lilypond function with @code{define-void-function} makes
sure that this special value (the only value satisfying the predicate
@node Music function usage
@subsection Music function usage
-Music functions may currently be used in three places. Depending on
+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.
@itemize
@item
-At top level in a music expression. There are no special restrictions
-on the argument list.
+At top level in a music expression. No restriction apply here.
@item
As a post-event, explicitly started with a direction indicator (one of
-@code{-}, @code{^}, @w{and @code{_}}). All trailing arguments of the
-music function with the predicate @code{ly:music?} will get parsed also
-as post-events (if the last argument is a scheme function, this will
-hold for trailing @code{ly:music?} arguments of the scheme function
-instead). Note that returning a post-event will be acceptable for music
-functions called as normal music, leading to a result roughly equivalent
-to
+@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.
+
@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.
+As a chord constituent. The returned expression must be of
+@code{rhythmic-event} type, most likely a @code{NoteEvent}.
@end itemize
@noindent
(parser location beg-end)
(pair?)
#@{
- \once \override Beam #'positions = $beg-end
+ \once \override Beam #'positions = #beg-end
#@})
\relative c' @{
(parser location beg end)
(number? number?)
#{
- \once \override Beam #'positions = $(cons beg end)
+ \once \override Beam #'positions = #(cons beg end)
#})
\relative c' {
(parser location mag)
(number?)
#{
- \override Stem #'length = $(* 7.0 mag)
+ \override Stem #'length = #(* 7.0 mag)
\override NoteHead #'font-size =
- $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+ #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
#})
AltOff = {
(parser location mag music)
(number? ly:music?)
#{
- \override Stem #'length = $(* 7.0 mag)
+ \override Stem #'length = #(* 7.0 mag)
\override NoteHead #'font-size =
- $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
- $music
+ #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+ #music
\revert Stem #'length
\revert NoteHead #'font-size
#})
to write dynamics commands, those are usually attached without direction
indicator, like @code{c'\pp}. Here is a way to write arbitrary
dynamics:
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
dyn=#(define-event-function (parser location arg) (markup?)
(make-dynamic-script arg))
\relative c' { c\dyn pfsss }
"Draw a double box around text."
(interpret-markup layout props
#@{\markup \override #'(box-padding . 0.4) \box
- \override #'(box-padding . 0.6) \box @{ $text @}#@}))
+ \override #'(box-padding . 0.6) \box @{ #text @}#@}))
@end lisp
or, equivalently
(interpret-markup layout props
#@{\markup \override #`(box-padding . ,inter-box-padding) \box
\override #`(box-padding . ,box-padding) \box
- @{ $text @} #@}))
+ @{ #text @} #@}))
@end lisp
Again, the equivalent version using the markup macro would be:
(interpret-markup layout props
#{\markup \override #`(box-padding . ,inter-box-padding) \box
\override #`(box-padding . ,box-padding) \box
- { $text } #}))
+ { #text } #}))
\markup \double-box A
\markup \override #'(inter-box-padding . 0.8) \double-box A
#(define-markup-list-command (paragraph layout props args) (markup-list?)
#:properties ((par-indent 2))
(interpret-markup-list layout props
- #@{\markuplist \justified-lines @{ \hspace #par-indent $args @} #@}))
+ #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
@end example
@node Inline Scheme code
@section Inline Scheme code
+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.
+
The main disadvantage of @code{\tweak} is its syntactical
inflexibility. For example, the following produces a syntax error.
@end example
@noindent
-In other words, @code{\tweak} doesn't behave like an articulation
-regarding the syntax; in particular, it can't be attached with
-@code{^} and @code{_}.
-
Using Scheme, this problem can be avoided. The route to the
result is given in @ref{Adding articulation to notes (example)},
especially how to use @code{\displayMusic} as a helping guide.
projects / lilypond.git / blobdiff