Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.20"
+@c \version "2.17.6"
@node Scheme tutorial
@chapter Scheme tutorial
* LilyPond Scheme syntax::
* LilyPond variables::
* Input variables and Scheme::
+* Importing Scheme in LilyPond::
* Object properties::
* LilyPond compound variables::
* Internal music representation::
This is, in fact, exactly the same mechanism that Lilypond employs when
you call any variable or music function by name, as @code{\name}, with
-the only difference that its end is determined by the Lilypond lexer
+the only difference that the name is determined by the Lilypond lexer
without consulting the Scheme reader, and thus only variable names
consistent with the current Lilypond mode are accepted.
The immediate action of @code{$} can lead to surprises, @ref{Input
-variables and Scheme}. Using @code{#} where the parser supports it is
-usually preferable.
+variables and Scheme}. Using @code{#} where the parser supports it
+is usually preferable. Inside of music expressions, expressions
+created using @code{#} @emph{are} interpreted as music. However,
+they are @emph{not} copied before use. If they are part of some
+structure that might still get used, you may need to use
+@code{ly:music-deep-copy} explicitly.
+
+@funindex $@@
+@funindex #@@
+There are also @q{list splicing} operators @code{$@@} and @code{#@@}
+that insert all elements of a list in the surrounding context.
Now let's take a look at some actual Scheme code. Scheme procedures can
be defined in LilyPond input files:
#(define twice
(make-sequential-music newLa))
-{ \twice }
+\twice
@end lilypond
@c Due to parser lookahead
evaluating it, so it can go ahead with the assignment, and
@emph{afterwards} execute the Scheme code without problem.
+@node Importing Scheme in LilyPond
+@subsection Importing Scheme in LilyPond
+@funindex $
+@funindex #
+
The above example shows how to @q{export} music expressions from the
input to the Scheme interpreter. The opposite is also possible. By
placing it after @code{$}, a Scheme
@example
...
-@{ $(make-sequential-music (list newLa)) @}
+$(make-sequential-music newLa)
@end example
You can use @code{$} with a Scheme expression anywhere you could use
would not yet have been defined. For an explanation of this timing
problem, @ref{LilyPond Scheme syntax}.
-In any case, evaluation of Scheme code happens in the parser at latest.
-If you need it to be executed at a later point of time, @ref{Void scheme
-functions}, or store it in a macro:
+@funindex $@@
+@funindex #@@
+A further convenience can be the @q{list splicing} operators @code{$@@}
+and @code{#@@} for inserting the elements of a list in the surrounding
+context. Using those, the last part of the example could have been
+written as
+
+@example
+...
+@{ #@@newLa @}
+@end example
+
+Here, every element of the list stored in @code{newLa} is taken in
+sequence and inserted into the list, as if we had written
+
+@example
+@{ #(first newLa) #(second newLa) @}
+@end example
+
+Now in all of these forms, the Scheme code is evaluated while the
+input is still being consumed, either in the lexer or in the parser.
+If you need it to be executed at a later point of time, check out
+@ref{Void scheme functions}, or store it in a procedure:
@example
#(define (nopc)
this is:
@example
-\override Stem #'thickness = #2.6
+\override Stem.thickness = #2.6
@end example
This instruction adjusts the appearance of stems. An alist entry
the Y coordinate.
@example
-\override TextScript #'extra-offset = #'(1 . 2)
+\override TextScript.extra-offset = #'(1 . 2)
@end example
This assigns the pair @code{(1 . 2)} to the @code{extra-offset}
@example
@{
- $(with-output-to-file "display.txt"
+ #(with-output-to-file "display.txt"
(lambda () #@{ \displayMusic @{ c'4\f @} #@}))
@}
@end example
@noindent
will not work in LilyPond. We could avoid this problem by attaching
-the articulation to a fake note,
+the articulation to an empty chord,
@example
-@{ << \music s1*0-.-> @}
+@{ << \music <> -. -> >> @}
@end example
@noindent
We have seen how LilyPond output can be heavily modified using
commands like
-@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
+@code{\override TextScript.extra-offset = ( 1 . -1)}. But
we have even more power if we use Scheme. For a full explanation
of this, see the @ref{Scheme tutorial}, and
@ref{Interfaces for programmers}.
@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
#{
- \once \override TextScript #'padding = #padding
+ \once \override TextScript.padding = #padding
#})
\relative c''' {
@lilypond[quote,verbatim,ragged-right]
tempoPadded = #(define-music-function (parser location padding tempotext)
- (number? string?)
+ (number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = $padding
+ \once \override Score.MetronomeMark.padding = #padding
\tempo \markup { \bold #tempotext }
#})
\relative c'' {
\tempo \markup { "Low tempo" }
c4 d e f g1
- \tempoPadded #4.0 #"High tempo"
+ \tempoPadded #4.0 "High tempo"
g4 f e d c1
}
@end lilypond
@lilypond[quote,verbatim,ragged-right]
pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
#{
- $x e8 a b $y b a e
+ #x e8 a b #y b a e
#})
\relative c''{
projects / lilypond.git / blobdiff