+
+@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