* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* Scheme procedures as properties::
+* 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::
+* Overview of available music 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
\withAlt #1.5 {c' c'} c'2 }
@end lilypond
-
@node Void functions
@subsection Void functions
\noPointAndClick % disable point and click
@end example
+@node Overview of available music functions
+@subsection Overview of available music functions
+
+@c fixme ; this should be move somewhere else?
+The following commands are music functions
+
+@include identifiers.tely
+
+
@node Programmer interfaces
@section Programmer interfaces
variable @code{traLaLa}, and duplicated using Scheme. The result is
imported in a @code{\score} block by means of a second variable
@code{twice}:
-@example
-traLaLa = @{ c'4 d'4 @}
+
+@lilypond[verbatim]
+traLaLa = { c'4 d'4 }
+
+%% dummy action to deal with parser lookahead
+#(display "this needs to be here, sorry!")
#(define newLa (map ly:music-deep-copy
(list traLaLa traLaLa)))
#(define twice
(make-sequential-music newLa))
-@{ \twice @}
-@end example
+{ \twice }
+@end lilypond
+
+Due to parser lookahead
-In the above example, music expressions can be `exported' from the
+In this example, the assignment happens after parser has verified that
+nothing interesting happens after @code{traLaLa = @{ ... @}}. Without
+the dummy statement in the above example, the @code{newLa} definition
+is executed before @code{traLaLa} is defined, leading to a syntax
+error.
+
+The above example shows how to `export' music expressions 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
-of defining @code{\twice}, the example above could also have been
-written as
+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{}
@{ #(ly:export (make-sequential-music (list newLa))) @}
@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
@code{SequentialMusic} with the two @code{EventChords}.
@example
-doubleSlur = #(def-music-function (parser location note) (ly:music?)
+doubleSlur = #(define-music-function (parser location note) (ly:music?)
"Return: @{ note ( note ) @}.
`note' is supposed to be an EventChord."
(let ((note2 (ly:music-deep-copy note)))
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
c b a g b a g b
@end lilypond
-Procedures may also be combined like that with
-"grob closure". Here is a setting from
+@noindent
+In this case, the procedure is executed as soon as the value of the
+property is requested during the formatting process.
+
+Most of the typesetting engine is driven by such callbacks.
+Properties that typically use callbacks include
+
+@table @code
+@item stencil
+ The printing routine, that constructs a drawing for the symbol
+@item X-offset
+ The routine that sets the horizontal position
+@item X-extent
+ The routine that computes the width of an object
+@end table
+
+The procedure always takes a single argument, being the grob.
+
+If routines with multiple arguments must be called, the current grob
+can be inserted with a grob closure. Here is a setting from
@code{AccidentalSuggestion},
@example
-(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)))))
+(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 example, both @code{ly:self-alignment-interface::x-aligned-on-self} and
+@code{ly:self-alignment-interface::centered-on-x-parent} are called
+with the grob as argument. The results are added with the @code{+}
+function. To ensure that this addition is properly executed, the whole
+thing is enclosed in @code{ly:make-simple-closure}.
+In fact, using a single procedure as property value is equivalent to
+
+@example
+(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
+@end example
+
+@noindent
+The inner @code{ly:make-simple-closure} supplies the grob as argument
+to @var{proc}, the outer ensures that result of the function is
+returned, rather than the @code{simple-closure} object.
projects / lilypond.git / blobdiff