-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Interfaces for programmers
@chapter Interfaces for programmers
* Internal music representation::
* Extending music syntax::
* Manipulating music expressions::
+* Displaying music expressions::
* Using LilyPond syntax inside Scheme::
@end menu
written as
@example
@dots{}
-@{ #(ly:export (make-sequential-music newLa)) @}
+@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
@refbugs
@node Extending music syntax
@subsection Extending music syntax
-The syntax of composite music expressions, like
-@code{\repeat}, @code{\transpose}, and @code{\context}
-follows the general form of
+@c TODO: rewrite example.
+@c The use of FUNC as example argument is rather confusing.
+
+The syntax of composite music expressions, like @code{\repeat},
+@code{\transpose}, and @code{\context} follows the general form of
@example
\@code{keyword} @var{non-music-arguments} @var{music-arguments}
Such syntax can also be defined as user code. To do this, it is
necessary to create a @emph{music function}. This is a specially marked
-Scheme function. For example, the music function @code{\applymusic} applies
+Scheme function. For example, the music function @code{\applyMusic} applies
a user-defined function to a music expression. Its syntax is
@example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
@end example
A music function is created with @code{ly:make-music-function},
(ly:make-music-function
@end example
-@code{\applymusic} takes a Scheme function and a Music expression as
+@code{\applyMusic} takes a Scheme function and a Music expression as
arguments. This is encoded in its parameter list,
@example
@end example
The above Scheme code only defines the functionality. The tag
-@code{\applymusic} is selected by defining
+@code{\applyMusic} is selected by defining
@example
-applymusic = #(ly:make-music-function
+applyMusic = #(ly:make-music-function
(list procedure? ly:music?)
- (lambda (location func music)
+ (lambda (parser location func music)
(func music)))
@end example
functions:
@example
-applymusic = #(def-music-function (location func music)
+applyMusic = #(def-music-function (parser location func music)
(procedure? ly:music?)
(func music))
@end example
-Examples of the use of @code{\applymusic} are in the next section.
+Examples of the use of @code{\applyMusic} are in the next section.
@seealso
@file{ly/@/music@/-functions@/-init@/.ly}.
@subsection Manipulating music expressions
Music objects and their properties can be accessed and manipulated
-directly, through the @code{\applymusic} mechanism.
-The syntax for @code{\applymusic} is
+directly, through the @code{\applyMusic} mechanism.
+The syntax for @code{\applyMusic} is
@example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
@end example
@noindent
(reverse (ly:music-property m 'elements)))
m)
-\applymusic #rev-music-1 { c'4 d'4 }
+\applyMusic #rev-music-1 { c'4 d'4 }
@end lilypond
The use of such a function is very limited. The effect of this
multiple children. The following function application has no effect
@example
-\applymusic #rev-music-1 \grace @{ c4 d4 @}
+\applyMusic #rev-music-1 \grace @{ c4 d4 @}
@end example
@noindent
In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which
has no @code{elements}, only a single @code{element}. Every generally
-applicable function for @code{\applymusic} must -- like music expressions
+applicable function for @code{\applyMusic} must -- like music expressions
themselves -- be recursive.
The following example is such a recursive function: It first extracts
\context Voice = "2" @{ \voiceTwo b @} >>
@end example
-Other applications of @code{\applymusic} are writing out repeats
+Other applications of @code{\applyMusic} are writing out repeats
automatically (@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}),
saving keystrokes (@inputfileref{input/@/test,music@/-box@/.ly}) and
exporting LilyPond input to other formats
-(@inputfileref{input/@/test,to@/-xml@/.ly})
+@c no @inputfileref{} here
+(eg. @file{input/@/no@/-notation/@/to@/-xml@/.ly}).
+
+@seealso
+
+@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
+@inputfileref{input/@/test,add@/-staccato@/.ly},
+@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
+@inputfileref{input/@/test,music@/-box@/.ly}.
+
+
+@node Displaying music expressions
+@subsection Displaying music expressions
@cindex internal storage
@cindex @code{\displayMusic}
+@cindex @code{\displayLilyMusic}
+
When writing a music function, it is often instructive to inspect how
a music expression is stored internally. This can be done with the
music function @code{\displayMusic}.
-@seealso
+@example
+@{
+ \displayMusic @{ c'4\f @}
+@}
+@end example
-@file{scm/@/music@/-functions@/.scm}, @file{scm/@/music@/-types@/.scm},
-@inputfileref{input/@/test,add@/-staccato@/.ly},
-@inputfileref{input/@/test,unfold@/-all@/-repeats@/.ly}, and
-@inputfileref{input/@/test,music@/-box@/.ly}.
+Conversely, displaying a music expression in LilyPond notation can be
+done using the music function @code{\displayLilyMusic}. For instance:
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c e g a bes @}
+@}
+@end example
+
+will display:
+
+@example
+@{ a, cis e fis g @}
+@end example
@node Using LilyPond syntax inside Scheme
@subsection Using LilyPond syntax inside Scheme
{
c'^"1"
- \applymusic #(with-padding 3) { c'^"2" c'^"3" }
+ \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
c'^"4"
}
@end lilypond
@lilypond[quote,verbatim,raggedright]
withPadding =
- #(def-music-function (location padding music) (number? ly:music?)
+ #(def-music-function (parser location padding music) (number? ly:music?)
#{ \override TextScript #'padding = #$padding
$music
\revert TextScript #'padding #})
@node Markup programmer interface
@section Markup programmer interface
-@c Please rewrite the second sentence; I don't unѕerstand its meaning. AS
-Markups are implemented as special Scheme functions. When applied with as
-arguments an output definition (@code{\layout} or @code{\paper}),
-and a list of properties and other arguments, produce a Stencil
-object.
+@c Please rewrite the second sentence; I don't understand its meaning. AS
+
+Markups are implemented as special Scheme functions. When applied
+with as arguments an output definition (@code{\layout} or
+@code{\paper}), and a list of properties and other arguments, produce
+a Stencil object.
@menu
* Markup construction in Scheme::
@noindent
is equivalent to:
@example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger @{ foo bar baz @} >
+\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+ \bigger \line @{ foo bar baz @} @}
@end example
@noindent
@quotation
@multitable @columnfractions .3 .3
@item @b{LilyPond} @tab @b{Scheme}
+@item @code{\markup markup1 @}} @tab @code{(markup markup1)}
+@item @code{\markup @{ markup1 markup2 ... @}} @tab
+ @code{(markup markup1 markup2 ... )}
@item @code{\command} @tab @code{#:command}
@item @code{\variable} @tab @code{variable}
-@item @code{@{ ... @}} @tab @code{#:line ( ... )}
-@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
+@item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
@item @code{string} @tab @code{"string"}
@item @code{#scheme-arg} @tab @code{scheme-arg}
@end multitable
function. The markup expression is stored as
@example
-(list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
+(list raise-markup 0.5 (list simple-markup "foo"))
@end example
-@noindent
-In this case, @code{latin1} is the input encoding, which is set with
-the @code{\encoding} command.
-
When the markup is converted to printable objects (Stencils), the
-raise markup is called as
+@code{raise-markup} function is called as
@example
(apply raise-markup
@var{the "foo" markup})
@end example
-The @code{raise-markup} first creates the stencil for the @code{foo}
-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}.
+The @code{raise-markup} function first creates the stencil for the
+@code{foo} 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}.
@node Markup command definition
@subsection Markup command definition
"Print the character name in small caps, translated to the left and
top. Syntax: \\character #\"name\""
(interpret-markup layout props
- (markup "" #:translate (cons -3 1) #:smallcaps name)))
+ (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
@end example
There is one complication that needs explanation: texts above and below
the staff are moved vertically to be at a certain distance (the
@code{padding} property) from the staff and the notes. To make sure
that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text. Now the @code{""} will be put above the notes, and the
+@code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
+translated text. Now the @code{#:hspace 0} will be put above the notes, and the
@code{name} is moved in relation to that empty string. The net effect is
that the text is moved to the upper left.
"Print the character name in small caps, translated to the left and
top. Syntax: \\character #\"name\""
(interpret-markup layout props
- (markup "" #:translate (cons -3 1) #:smallcaps name)))
+ (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
{
c''^\markup \character #"Cleopatra" c'' c'' c''
@subsection Context evaluation
@cindex calling code during interpreting
-@cindex @code{\applycontext}
+@cindex @code{\applyContext}
Contexts can be modified during interpretation with Scheme code. The
syntax for this is
@example
-\applycontext @var{function}
+\applyContext @var{function}
@end example
@var{function} should be a Scheme function taking a single argument,
current bar number on the standard output during the compile:
@example
-\applycontext
+\applyContext
#(lambda (x)
(format #t "\nWe were called in barnumber ~a.\n"
(ly:context-property x 'currentBarNumber)))
@cindex calling code on layout objects
-@cindex @code{\applyoutput}
+@cindex @code{\applyOutput}
-The most versatile way of tuning an object is @code{\applyoutput}. Its
+The most versatile way of tuning an object is @code{\applyOutput}. Its
syntax is
@example
-\applyoutput @var{proc}
+\applyOutput @var{proc}
@end example
@noindent
@itemize @bullet
@item the layout object itself,
@item the context where the layout object was created, and
-@item the context where @code{\applyoutput} is processed.
+@item the context where @code{\applyOutput} is processed.
@end itemize
@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
this is a @internalsref{NoteHead} object.
-Here is a function to use for @code{\applyoutput}; it blanks
+Here is a function to use for @code{\applyOutput}; it blanks
note-heads on the center-line:
@example
projects / lilypond.git / blobdiff