* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* OLD STUFF::
@end menu
* Simple substitution functions::
* Paired substition functions::
* Mathematics in functions::
+* Void functions::
@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
variables as @code{#$var1}.
@end multitable
-The following input types may be used as variables
-in a music function.
+There following input types may be used as variables
+in a music function. This list is not exhaustive; see
+other documentation specifically about Scheme for more
+variable types.
@multitable @columnfractions .33 .66
@headitem Input type @tab @var{argi-type?} notation
@item Text string @tab @code{string?}
@item Markup @tab @code{markup?}
@item Music expression @tab @code{ly:music?}
-@item A pair of numbers @tab @code{pair?}
+@item A pair of variables @tab @code{pair?}
@end multitable
+The @code{parser} and @code{location} argument are mandatory,
+and are used in some advanced situations. The @code{parser}
+argument is used to access to the value of another LilyPond
+variable. The @code{location} argument
+is used to set the ``origin'' of the music expression that is built
+by the music function, so that in case of a syntax error LilyPond
+can tell the user an appropriate place to look in the input file.
+
@node Simple substitution functions
@subsection Simple substitution functions
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
#})
Multiple variables may be used,
@lilypond[quote,verbatim,ragged-right]
-tempoMark = #(define-music-function (parser location marktext padding)
- (string? number?)
+tempoMark = #(define-music-function (parser location padding marktext)
+ (number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
\once \override Score . RehearsalMark #'no-spacing-rods = ##t
\relative c'' {
c2 e
-\tempoMark #"Allegro" #3.0
+\tempoMark #3.0 #"Allegro"
g c
}
@end lilypond
(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
@end lilypond
+@node Void functions
+@subsection Void functions
+
+A music function must return a music expression, but sometimes we
+may want to have a function which does not involve music (such as
+turning off Point and Click). To do this, we return a @code{void}
+music expression.
+
+That is why the form
+that is returned is the @code{(make-music ...)}. With the
+@code{'void} property set to @code{#t}, the parser is told to
+actually disregard this returned music
+expression. Thus the important part of the void music function is the
+processing done by the function, not the music expression that is
+returned.
+
+@example
+noPointAndClick =
+#(define-music-function (parser location) ()
+ (ly:set-option 'point-and-click #f)
+ (make-music 'SequentialMusic 'void #t))
+...
+\noPointAndClick % disable point and click
+@end example
+
@node Programmer interfaces
@section Programmer interfaces
Scheme code is evaluated as soon as the parser encounters it. To
define some scheme code in a macro (to be called later), use
+@ref{Void functions} or
@example
#(define (nopc)
@menu
* Displaying music expressions::
+* Music properties::
* Doubling a note with slurs (example)::
* Adding articulation to notes (example)::
@end menu
@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
lilypond file.ly >display.txt
@end example
+With a bit of reformatting, the above information is
+easier to read,
+
+@example
+(make-music 'SequentialMusic
+ 'elements (list (make-music 'EventChord
+ 'elements (list (make-music 'NoteEvent
+ 'duration (ly:make-duration 2 0 1 1)
+ 'pitch (ly:make-pitch 0 0 0))
+ (make-music 'AbsoluteDynamicEvent
+ 'text "f")))))
+@end example
+
+A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
+and its inner expressions are stored as a list in its @code{'elements}
+property. A note is represented as an @code{EventChord} expression,
+containing a @code{NoteEvent} object (storing the duration and
+pitch properties) and any extra information (in this case, an
+@code{AbsoluteDynamicEvent} with a @code{"f"} text property.
+
+
+@node Music properties
+@subsection Music properties
+
+The @code{NoteEvent} object is the first object of the
+@code{'elements} property of @code{someNote}.
+
+@example
+someNote = c'
+\displayMusic \someNote
+===>
+(make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0))))
+@end example
+
+The @code{display-scheme-music} function is the function used by
+@code{\displayMusic} to display the scheme representation of a music
+expression.
+
+@example
+#(display-scheme-music (first (ly:music-property someNote 'elements)))
+===>
+(make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0))
+@end example
+
+Then the note pitch is accessed thourgh the @code{'pitch} property
+of the @code{NoteEvent} object,
+
+@example
+#(display-scheme-music
+ (ly:music-property (first (ly:music-property someNote 'elements))
+ 'pitch))
+===>
+(ly:make-pitch 0 0 0)
+@end example
+
+The note pitch can be changed by setting this 'pitch property,
+
+@example
+#(set! (ly:music-property (first (ly:music-property someNote 'elements))
+ 'pitch)
+ (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
+\displayLilyMusic \someNote
+===>
+d'
+@end example
+
@node Doubling a note with slurs (example)
@subsection Doubling a note with slurs (example)
@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.
(ly:music-property result-event-chord 'elements))
@end example
-`@code{cons}' is used to add an element to a list. This is what we
+`@code{cons}' is used to add an element to a list without modifying the
+original list. This is what we
want: the same list as before, plus the new @code{ArticulationEvent}
expression. The order inside the elements property is not important here.
@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}
useful when defining new markup commands (see
@ref{New markup command definition}).
+
@refbugs
-One can not feed the @code{#:line}, @code{#:center}, or
-@code{#:column}) commands with a variable or the result of a function
-call. Example:
+The markup-list argument of commands such as @code{#:line},
+@code{#:center}, and @code{#:column} cannot be a variable or
+the result of a function call.
@lisp
(markup #:line (function-that-returns-markups))
@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
-
-
-