* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* OLD STUFF::
+* Scheme procedures as properties::
@end menu
@menu
* Overview of music functions::
* Simple substitution functions::
-* Paired substition functions::
+* Paired substitution functions::
* Mathematics in functions::
* Void functions::
@end menu
@node Overview of music functions
@subsection Overview of music functions
-Making a funcion which substitutes a variable into LilyPond
+Making a function which substitutes a variable into LilyPond
code is easy. The general form of these functions is
@example
@end lilypond
-@node Paired substition functions
-@subsection Paired substition functions
+@node Paired substitution functions
+@subsection Paired substitution functions
Some @code{\override} commands require a pair of numbers
(called a @code{cons cell} in Scheme). To pass these numbers
@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
+define some Scheme code in a macro (to be called later), use
@ref{Void functions} or
@example
interfaces, for example, a note is an @code{event}, but it is also a
@code{note-event}, a @code{rhythmic-event}, and a
@code{melodic-event}. All classes of music are listed in the
-Profram reference, under
+Program reference, under
@internalsref{Music classes}.
@item
@subsection Displaying music expressions
@cindex internal storage
-@findex \displayMusic
-@findex \displayLilyMusic
+@funindex \displayMusic
+@funindex \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
The @code{display-scheme-music} function is the function used by
-@code{\displayMusic} to display the scheme representation of a music
+@code{\displayMusic} to display the Scheme representation of a music
expression.
@example
(ly:make-pitch 0 0 0))
@end example
-Then the note pitch is accessed thourgh the @code{'pitch} property
+Then the note pitch is accessed through the @code{'pitch} property
of the @code{NoteEvent} object,
@example
used elsewhere.
Now we have a @code{result-event-chord}, which is a
-@code{oteEventChord} expression and is a copy of @code{event-chord}. We
+@code{NoteEventChord} expression and is a copy of @code{event-chord}. We
add the marcato to its elements list property.
@example
@end multitable
@end quotation
-The whole scheme language is accessible inside the
+The whole Scheme language is accessible inside the
@code{markup} macro. For example, You may use function calls inside
@code{markup} in order to manipulate character strings. This is
useful when defining new markup commands (see
@subsection New markup command definition
New markup commands can be defined
-with the @code{define-markup-command} scheme macro.
+with the @code{define-markup-command} Scheme macro.
@lisp
(define-markup-command (@var{command-name} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
@subsection Context evaluation
@cindex calling code during interpreting
-@findex \applyContext
+@funindex \applyContext
Contexts can be modified during interpretation with Scheme code. The
syntax for this is
@cindex calling code on layout objects
-@findex \applyOutput
+@funindex \applyOutput
The most versatile way of tuning an object is @code{\applyOutput}. Its
@end example
-@node OLD STUFF
-@section OLD STUFF
+@node Scheme procedures as properties
+@section Scheme procedures as properties
-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
+Properties (like thickness, direction, etc.) can be set at fixed values
+with \override, e.g.
@example
-\applyMusic #@var{func} @var{music}
+\override Stem #'thickness = #2.0
@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)
+Properties can also be set to a Scheme procedure,
-\applyMusic #rev-music-1 { c'4 d'4 }
+@lilypond[fragment,verbatim,quote,relative=2]
+\override Stem #'thickness = #(lambda (grob)
+ (if (= UP (ly:grob-property grob 'direction))
+ 2.0
+ 7.0))
+c b a g b a g b
@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
+Procedures may also be combined like that with
+"grob closure". Here is a setting from
+@code{AccidentalSuggestion},
@example
-\applyMusic #rev-music-1 \grace @{ c4 d4 @}
+(X-offset .
+ ,(ly:make-simple-closure
+ `(,+
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::centered-on-x-parent))
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::x-aligned-on-self)))))
@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