@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::
-* Using LilyPond syntax inside Scheme::
+* 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
example, a music expression is assigned to a variable with the name
@code{traLaLa}.
@example
- traLaLa = \notes @{ c'4 d'4 @}
+ traLaLa = @{ c'4 d'4 @}
@end example
@noindent
@code{\paper} block also contains a @code{traLaLa} variable, which is
independent of the outer @code{\traLaLa}.
@example
- traLaLa = \notes @{ c'4 d'4 @}
+ traLaLa = @{ c'4 d'4 @}
\paper @{ traLaLa = 1.0 @}
@end example
@c
An anonymous Scheme module is attached to each scope. An assignment of
the form
@example
- traLaLa = \notes @{ c'4 d'4 @}
+ traLaLa = @{ c'4 d'4 @}
@end example
@noindent
is internally converted to a Scheme definition
@example
- (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
+ (define traLaLa @var{Scheme value of ``@code{... }''})
@end example
This means that input variables and Scheme variables may be freely
imported in a @code{\score} by means of a second variable
@code{twice}:
@example
- traLaLa = \notes @{ c'4 d'4 @}
+ traLaLa = @{ c'4 d'4 @}
#(define newLa (map ly:music-deep-copy
(list traLaLa traLaLa)))
#(define twice
(make-sequential-music newLa))
- \score @{ \twice @}
+ @{ \twice @}
@end example
In the above example, music expressions can be `exported' from the
input to the Scheme interpreter. The opposite is also possible. By
wrapping a Scheme value in the function @code{ly:export}, a Scheme
-value is interpreted as if it were entered in LilyPond syntax: instead
+value is interpreted as if it were entered in LilyPond syntax. Instead
of defining @code{\twice}, the example above could also have been
written as
@example
@dots{}
- \score @{ #(ly:export (make-sequential-music newLa)) @}
+ @{ #(ly:export (make-sequential-music newLa)) @}
@end example
@refbugs
-Mixing Scheme and lily identifiers is not possible with @code{--safe}.
+Mixing Scheme and LilyPond identifiers is not possible with the
+@code{--safe} option.
@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.
music object in the @code{element} object. For example,
@internalsref{SequentialMusic} has its children in @code{elements},
and @internalsref{GraceMusic} has its single argument in
-@code{element}. The body of a repeat is in @code{element} property of
-@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
+@code{element}. The body of a repeat is stored in the @code{element}
+property of @internalsref{RepeatedMusic}, and the alternatives in
+@code{elements}.
@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}
functions:
@example
- applymusic = #(def-music-function (location func music) (procedure? ly:music?)
+ applymusic = #(def-music-function (location func music)
+ (procedure? ly:music?)
(func music))
@end example
@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.
@end example
@noindent
-This means that the scheme function @var{func} is called with
+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:
+its argument,
@lilypond[verbatim,raggedright]
#(define (rev-music-1 m)
(ly:music-set-property! m 'elements (reverse
(ly:music-property m 'elements)))
m)
- \score { \notes \applymusic #rev-music-1 { c4 d4 } }
+ \applymusic #rev-music-1 { c4 d4 }
@end lilypond
The use of such a function is very limited. The effect of this
function is void when applied to an argument which is does not have
-multiple children. The following function application has no effect:
+multiple children. The following function application has no effect
@example
\applymusic #rev-music-1 \grace @{ c4 d4 @}
@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
+applicable function for @code{\applymusic} must---like music expressions
themselves -- be recursive.
The following example is such a recursive function: It first extracts
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 (@inputfileref{input/test,to-xml.ly})
+exporting LilyPond input to other formats
+(@inputfileref{input/test,to-xml.ly})
@seealso
@node Using LilyPond syntax inside Scheme
-@appendixsubsec 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
+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.
+Scheme, with the dedicated @code{#@{ ... #@}} syntax.
The following two expressions give equivalent music expressions:
@example
mynotes = @{ \override Stem #'thickness = #4
- \notes @{ c'8 d' @} @}
+ @{ c'8 d' @} @}
#(define mynotes #@{ \override Stem #'thickness = #4
- \notes @{ c'8 d' @} #@})
+ @{ 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.
+@code{SequentialMusic} music object, is then returned and usable in Scheme.
-Arbitrary scheme forms, including variables, can be used in @code{#@{ ... #@}}
+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
#(use-modules (ice-9 optargs))
#(define* (textpad padding #:optional once?)
(ly:export ; this is necessary for using the expression
- ; directly inside a \notes block
+ ; directly inside a 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'^"5"
}
- }
@end lilypond
Here, the variable @code{padding} is a number; music expression
$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
this new expression. Thus, this example is equivalent to:
@example
- \score @{
- \notes @{
+ @{
c'^"1"
@{ \override TextScript #'padding = #3
@{ c'^"2" c'^"3"@}
@}
c'^"4"
@}
- @}
@end example
This function may also be defined as a music function:
$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
+Markups implemented as special Scheme functions. When applied with as
+arguments an output definition (@code{\paper} or @code{\bookpaper}),
+and a list of properties and other arguments, produce a Stencil
+object.
@menu
-* Markup construction in scheme::
+* Markup construction in Scheme::
+* How markups work internally ::
* Markup command definition::
@end menu
-@node Markup construction in scheme
-@appendixsubsec Markup construction in scheme
+@node Markup construction in Scheme
+@subsection Markup construction in Scheme
@cindex defining markup commands
@noindent
This example exposes the main translation rules between regular
-LilyPond markup syntax and scheme markup syntax, which are summed up
+LilyPond markup syntax and Scheme markup syntax, which are summed up
is this table:
@multitable @columnfractions .5 .5
@item @b{LilyPond} @tab @b{Scheme}
@end lisp
is illegal. One should use the @code{make-line-markup} (resp
@code{make-center-markup}, @code{make-column-markup}) function
-instead:
+instead,
@lisp
(markup (make-line-markup (fun-that-returns-markups)))
@end lisp
+@node How markups work internally
+@subsection How markups work internally
+
+In a markup like
+
+@example
+ \raise #0.5 "foo"
+@end example
+
+@noindent
+@code{\raise} is actually represented by the @code{raise-markup}
+function. The markup expression is stored as
+
+@example
+ (list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
+@end example
+
+@noindent
+In this case, @code{latin1} is the input encoding, which is set with
+the @code{\encoding} command.
+
+When the markup is converted to printable objects (Stencils), the
+raise markup is called as
+
+@example
+ (apply raise-markup
+ @var{\paper object}
+ @var{list of property alists}
+ 0.5
+ @var{the "foo" markup})
+@end example
+
+The @code{raise-markup} first creates the stencil for the @code{foo}
+string, and then it raises that Stencil by 0.5 staff space. This is a
+rather simple example; more complex examples are in the rest of this
+section, and in @file{scm/define-markup-commands.scm}.
+
@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.
The final result is as follows:
@verbatim
-\score {
- \notes { \fatText
+ { \fatText
c''^\markup \character #"Cleopatra"
e'^\markup \character #"Giulio Cesare"
}
-}
@end verbatim
@lilypond[raggedright]
(interpret-markup paper props
(markup "" #:translate (cons -4 0) #:smallcaps name)))
-\score {
- \notes { \fatText
+ { \fatText
c''^\markup \character #"Cleopatra"
e'^\markup \character #"Giulio Cesare"
}
-}
@end lilypond
We have used the @code{caps} font shape, but suppose that our font
@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}
@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
projects / lilypond.git / blobdiff