@c -*-texinfo-*-
@node Interfaces for programmers
-@appendix Interfaces for programmers
+@chapter Interfaces for programmers
@end menu
@node Programmer interfaces for input
-@appendixsec Programmer interfaces for input
+@section Programmer interfaces for input
@menu
* Input variables and Scheme::
* Internal music representation::
* Extending music syntax::
-* Manipulating music expressions::
+* Manipulating music expressions::
+* Using LilyPond syntax inside Scheme::
@end menu
@node Input variables and Scheme
-@appendixsubsec Input variables and Scheme
+@subsection Input variables and Scheme
The input format supports the notion of variable: in the following
\score @{ #(ly:export (make-sequential-music newLa)) @}
@end example
+@refbugs
+
+Mixing Scheme and lily identifiers is not possible with @code{--safe}.
@node Internal music representation
-@appendixsubsec Internal music representation
+@subsection Internal music representation
When a music expression is parsed, it is converted into a set of
Scheme music objects. The defining property of a music object is that
music name: Each music expression has a name, for example, a note
leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
a @internalsref{SimultaneousMusic}. A list of all expressions
-available is in the internals manual, under @internalsref{Music
-expressions}.
+available is in the internals manual, under
+@hyphenatedinternalsref{Music expressions,Music-expressions}.
@item
- `type' or interface: Each music name has several `types' or interface,
- 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}.
+ `type' or interface: Each music name has several `types' or
+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 internals manual, under
- @internalsref{Music classes}.
-@item
-C++ object: Each music object is represented by a C++ object. For technical
-reasons, different music objects may be represented by different C++
-object types. For example, a note is @code{Event} object, while
-@code{\grace} creates a @code{Grace_music} object.
+ @hyphenatedinternalsref{Music classes,Music-classes}.
+
+ @item
+C++ object: Each music object is represented by a C++ object. For
+technical reasons, different music objects may be represented by
+different C++ object types. For example, a note is @code{Event}
+object, while @code{\grace} creates a @code{Grace_music} object.
We expect that distinctions between different C++ types will disappear
in the future.
@node Extending music syntax
-@appendixsubsec Extending music syntax
+@subsection Extending music syntax
The syntax of composite music expressions, like
@code{\repeat}, @code{\transpose} and @code{\context}
@code{\applymusic} is selected by defining
@example
- apply = #(ly:make-music-function
- (list procedure? ly:music?)
- (lambda (where func music)
- (func music)))
+ applymusic = #(ly:make-music-function
+ (list procedure? ly:music?)
+ (lambda (location func music)
+ (func music)))
+@end example
+
+A @code{def-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 (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
-@appendixsubsec Manipulating music expressions
+@subsection Manipulating music expressions
Music objects and their properties can be accessed and manipulated
directly, through the @code{\applymusic} mechanism.
@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, using LilyPond usual syntax inside
+scheme, with the dedicated @code{#@{ ... #@}} syntax.
+
+The following two expressions give equivalent music expressions:
+@example
+ mynotes = @{ \override Stem #'thickness = #4
+ \notes @{ c'8 d' @} @}
+
+ #(define mynotes #@{ \override Stem #'thickness = #4
+ \notes @{ 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 $ character). This makes the creation of simple
+functions straightforward. In the following example, a function
+setting the TextScript's padding is defined:
+
+@lilypond[verbatim,raggedright]
+ #(use-modules (ice-9 optargs))
+ #(define* (textpad padding #:optional once?)
+ (ly:export ; this is necessary for using the expression
+ ; directly inside a \notes block
+ (if once?
+ #{ \once \override TextScript #'padding = #$padding #}
+ #{ \override TextScript #'padding = #$padding #})))
+
+ \score {
+ \notes {
+ 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[verbatim,raggedright]
+ #(define (with-padding padding)
+ (lambda (music)
+ #{ \override TextScript #'padding = #$padding
+ $music
+ \revert TextScript #'padding #}))
+
+ \score {
+ \notes {
+ 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
+ \score @{
+ \notes @{
+ c'^"1"
+ @{ \override TextScript #'padding = #3
+ @{ c'^"2" c'^"3"@}
+ \revert TextScript #'padding
+ @}
+ c'^"4"
+ @}
+ @}
+@end example
+
+This function may also be defined as a music function:
+
+@lilypond[verbatim,raggedright]
+ withPadding = #(def-music-function (location padding music) (number? ly:music?)
+ #{ \override TextScript #'padding = #$padding
+ $music
+ \revert TextScript #'padding #})
+
+ \score {
+ \notes {
+ c'^"1"
+ \withPadding #3
+ { c'^"2" c'^"3"}
+ c'^"4"
+ }
+ }
+@end lilypond
+
@node Markup programmer interface
-@appendixsec Markup programmer interface
+@section Markup programmer interface
@menu
@end menu
@node Markup construction in scheme
-@appendixsubsec Markup construction in scheme
+@subsection Markup construction in scheme
@cindex defining markup commands
@end lisp
@node Markup command definition
-@appendixsubsec Markup command definition
+@subsection Markup command definition
New markup commands can be defined
with the @code{def-markup-command} scheme macro.
@node Contexts for programmers
-@appendixsec Contexts for programmers
+@section Contexts for programmers
@menu
@end menu
@node Context evaluation
-@appendixsubsec Context evaluation
+@subsection Context evaluation
+
+@cindex calling code during interpreting
+@cindex @code{\applycontext}
Contexts can be modified during interpretation with Scheme code. The
syntax for this is
@node Running a function on all layout objects
-@appendixsubsec Running a function on all layout objects
+@subsection Running a function on all layout objects
+
+
+@cindex calling code on layout objects
+@cindex @code{\applyoutput}
+
The most versatile way of tuning an object is @code{\applyoutput}. Its
syntax is
projects / lilypond.git / blobdiff