Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.20"
+@c \version "2.17.6"
@node Scheme tutorial
@chapter Scheme tutorial
There are also compound data types in Scheme. The types commonly used in
LilyPond programming include pairs, lists, alists, and hash tables.
-@subheading Pairs
+@menu
+* Pairs::
+* Lists::
+* Association lists (alists)::
+* Hash tables::
+@end menu
+
+@node Pairs
+@unnumberedsubsubsec Pairs
The foundational compound data type of Scheme is the @code{pair}. As
might be expected from its name, a pair is two values glued together.
Abelson, see
@uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
-@subheading Lists
+@node Lists
+@unnumberedsubsubsec Lists
A very common Scheme data structure is the @emph{list}. Formally, a
list is defined as either the empty list (represented as @code{'()},
a dialect of lisp, where @q{lisp} is an abbreviation for
@q{List Processing}. Scheme expressions are all lists.
-@subheading Association lists (alists)
+@node Association lists (alists)
+@unnumberedsubsubsec Association lists (alists)
A special type of list is an @emph{association list} or @emph{alist}.
An alist is used to store data for easy retrieval.
Alists are widely used in LilyPond to store properties and other data.
-@subheading Hash tables
+@node Hash tables
+@unnumberedsubsubsec Hash tables
A data structure that is used occasionally in LilyPond. A hash table
is similar to an array, but the indexes to the array can be any type
value resulting from their execution. They can also manipulate
variables defined outside of the procedure.
-@subheading Defining procedures
+@menu
+* Defining procedures::
+* Predicates::
+* Return values::
+@end menu
+
+@node Defining procedures
+@unnumberedsubsubsec Defining procedures
Procedures are defined in Scheme with define
15/2
@end lisp
-@subheading Predicates
+@node Predicates
+@unnumberedsubsubsec Predicates
Scheme procedures that return boolean values are often called
@emph{predicates}. By convention (but not necessity), predicate names
#f
@end lisp
-@subheading Return values
+@node Return values
+@unnumberedsubsubsec Return values
Scheme procedures always return a return value, which is the value
of the last expression executed in the procedure. The return
@node Scheme conditionals
@subsection Scheme conditionals
-@subheading if
+@menu
+* if::
+* cond::
+@end menu
+
+@node if
+@unnumberedsubsubsec if
Scheme has an @code{if} procedure:
"a is not greater than b"
@end lisp
-@subheading cond
+@node cond
+@unnumberedsubsubsec cond
Another conditional procedure in scheme is @code{cond}:
like human language is structured into words and sentences. LilyPond
has a lexer that recognizes tokens (literal numbers, strings, Scheme
elements, pitches and so on), and a parser that understands the syntax,
-@ruser{LilyPond grammar}. Once it knows that a particular syntax rule
+@rcontrib{LilyPond grammar}. Once it knows that a particular syntax rule
applies, it executes actions associated with it.
The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
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 #@@
@example
...
-@{ $@@newLa @}
+@{ #@@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) @}
+@{ #(first newLa) #(second newLa) @}
@end example
Now in all of these forms, the Scheme code is evaluated while the
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
@node LilyPond compound variables
@subsection LilyPond compound variables
-@subheading Offsets
+@menu
+* Offsets::
+* Fractions::
+* Extents::
+* Property alists::
+* Alist chains::
+@end menu
+
+@node Offsets
+@unnumberedsubsubsec Offsets
Two-dimensional offsets (X and Y coordinates) are stored as @emph{pairs}.
The @code{car} of the offset is the X coordinate, and the @code{cdr} is
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}
Procedures for working with offsets are found in @file{scm/lily-library.scm}.
-@subheading Fractions
+@node Fractions
+@unnumberedsubsubsec Fractions
Fractions as used by LilyPond are again stored as @emph{pairs}, this
time of unsigned integers. While Scheme can represent rational numbers
means @code{(2 . 4)} in Scheme, and @code{#2/4} in LilyPond means
@code{1/2} in Scheme.
-@subheading Extents
+@node Extents
+@unnumberedsubsubsec Extents
Pairs are also used to store intervals, which represent a range of numbers
from the minimum (the @code{car}) to the maximum (the @code{cdr}).
@file{scm/lily-library.scm}. These procedures should be used when possible
to ensure consistency of code.
-@subheading Property alists
+@node Property alists
+@unnumberedsubsubsec Property alists
A property alist is a LilyPond data structure that is an alist whose
keys are properties and whose values are Scheme expressions that give
LilyPond properties are Scheme symbols, such as @code{'thickness}.
-@subheading Alist chains
+@node Alist chains
+@unnumberedsubsubsec Alist chains
An alist chain is a list containing property alists.
@example
@{
- $(with-output-to-file "display.txt"
+ #(with-output-to-file "display.txt"
(lambda () #@{ \displayMusic @{ c'4\f @} #@}))
@}
@end example
@subsection Adding articulation to notes (example)
The easy way to add articulation to notes is to merge two music
-expressions into one context, as explained in @ruser{Creating contexts}.
+expressions into one context.
However, suppose that we want to write a music function that does this.
This will have the additional advantage that we can use that music
function to add an articulation (like a fingering instruction) to a
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