* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* OLD STUFF::
@end menu
@end menu
@node Overview of music functions
-@subsection Overview of music functions
+@subsection Overview of music functions
Making a funcion which substitutes a variable into LilyPond
code is easy. The general form of these functions is
c4^"piu mosso" d e f
\padText #2.6
c4^"piu mosso" fis a g
-}
+}
@end lilypond
Music expressions may be substituted as well,
@lilypond[quote,verbatim,ragged-right]
custosNote = #(define-music-function (parser location note)
(ly:music?)
- #{
- \once \override Voice.NoteHead #'stencil =
+ #{
+ \once \override Voice.NoteHead #'stencil =
#ly:text-interface::print
- \once \override Voice.NoteHead #'text =
+ \once \override Voice.NoteHead #'text =
\markup \musicglyph #"custodes.mensural.u0"
- \once \override Voice.Stem #'stencil = ##f
+ \once \override Voice.Stem #'stencil = ##f
$note
#})
@lilypond[quote,verbatim,ragged-right]
tempoMark = #(define-music-function (parser location padding marktext)
- (number? string?)
+ (number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
\once \override Score . RehearsalMark #'no-spacing-rods = ##t
(number? number?)
#{
\once \override Beam #'positions = #(cons $beg $end)
-#})
+#})
\relative {
\manualBeam #3 #6 c8 d e f
}
-@end lilypond
+@end lilypond
@node Mathematics in functions
addition to simple substitution,
@lilypond[quote,verbatim,ragged-right]
-AltOn = #(define-music-function (parser location mag) (number?)
+AltOn = #(define-music-function (parser location mag) (number?)
#{ \override Stem #'length = #$(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override NoteHead #'font-size =
#$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
AltOff = {
\revert Stem #'length
- \revert NoteHead #'font-size
+ \revert NoteHead #'font-size
}
{ c'2 \AltOn #0.5 c'4 c'
This example may be rewritten to pass in music expressions,
@lilypond[quote,verbatim,ragged-right]
-withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
+withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
#{ \override Stem #'length = #$(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override NoteHead #'font-size =
#$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
$music
\revert Stem #'length
@subsection Displaying music expressions
@cindex internal storage
-@cindex @code{\displayMusic}
-@cindex @code{\displayLilyMusic}
+@findex \displayMusic
+@findex \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
@end example
`@code{let}' is used to declare local variables. Here we use one local
-variable, named `@code{result-event-chord}', to which we give the value
+variable, named `@code{result-event-chord}', to which we give the value
@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
a function specific to LilyPond, like all functions prefixed by
`@code{ly:}'. It is use to make a copy of a music
@code{EventChord} which was given as an argument, because it may be
used elsewhere.
-Now we have a @code{result-event-chord}, which is a
+Now we have a @code{result-event-chord}, which is a
@code{oteEventChord} expression and is a copy of @code{event-chord}. We
add the marcato to its elements list property.
@node Markup construction in Scheme
@subsection Markup construction in Scheme
-@cindex defining markup commands
+@cindex defining markup commands
The @code{markup} macro builds markup expressions in Scheme while
providing a LilyPond-like syntax. For example,
@multitable @columnfractions .3 .3
@item @b{LilyPond} @tab @b{Scheme}
@item @code{\markup markup1} @tab @code{(markup markup1)}
-@item @code{\markup @{ markup1 markup2 ... @}} @tab
+@item @code{\markup @{ markup1 markup2 ... @}} @tab
@code{(markup markup1 markup2 ... )}
@item @code{\command} @tab @code{#:command}
@item @code{\variable} @tab @code{variable}
@item layout
the `layout' definition
@item props
-a list of alists, containing all active properties.
+a list of alists, containing all active properties.
@end table
As a simple example, we show how to add a @code{\smallcaps} command,
#(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
+ (interpret-markup layout props
(markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
@end example
#(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
+ (interpret-markup layout props
(markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
{
@subsection Context evaluation
@cindex calling code during interpreting
-@cindex @code{\applyContext}
+@findex \applyContext
Contexts can be modified during interpretation with Scheme code. The
syntax for this is
@cindex calling code on layout objects
-@cindex @code{\applyOutput}
+@findex \applyOutput
The most versatile way of tuning an object is @code{\applyOutput}. Its
syntax is
@example
-\applyOutput @var{proc}
+\applyOutput @var{context} @var{proc}
@end example
@noindent
where @var{proc} is a Scheme function, taking three arguments.
When interpreted, the function @var{proc} is called for every layout
-object found in the context, with the following arguments:
+object found in the context @var{context}, with the following
+arguments:
@itemize @bullet
@item the layout object itself,
@item the context where the layout object was created, and
(set! (ly:grob-property grob 'transparent) #t)))
@end example
-
-@node OLD STUFF
-@section OLD STUFF
-
-This stuff is slated for deletion or merger into the earlier sections.
-
-@menu
-* Extending music syntax::
-* Manipulating music expressions::
-* Using LilyPond syntax inside Scheme::
-@end menu
-
-
-@node Extending music syntax
-@subsection Extending music syntax
-
-@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}
-@end example
-
-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
-a user-defined function to a music expression. Its syntax is
-
-@example
-\applyMusic #@var{func} @var{music}
-@end example
-
-A music function is created with @code{ly:make-music-function},
-
-@example
-(ly:make-music-function
-@end example
-
-@code{\applyMusic} takes a Scheme function and a Music expression as
-arguments. This is encoded in its parameter list,
-
-@example
-(list procedure? ly:music?)
-@end example
-
-The function itself takes another argument: an Input location
-object. That object is used to provide error messages with file names
-and line numbers. The definition is the second argument of
-@code{ly:make-music-function}. The body simply calls the function
-
-@example
-(lambda (where func music)
- (func music))
-@end example
-
-The above Scheme code only defines the functionality. The tag
-@code{\applyMusic} is selected by defining
-
-@example
-applyMusic = #(ly:make-music-function
- (list procedure? ly:music?)
- (lambda (parser location func music)
- (func music)))
-@end example
-
-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 = #(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.
-
-@seealso
-@file{ly/@/music@/-functions@/-init@/.ly}.
-
-
-@node Manipulating music expressions
-@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
-
-@example
-\applyMusic #@var{func} @var{music}
-@end example
-
-@noindent
-This means that the Scheme function @var{func} is called with
-@var{music} as its argument. The return value of @var{func} is the
-result of the entire expression. @var{func} may read and write music
-properties using the functions @code{ly:music-property} and
-@code{ly:music-set-property!}.
-
-An example is a function that reverses the order of elements in
-its argument,
-@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 }
-@end lilypond
-
-The use of such a function is very limited. The effect of this
-function is void when applied to an argument that does not have
-multiple children. The following function application has no effect
-
-@example
-\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
-themselves -- be recursive.
-
-The following example is such a recursive function: It first extracts
-the @code{elements} of an expression, reverses them and puts them
-back. Then it recurses, both on @code{elements} and @code{element}
-children.
-
-@example
-#(define (reverse-music music)
- (let* ((elements (ly:music-property music 'elements))
- (child (ly:music-property music 'element))
- (reversed (reverse elements)))
-
- ; set children
- (ly:music-set-property! music 'elements reversed)
-
- ; recurse
- (if (ly:music? child) (reverse-music child))
- (map reverse-music reversed)
-
- music))
-@end example
-
-A slightly more elaborate example is in
-@inputfileref{input/@/test,reverse@/-music@/.ly}.
-
-Some of the input syntax is also implemented as recursive music
-functions. For example, the syntax for polyphony
-@example
-<<a \\ b>>
-@end example
-
-@noindent
-is actually implemented as a recursive function that replaces the
-above by the internal equivalent of
-@example
-<< \context Voice = "1" @{ \voiceOne a @}
- \context Voice = "2" @{ \voiceTwo b @} >>
-@end example
-
-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
-@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 Using LilyPond syntax inside Scheme
-@subsection Using LilyPond syntax inside Scheme
-
-Creating music expressions in Scheme can be tedious, as they are
-heavily nested and the resulting Scheme code is large. For some
-simple tasks this can be avoided by using common LilyPond syntax inside
-Scheme, with the dedicated @code{#@{ ... #@}} syntax.
-
-The following two expressions give equivalent music expressions:
-@example
-mynotes = @{ \override Stem #'thickness = #4
- @{ c'8 d' @} @}
-
-#(define mynotes #@{ \override Stem #'thickness = #4
- @{ c'8 d' @} #@})
-@end example
-
-The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
-... @}} block, which is parsed. The resulting music expression, a
-@code{SequentialMusic} music object, is then returned and usable in Scheme.
-
-Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
-expressions with the @code{$} character (@code{$$} can be used to
-produce a single @code{$} character). This makes the creation of simple
-functions straightforward. In the following example, a function
-setting the TextScript's padding is defined:
-
-@lilypond[quote,verbatim,ragged-right]
-#(use-modules (ice-9 optargs))
-#(define* (textpad padding #:optional once?)
- (ly:export ; this is necessary for using the expression
- ; directly inside a block
- (if once?
- #{ \once \override TextScript #'padding = #$padding #}
- #{ \override TextScript #'padding = #$padding #})))
-
- {
- c'^"1"
- #(textpad 3.0 #t) % only once
- c'^"2"
- c'^"3"
- #(textpad 5.0)
- c'^"4"
- c'^"5"
- }
-@end lilypond
-
-Here, the variable @code{padding} is a number; music expression
-variables may also be used in a similar fashion, as in the following
-example:
-
-@lilypond[quote,verbatim,ragged-right]
-#(define (with-padding padding)
- (lambda (music)
- #{ \override TextScript #'padding = #$padding
- $music
- \revert TextScript #'padding #}))
-
-{
- c'^"1"
- \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
- c'^"4"
-}
-@end lilypond
-
-The function created by @code{(with-padding 3)} adds @code{\override} and
-@code{\revert} statements around the music given as an argument, and returns
-this new expression. Thus, this example is equivalent to:
-
-@example
-@{
- c'^"1"
- @{ \override TextScript #'padding = #3
- @{ c'^"2" c'^"3"@}
- \revert TextScript #'padding
- @}
- c'^"4"
-@}
-@end example
-
-
-
projects / lilypond.git / blobdiff