Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.18"
+@c \version "2.17.6"
@node Interfaces for programmers
@chapter Interfaces for programmers
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 cloned and given the
-correct @code{origin}.
+If your function returns a music expression, it is given a useful value
+of @code{origin}.
@end multitable
@noindent
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 a lenient predicate like @code{scheme?} might be good
-for surprising interpretations.
+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}.
@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 NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
#})
AltOff = {
- \revert Stem #'length
- \revert NoteHead #'font-size
+ \revert Stem.length
+ \revert NoteHead.font-size
}
\relative c' {
(parser location mag music)
(number? ly:music?)
#{
- \override Stem #'length = #(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
- $music
- \revert Stem #'length
- \revert NoteHead #'font-size
+ #music
+ \revert Stem.length
+ \revert NoteHead.font-size
#})
\relative c' {
(parser location)
()
(if (eq? #t (ly:get-option 'display-bar-numbers))
- #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
#@{#@}))
@end example
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
set at fixed values with @code{\override}, e.g.
@example
-\override Stem #'thickness = #2.0
+\override Stem.thickness = #2.0
@end example
Properties can also be set to a Scheme procedure,
@lilypond[fragment,verbatim,quote,relative=2]
-\override Stem #'thickness = #(lambda (grob)
+\override Stem.thickness = #(lambda (grob)
(if (= UP (ly:grob-property grob 'direction))
2.0
7.0))
@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.
@example
-F = \tweak #'font-size #-3 -\flageolet
+F = \tweak font-size #-3 -\flageolet
\relative c'' @{
c4^\F c4_\F
@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.
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
- \override Tie #'after-line-breaking =
+ \override Tie.after-line-breaking =
#my-callback
c1 ~ \break
c2 ~ c
@example
\overrideProperty
-#"Score.NonMusicalPaperColumn" % Grob name
+Score.NonMusicalPaperColumn % Grob name
#'line-break-system-details % Property name
#'((next-padding . 20)) % Value
@end example
projects / lilypond.git / blobdiff