-@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
+Scheme code is evaluated as soon as the parser encounters it. To
+define some scheme code in a macro (to be called later), use
+
+@example
+#(define (nopc)
+ (ly:set-option 'point-and-click #f))
+
+...
+#(nopc)
+@{ c'4 @}
+@end example
+
+
@refbugs
Mixing Scheme and LilyPond identifiers is not possible with the
@code{--safe} option.
+
@node Internal music representation
@subsection Internal music representation
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 (parser location func music)
(func music)))
@end example
-A @code{def-music-function} macro is introduced on top of
+A @code{define-music-function} macro is introduced on top of
@code{ly:make-music-function} to ease the definition of music
functions:
@example
-applymusic = #(def-music-function (parser location func music)
+applyMusic = #(define-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
An example is a function that reverses the order of elements in
its argument,
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
#(define (rev-music-1 m)
(ly:music-set-property! m 'elements
(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
functions straightforward. In the following example, a function
setting the TextScript's padding is defined:
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
#(use-modules (ice-9 optargs))
#(define* (textpad padding #:optional once?)
(ly:export ; this is necessary for using the expression
variables may also be used in a similar fashion, as in the following
example:
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
#(define (with-padding padding)
(lambda (music)
#{ \override TextScript #'padding = #$padding
{
c'^"1"
- \applymusic #(with-padding 3) { c'^"2" c'^"3" }
+ \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
c'^"4"
}
@end lilypond
This function may also be defined as a music function:
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
withPadding =
- #(def-music-function (parser location padding music) (number? ly:music?)
+ #(define-music-function (parser location padding music) (number? ly:music?)
#{ \override TextScript #'padding = #$padding
$music
\revert TextScript #'padding #})
@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
@code{raise-markup} function is called as
@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
New markup commands can be defined
-with the @code{def-markup-command} scheme macro.
+with the @code{define-markup-command} scheme macro.
@lisp
-(def-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
+(define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
(@var{arg1-type?} @var{arg2-type?} ...)
..command body..)
@end lisp
@code{#'caps} for interpreting @code{Text-in-caps}.
To make the above available as @code{\smallcaps} command, we have to
-define a function using @code{def-markup-command}. The command should
+define a function using @code{define-markup-command}. The command should
take a single argument, of type markup. Therefore, the start of the
definition should read
@example
-(def-markup-command (smallcaps layout props argument) (markup?)
+(define-markup-command (smallcaps layout props argument) (markup?)
@end example
@noindent
defined @code{\smallcaps} command:
@example
-#(def-markup-command (character layout props name) (string?)
+#(define-markup-command (character layout props name) (string?)
"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.
@}
@end example
-@lilypond[quote,raggedright]
-#(def-markup-command (smallcaps layout props str) (string?)
+@lilypond[quote,ragged-right]
+#(define-markup-command (smallcaps layout props str) (string?)
"Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
(interpret-markup layout props
(make-line-markup
#:tiny (string-upcase (substring s 1)))))
(string-split str #\Space)))))
-#(def-markup-command (character layout props name) (string?)
+#(define-markup-command (character layout props name) (string?)
"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''
letter a little larger:
@example
-#(def-markup-command (smallcaps layout props str) (string?)
+#(define-markup-command (smallcaps layout props str) (string?)
"Print the string argument in small caps."
(interpret-markup layout props
(make-line-markup
@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