@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Interfaces for programmers
@chapter Interfaces for programmers
* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
-* Scheme procedures as properties::
+* Scheme procedures as properties::
@end menu
* Paired substitution functions::
* Mathematics in functions::
* Void functions::
+* Functions without arguments::
+* Overview of available music functions::
@end menu
@node Overview of music functions
and are used in some advanced situations. The @code{parser}
argument is used to access to the value of another LilyPond
variable. The @code{location} argument
-is used to set the ``origin'' of the music expression that is built
+is used to set the @q{origin} of the music expression that is built
by the music function, so that in case of a syntax error LilyPond
can tell the user an appropriate place to look in the input file.
(number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $marktext }
#})
@end example
+@node Functions without arguments
+@subsection Functions without arguments
+
+In most cases a function without arguments should be written
+with an identifier,
+
+@example
+dolce = \markup@{ \italic \bold dolce @}
+@end example
+
+However, in rare cases it may be useful to create a music function
+without arguments,
+
+@example
+displayBarNum =
+#(define-music-function (parser location) ()
+ (if (eq? #t (ly:get-option display-bar-numbers))
+ #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{#@}))
+@end example
+
+To actually display bar numbers where this function is called,
+invoke lilypond with
+
+@example
+lilypond -d display-bar-numbers FILENAME.ly
+@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
@noindent
is internally converted to a Scheme definition
@example
-(define traLaLa @var{Scheme value of ``@code{... }''})
+(define traLaLa @var{Scheme value of `@code{... }'})
@end example
This means that input variables and Scheme variables may be freely
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 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.
-In the above example, music expressions can be `exported' from the
+The above example shows how to @q{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))) @}
@internalsref{Music expressions}.
@item
-`type' or interface: Each music name has several `types' or
+@q{type} or interface: Each music name has several @q{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
A compound music expression is a music object that contains other
music objects in its properties. A list of objects can be stored in
-the @code{elements} property of a music object, or a single `child'
+the @code{elements} property of a music object, or a single @q{child}
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
@subsection Doubling a note with slurs (example)
Suppose we want to create a function which translates
-input like ``@code{a}'' into ``@code{a( a)}''. We begin
+input like @samp{a} into @samp{a( a)}. We begin
by examining the internal representation of the music
we want to end up with.
@end example
The bad news is that the @code{SlurEvent} expressions
-must be added ``inside'' the note (or more precisely,
+must be added @q{inside} the note (or more precisely,
inside the @code{EventChord} expression).
Now we examine the input,
@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)))
(let ((result-event-chord (ly:music-deep-copy event-chord)))
@end example
-`@code{let}' is used to declare local variables. Here we use one local
-variable, named `@code{result-event-chord}', to which we give the value
-@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
+@code{let} is used to declare local variables. Here we use one local
+variable, named @code{result-event-chord}, to which we give the value
+@code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
a function specific to LilyPond, like all functions prefixed by
-`@code{ly:}'. It is use to make a copy of a music
-expression. Here we copy `@code{event-chord} (the parameter of the
+@code{ly:}. It is use to make a copy of a music
+expression. Here we copy @code{event-chord} (the parameter of the
function). Recall that our purpose is to add a marcato to an
@code{EventChord} expression. It is better to not modify the
@code{EventChord} which was given as an argument, because it may be
(ly:music-property result-event-chord 'elements))
@end example
-`@code{cons}' is used to add an element to a list without modifying the
+@code{cons} is used to add an element to a list without modifying the
original list. This is what we
want: the same list as before, plus the new @code{ArticulationEvent}
expression. The order inside the elements property is not important here.
@item argi-type?
a type predicate for the i@var{th} argument
@item layout
-the `layout' definition
+the @q{layout} definition
@item props
a list of alists, containing all active properties.
@end table
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
(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