1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @chapter Scheme tutorial
18 @cindex Scheme, in-line code
19 @cindex accessing Scheme
20 @cindex evaluating Scheme
23 LilyPond uses the Scheme programming language, both as part of the
24 input syntax, and as internal mechanism to glue modules of the program
25 together. This section is a very brief overview of entering data in
26 Scheme. If you want to know more about Scheme, see
27 @uref{http://@/www@/.schemers@/.org}.
29 LilyPond uses the GNU Guile implementation of Scheme, which is
30 based on the Scheme @qq{R5RS} standard. If you are learning Scheme
31 to use with LilyPond, working with a different implementation (or
32 referring to a different standard) is not recommended. Information
33 on guile can be found at @uref{http://www.gnu.org/software/guile/}.
34 The @qq{R5RS} Scheme standard is located at
35 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
38 * Introduction to Scheme::
39 * Scheme in LilyPond::
40 * Building complicated functions::
43 @node Introduction to Scheme
44 @section Introduction to Scheme
46 We begin with an introduction to Scheme. For this brief introduction,
47 we will use the GUILE interpreter to explore how the language works.
48 Once we are familiar with Scheme, we will show how the language can
49 be integrated in LilyPond files.
55 * Scheme simple data types::
56 * Scheme compound data types::
57 * Calculations in Scheme::
59 * Scheme conditionals::
63 @subsection Scheme sandbox
65 The LilyPond installation includes the Guile implementation of
66 Scheme. On most systems you can experiment in a Scheme sandbox by
67 opening a terminal window and typing @q{guile}. On some systems,
68 notably Windows, you may need to set the environment variable
69 @code{GUILE_LOAD_PATH} to the directory @code{../usr/share/guile/1.8}
70 in the LilyPond installation. For the full path to this directory
71 see @rlearning{Other sources of information}. Alternatively, Windows
72 users may simply choose @q{Run} from the Start menu and enter
75 However, a hands-on Scheme sandbox with all of LilyPond loaded is
76 available with this command line:
78 lilypond scheme-sandbox
82 Once the sandbox is running, you will receive a guile prompt:
88 You can enter Scheme expressions at this prompt to experiment with
89 Scheme. If you want to be able to use the GNU readline library for
90 nicer editing of the Scheme command line, check the file
91 @file{ly/scheme-sandbox.ly} for more information. If you already have
92 enabled the readline library for your interactive Guile sessions outside
93 of LilyPond, this should work in the sandbox as well.
95 @node Scheme variables
96 @subsection Scheme variables
98 Scheme variables can have any valid scheme value, including a Scheme
101 Scheme variables are created with @code{define}:
108 Scheme variables can be evaluated at the guile prompt simply by
109 typing the variable name:
117 Scheme variables can be printed on the display by using the display function:
125 Note that both the value @code{2} and the guile prompt @code{guile}
126 showed up on the same line. This can be avoided by calling the
127 newline procedure or displaying a newline character.
130 guile> (display a)(newline)
132 guile> (display a)(display "\n")
137 Once a variable has been created, its value can be changed with @code{set!}:
140 guile> (set! a 12345)
146 @node Scheme simple data types
147 @subsection Scheme simple data types
149 The most basic concept in a language is data typing: numbers, character
150 strings, lists, etc. Here is a list of simple Scheme data types that are
151 often used with LilyPond.
155 Boolean values are True or False. The Scheme for True is @code{#t}
156 and False is @code{#f}.
161 Numbers are entered in the standard fashion,
162 @code{1} is the (integer) number one, while @w{@code{-1.5}} is a
163 floating point number (a non-integer number).
166 Strings are enclosed in double quotes:
172 Strings may span several lines:
181 and the newline characters at the end of each line will be included
184 Newline characters can also be added by including @code{\n} in the
188 "this\nis a\nmultiline string"
192 Quotation marks and backslashes are added to strings
193 by preceding them with a backslash.
194 The string @code{\a said "b"} is entered as
202 There are additional Scheme data types that are not discussed here.
203 For a complete listing see the Guile reference guide,
204 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
206 @node Scheme compound data types
207 @subsection Scheme compound data types
209 There are also compound data types in Scheme. The types commonly used in
210 LilyPond programming include pairs, lists, alists, and hash tables.
215 * Association lists (alists)::
220 @unnumberedsubsubsec Pairs
222 The foundational compound data type of Scheme is the @code{pair}. As
223 might be expected from its name, a pair is two values glued together.
224 The operator used to form a pair is called @code{cons}.
232 Note that the pair is displayed as two items surrounded by
233 parentheses and separated by whitespace, a period (@code{.}), and
234 more whitespace. The period is @emph{not} a decimal point, but
235 rather an indicator of the pair.
237 Pairs can also be entered as literal values by preceding them with
238 a single quote character.
246 The two elements of a pair may be any valid Scheme value:
251 guile> '("blah-blah" . 3.1415926535)
252 ("blah-blah" . 3.1415926535)
256 The first and second elements of the pair can be accessed by the
257 Scheme procedures @code{car} and @code{cdr}, respectively.
260 guile> (define mypair (cons 123 "hello there")
271 Note: @code{cdr} is pronounced "could-er", according Sussman and
273 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
276 @unnumberedsubsubsec Lists
278 A very common Scheme data structure is the @emph{list}. Formally,
279 a @q{proper} list is defined to be either the empty list with its
280 input form @code{'()} and length@tie{}0, or a pair whose
281 @code{cdr} in turn is a shorter list.
283 There are many ways of creating lists. Perhaps the most common is
284 with the @code{list} procedure:
287 guile> (list 1 2 3 "abc" 17.5)
291 Representing a list as individual
292 elements separated by whitespace and enclosed in parentheses
293 is actually a compacted rendition of the actual dotted pairs
294 constituting the list, where the dot and an immediately following
295 starting paren are removed along with the matching closing paren.
296 Without this compaction, the output would have been
298 (1 . (2 . (3 . ("abc" . (17.5 . ())))))
301 As with the output, a list can also be entered (after adding a
302 quote to avoid interpretation as a function call) as a literal
303 list by enclosing its elements in parentheses:
306 guile> '(17 23 "foo" "bar" "bazzle")
307 (17 23 "foo" "bar" "bazzle")
310 Lists are a central part of Scheme. In, fact, Scheme is considered
311 a dialect of lisp, where @q{lisp} is an abbreviation for
312 @q{List Processing}. Scheme expressions are all lists.
314 @node Association lists (alists)
315 @unnumberedsubsubsec Association lists (alists)
317 A special type of list is an @emph{association list} or @emph{alist}.
318 An alist is used to store data for easy retrieval.
320 Alists are lists whose elements are pairs. The @code{car} of each
321 element is called the @emph{key}, and the @code{cdr} of each element
322 is called the @emph{value}. The Scheme procedure @code{assoc} is
323 used to retrieve an entry from the alist, and @code{cdr} is used to
327 guile> (define my-alist '((1 . "A") (2 . "B") (3 . "C")))
329 ((1 . "A") (2 . "B") (3 . "C"))
330 guile> (assoc 2 my-alist)
332 guile> (cdr (assoc 2 my-alist))
337 Alists are widely used in LilyPond to store properties and other data.
340 @unnumberedsubsubsec Hash tables
342 A data structure that is used occasionally in LilyPond. A hash table
343 is similar to an array, but the indexes to the array can be any type
344 of Scheme value, not just integers.
346 Hash tables are more efficient than alists if there is a lot of data
347 to store and the data changes very infrequently.
349 The syntax to create hash tables is a bit complex, but you
350 can see examples of it in the LilyPond source.
353 guile> (define h (make-hash-table 10))
356 guile> (hashq-set! h 'key1 "val1")
358 guile> (hashq-set! h 'key2 "val2")
360 guile> (hashq-set! h 3 "val3")
364 Values are retrieved from hash tables with @code{hashq-ref}.
367 guile> (hashq-ref h 3)
369 guile> (hashq-ref h 'key2)
374 Keys and values are retrieved as a pair with @code{hashq-get-handle}.
375 This is a preferred way, because it will return @code{#f} if a key is
379 guile> (hashq-get-handle h 'key1)
381 guile> (hashq-get-handle h 'frob)
386 @node Calculations in Scheme
387 @subsection Calculations in Scheme
390 We have been using lists all along. A calculation, like @code{(+ 1 2)}
391 is also a list (containing the symbol @code{+} and the numbers 1
392 and@tie{}2). Normally lists are interpreted as calculations, and the
393 Scheme interpreter substitutes the outcome of the calculation. To enter a
394 list, we stop the evaluation. This is done by quoting the list with a
395 quote @code{'} symbol. So, for calculations do not use a quote.
397 Inside a quoted list or pair, there is no need to quote anymore. The
398 following is a pair of symbols, a list of symbols and a list of lists
403 #'(staff clef key-signature)
408 Scheme can be used to do calculations. It uses @emph{prefix}
409 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
410 traditional @math{1+2}.
417 Calculations may be nested; the result of a function may
418 be used for another calculation.
425 These calculations are examples of evaluations; an expression like
426 @code{(* 3 4)} is replaced by its value @code{12}.
428 Scheme calculations are sensitive to the differences between integers
429 and non-integers. Integer calculations are exact, while non-integers
430 are calculated to the appropriate limits of precision:
439 When the scheme interpreter encounters an expression that is a list,
440 the first element of the list is treated as a procedure to be
441 evaluated with the arguments of the remainder of the list. Therefore,
442 all operators in Scheme are prefix operators.
444 If the first element of a Scheme expression that is a list passed to
445 the interpreter is @emph{not} an operator or procedure, an error will
455 <unnamed port>:52:1: In expression (1 2 3):
456 <unnamed port>:52:1: Wrong type to apply: 1
461 Here you can see that the interpreter was trying to treat 1 as an
462 operator or procedure, and it couldn't. Hence the error is "Wrong
465 Therefore, to create a list we need to use the list operator, or to
466 quote the list so that the interpreter will not try to evaluate it.
476 This is an error that can appear as you are working with Scheme in LilyPond.
479 The same assignment can be done in completely in Scheme as well,
482 #(define twentyFour (* 2 twelve))
485 @c this next section is confusing -- need to rewrite
487 The @emph{name} of a variable is also an expression, similar to a
488 number or a string. It is entered as
495 @cindex quoting in Scheme
497 The quote mark @code{'} prevents the Scheme interpreter from substituting
498 @code{24} for the @code{twentyFour}. Instead, we get the name
503 @node Scheme procedures
504 @subsection Scheme procedures
506 Scheme procedures are executable scheme expressions that return a
507 value resulting from their execution. They can also manipulate
508 variables defined outside of the procedure.
511 * Defining procedures::
516 @node Defining procedures
517 @unnumberedsubsubsec Defining procedures
519 Procedures are defined in Scheme with define
522 (define (function-name arg1 arg2 ... argn)
523 scheme-expression-that-gives-a-return-value)
526 For example, we could define a procedure to calculate the average:
529 guile> (define (average x y) (/ (+ x y) 2))
531 #<procedure average (x y)>
534 Once a procedure is defined, it is called by putting the procedure
535 name and the arguments in a list. For example, we can calculate
536 the average of 3 and 12:
539 guile> (average 3 12)
544 @unnumberedsubsubsec Predicates
546 Scheme procedures that return boolean values are often called
547 @emph{predicates}. By convention (but not necessity), predicate names
548 typically end in a question mark:
551 guile> (define (less-than-ten? x) (< x 10))
552 guile> (less-than-ten? 9)
554 guile> (less-than-ten? 15)
559 @unnumberedsubsubsec Return values
561 Scheme procedures always return a return value, which is the value
562 of the last expression executed in the procedure. The return
563 value can be any valid Scheme value, including a complex data
564 structure or a procedure.
566 Sometimes the user would like to have multiple Scheme expressions in
567 a procedure. There are two ways that multiple expressions can be
568 combined. The first is the @code{begin} procedure, which allows
569 multiple expressions to be evaluated, and returns the value of
573 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
577 The second way to combine multiple expressions is in a @code{let} block.
578 In a let block, a series of bindings are created, and then a sequence
579 of expressions that can include those bindings is evaluated. The
580 return value of the let block is the return value of the last
581 statement in the let block:
584 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
585 @dots{} (+ (* x y) (/ z x)))
589 @node Scheme conditionals
590 @subsection Scheme conditionals
598 @unnumberedsubsubsec if
600 Scheme has an @code{if} procedure:
603 (if test-expression true-expression false-expression)
606 @var{test-expression} is an expression that returns a boolean
607 value. If @var{test-expression} returns @code{#t}, the if
608 procedure returns the value of @var{true-expression}, otherwise
609 it returns the value of @var{false-expression}.
614 guile> (if (> a b) "a is greater than b" "a is not greater than b")
615 "a is not greater than b"
619 @unnumberedsubsubsec cond
621 Another conditional procedure in scheme is @code{cond}:
624 (cond (test-expression-1 result-expression-sequence-1)
625 (test-expression-2 result-expression-sequence-2)
627 (test-expression-n result-expression-sequence-n))
635 guile> (cond ((< a b) "a is less than b")
636 ... ((= a b) "a equals b")
637 ... ((> a b) "a is greater than b"))
641 @node Scheme in LilyPond
642 @section Scheme in LilyPond
646 * LilyPond Scheme syntax::
647 * LilyPond variables::
648 * Input variables and Scheme::
649 * Importing Scheme in LilyPond::
650 * Object properties::
651 * LilyPond compound variables::
652 * Internal music representation::
655 @node LilyPond Scheme syntax
656 @subsection LilyPond Scheme syntax
660 The Guile interpreter is part of LilyPond, which means that
661 Scheme can be included in LilyPond input files. There are several
662 methods for including Scheme in LilyPond.
664 The simplest way is to use a hash mark@tie{}@code{#} before a Scheme
667 Now LilyPond's input is structured into tokens and expressions, much
668 like human language is structured into words and sentences. LilyPond
669 has a lexer that recognizes tokens (literal numbers, strings, Scheme
670 elements, pitches and so on), and a parser that understands the syntax,
671 @rcontrib{LilyPond grammar}. Once it knows that a particular syntax rule
672 applies, it executes actions associated with it.
674 The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
675 for this system. Once the lexer sees a hash mark, it calls the Scheme
676 reader to read one full Scheme expression (this can be an identifier, an
677 expression enclosed in parentheses, or several other things). After the
678 Scheme expression is read, it is stored away as the value for an
679 @code{SCM_TOKEN} in the grammar. Once the parser knows how to make use
680 of this token, it calls Guile for evaluating the Scheme expression.
681 Since the parser usually requires a bit of lookahead from the lexer to
682 make its parsing decisions, this separation of reading and evaluation
683 between lexer and parser is exactly what is needed to keep the execution
684 of LilyPond and Scheme expressions in sync. For this reason, you should
685 use the hash mark@tie{}@code{#} for calling Scheme whenever this is
688 Another way to call the Scheme interpreter from LilyPond is the use of
689 dollar@tie{}@code{$} instead of a hash mark for introducing Scheme
690 expressions. In this case, LilyPond evaluates the code right after the
691 lexer has read it. It checks the resulting type of the Scheme
692 expression and then picks a token type (one of several
693 @code{xxx_IDENTIFIER} in the syntax) for it. It creates a @emph{copy}
694 of the value and uses that for the value of the token. If the value of
695 the expression is void (Guile's value of @code{*unspecified*}), nothing
696 at all is passed to the parser.
698 This is, in fact, exactly the same mechanism that LilyPond employs when
699 you call any variable or music function by name, as @code{\name}, with
700 the only difference that the name is determined by the LilyPond lexer
701 without consulting the Scheme reader, and thus only variable names
702 consistent with the current LilyPond mode are accepted.
704 The immediate action of @code{$} can lead to surprises, see
705 @ref{Importing Scheme in LilyPond}. Using @code{#} where the
706 parser supports it is usually preferable. Inside of music expressions,
707 expressions created using @code{#} @emph{are} interpreted as
708 music. However, they are @emph{not} copied before use. If they are
709 part of some structure that might still get used, you may need to use
710 @code{ly:music-deep-copy} explicitly.
714 There are also @q{list splicing} operators @code{$@@} and @code{#@@}
715 that insert all elements of a list in the surrounding context.
717 Now let's take a look at some actual Scheme code. Scheme procedures can
718 be defined in LilyPond input files:
721 #(define (average a b c) (/ (+ a b c) 3))
724 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
725 be used within Scheme code, even in a LilyPond input file, because
726 the Guile interpreter, not the LilyPond lexer, is reading
727 the Scheme expression. Comments in Guile Scheme are entered
731 ; this is a single-line comment
734 This a (non-nestable) Guile-style block comment
735 But these are rarely used by Schemers and never in
740 For the rest of this section, we will assume that the data is entered
741 in a music file, so we add a @code{#} at the beginning of each Scheme
744 All of the top-level Scheme expressions in a LilyPond input file can
745 be combined into a single Scheme expression by use of the
746 @code{begin} statement:
755 @node LilyPond variables
756 @subsection LilyPond variables
758 LilyPond variables are stored internally in the form of Scheme
772 This means that LilyPond variables are available
773 for use in Scheme expressions. For example, we could use
776 twentyFour = #(* 2 twelve)
780 which would result in the number 24 being stored in the
781 LilyPond (and Scheme) variable @code{twentyFour}.
783 The usual way to refer to LilyPond variables is to call them using a
784 backslash, i.e., @code{\twentyFour} (see @ref{LilyPond Scheme syntax}).
785 Since this creates a copy of the value for most of LilyPond's internal
786 types, in particular music expressions, music functions don't usually
787 create copies of material they change. For this reason, music
788 expressions given with @code{#} should usually not contain material that
789 is not either created from scratch or explicitly copied rather than
792 @node Input variables and Scheme
793 @subsection Input variables and Scheme
795 The input format supports the notion of variables: in the following
796 example, a music expression is assigned to a variable with the name
800 traLaLa = @{ c'4 d'4 @}
805 There is also a form of scoping: in the following example, the
806 @code{\layout} block also contains a @code{traLaLa} variable, which is
807 independent of the outer @code{\traLaLa}.
810 traLaLa = @{ c'4 d'4 @}
811 \layout @{ traLaLa = 1.0 @}
815 In effect, each input file is a scope, and all @code{\header},
816 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
819 Both variables and scoping are implemented in the GUILE module system.
820 An anonymous Scheme module is attached to each scope. An assignment of
824 traLaLa = @{ c'4 d'4 @}
828 is internally converted to a Scheme definition:
831 (define traLaLa @var{Scheme value of `@code{@dots{}}'})
834 This means that LilyPond variables and Scheme variables may be freely
835 mixed. In the following example, a music fragment is stored in the
836 variable @code{traLaLa}, and duplicated using Scheme. The result is
837 imported in a @code{\score} block by means of a second variable
841 traLaLa = { c'4 d'4 }
843 #(define newLa (map ly:music-deep-copy
844 (list traLaLa traLaLa)))
846 (make-sequential-music newLa))
851 @c Due to parser lookahead
853 This is actually a rather interesting example. The assignment will only
854 take place after the parser has ascertained that nothing akin to
855 @code{\addlyrics} follows, so it needs to check what comes next. It
856 reads @code{#} and the following Scheme expression @emph{without}
857 evaluating it, so it can go ahead with the assignment, and
858 @emph{afterwards} execute the Scheme code without problem.
860 @node Importing Scheme in LilyPond
861 @subsection Importing Scheme in LilyPond
865 The above example shows how to @q{export} music expressions from the
866 input to the Scheme interpreter. The opposite is also possible. By
867 placing it after @code{$}, a Scheme
868 value is interpreted as if it were entered in LilyPond syntax.
869 Instead of defining @code{\twice}, the example above could also have
874 $(make-sequential-music newLa)
877 You can use @code{$} with a Scheme expression anywhere you could use
878 @code{\@var{name}} after having assigned the Scheme expression to a
879 variable @var{name}. This replacement happens in the @q{lexer}, so
880 LilyPond is not even aware of the difference.
882 One drawback, however, is that of timing. If we had been using @code{$}
883 instead of @code{#} for defining @code{newLa} in the above example, the
884 following Scheme definition would have failed because @code{traLaLa}
885 would not yet have been defined. For an explanation of this timing
886 problem, @ref{LilyPond Scheme syntax}.
890 A further convenience can be the @q{list splicing} operators @code{$@@}
891 and @code{#@@} for inserting the elements of a list in the surrounding
892 context. Using those, the last part of the example could have been
900 Here, every element of the list stored in @code{newLa} is taken in
901 sequence and inserted into the list, as if we had written
904 @{ #(first newLa) #(second newLa) @}
907 Now in all of these forms, the Scheme code is evaluated while the
908 input is still being consumed, either in the lexer or in the parser.
909 If you need it to be executed at a later point of time, check out
910 @ref{Void scheme functions}, or store it in a procedure:
914 (ly:set-option 'point-and-click #f))
923 Mixing Scheme and LilyPond variables is not possible with the
924 @option{--safe} option.
927 @node Object properties
928 @subsection Object properties
930 Object properties are stored in LilyPond in the form of alist-chains,
931 which are lists of alists. Properties are set by adding values at
932 the beginning of the property list. Properties are read by retrieving
933 values from the alists.
935 Setting a new value for a property requires assigning a value to
936 the alist with both a key and a value. The LilyPond syntax for doing
940 \override Stem.thickness = #2.6
943 This instruction adjusts the appearance of stems. An alist entry
944 @code{'(thickness . 2.6)} is added to the property list of the
946 object. @code{thickness} is measured relative to the thickness of
947 staff lines, so these stem lines will be @code{2.6} times the
948 width of staff lines. This makes stems almost twice as thick as their
949 normal size. To distinguish between variables defined in input files (like
950 @code{twentyFour} in the example above) and variables of internal
951 objects, we will call the latter @q{properties} and the former
952 @q{variables.} So, the stem object has a @code{thickness} property,
953 while @code{twentyFour} is a variable.
955 @cindex properties vs. variables
956 @cindex variables vs. properties
958 @c todo -- here we're getting interesting. We're now introducing
959 @c LilyPond variable types. I think this deserves a section all
962 @node LilyPond compound variables
963 @subsection LilyPond compound variables
974 @unnumberedsubsubsec Offsets
976 Two-dimensional offsets (X and Y coordinates) are stored as @emph{pairs}.
977 The @code{car} of the offset is the X coordinate, and the @code{cdr} is
981 \override TextScript.extra-offset = #'(1 . 2)
984 This assigns the pair @code{(1 . 2)} to the @code{extra-offset}
986 TextScript object. These numbers are measured in staff-spaces, so
987 this command moves the object 1 staff space to the right, and 2 spaces up.
989 Procedures for working with offsets are found in @file{scm/lily-library.scm}.
992 @unnumberedsubsubsec Fractions
994 Fractions as used by LilyPond are again stored as @emph{pairs}, this
995 time of unsigned integers. While Scheme can represent rational numbers
996 as a native type, musically @samp{2/4} and @samp{1/2} are not the same,
997 and we need to be able to distinguish between them. Similarly there are
998 no negative @q{fractions} in LilyPond's mind. So @code{2/4} in LilyPond
999 means @code{(2 . 4)} in Scheme, and @code{#2/4} in LilyPond means
1000 @code{1/2} in Scheme.
1003 @unnumberedsubsubsec Extents
1005 Pairs are also used to store intervals, which represent a range of numbers
1006 from the minimum (the @code{car}) to the maximum (the @code{cdr}).
1007 Intervals are used to store the X- and Y- extents of printable objects.
1008 For X extents, the @code{car} is the left hand X coordinate, and the
1009 @code{cdr} is the right hand X coordinate. For Y extents, the @code{car}
1010 is the bottom coordinate, and the @code{cdr} is the top coordinate.
1012 Procedures for working with intervals are found in
1013 @file{scm/lily-library.scm}. These procedures should be used when possible
1014 to ensure consistency of code.
1016 @node Property alists
1017 @unnumberedsubsubsec Property alists
1019 A property alist is a LilyPond data structure that is an alist whose
1020 keys are properties and whose values are Scheme expressions that give
1021 the desired value for the property.
1023 LilyPond properties are Scheme symbols, such as @code{'thickness}.
1026 @unnumberedsubsubsec Alist chains
1028 An alist chain is a list containing property alists.
1030 The set of all properties that will apply to a grob is typically
1031 stored as an alist chain. In order to find the value for a particular
1032 property that a grob should have, each alist in the chain is searched in
1033 order, looking for an entry containing the property key. The first alist
1034 entry found is returned, and the value is the property value.
1036 The Scheme procedure @code{chain-assoc-get} is normally used to get
1037 grob property values.
1039 @node Internal music representation
1040 @subsection Internal music representation
1042 Internally, music is represented as a Scheme list. The list contains
1043 various elements that affect the printed output. Parsing is the process
1044 of converting music from the LilyPond input representation to the
1045 internal Scheme representation.
1047 When a music expression is parsed, it is converted into a set of
1048 Scheme music objects. The defining property of a music object is that
1049 it takes up time. The time it takes up is called its @emph{duration}.
1050 Durations are expressed as a rational number that measures the length
1051 of the music object in whole notes.
1053 A music object has three kinds of types:
1056 music name: Each music expression has a name. For example, a note
1057 leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
1058 a @rinternals{SimultaneousMusic}. A list of all expressions
1059 available is in the Internals Reference manual, under
1060 @rinternals{Music expressions}.
1063 @q{type} or interface: Each music name has several @q{types} or
1064 interfaces, for example, a note is an @code{event}, but it is also a
1065 @code{note-event}, a @code{rhythmic-event}, and a
1066 @code{melodic-event}. All classes of music are listed in the
1067 Internals Reference, under
1068 @rinternals{Music classes}.
1071 C++ object: Each music object is represented by an object of the C++
1075 The actual information of a music expression is stored in properties.
1076 For example, a @rinternals{NoteEvent} has @code{pitch} and
1077 @code{duration} properties that store the pitch and duration of that
1078 note. A list of all properties available can be found in the
1079 Internals Reference, under @rinternals{Music properties}.
1081 A compound music expression is a music object that contains other
1082 music objects in its properties. A list of objects can be stored in
1083 the @code{elements} property of a music object, or a single @q{child}
1084 music object in the @code{element} property. For example,
1085 @rinternals{SequentialMusic} has its children in @code{elements},
1086 and @rinternals{GraceMusic} has its single argument in
1087 @code{element}. The body of a repeat is stored in the @code{element}
1088 property of @rinternals{RepeatedMusic}, and the alternatives in
1091 @node Building complicated functions
1092 @section Building complicated functions
1094 This section explains how to gather the information necessary
1095 to create complicated music functions.
1098 * Displaying music expressions::
1099 * Music properties::
1100 * Doubling a note with slurs (example)::
1101 * Adding articulation to notes (example)::
1104 @node Displaying music expressions
1105 @subsection Displaying music expressions
1107 @cindex internal storage
1108 @cindex displaying music expressions
1109 @cindex internal representation, displaying
1110 @cindex displayMusic
1111 @funindex \displayMusic
1113 When writing a music function it is often instructive to inspect how
1114 a music expression is stored internally. This can be done with the
1115 music function @code{\displayMusic}.
1119 \displayMusic @{ c'4\f @}
1134 'AbsoluteDynamicEvent
1138 (ly:make-duration 2 0 1/1)
1140 (ly:make-pitch 0 0 0))))
1143 By default, LilyPond will print these messages to the console along
1144 with all the other messages. To split up these messages and save
1145 the results of @code{\display@{STUFF@}}, you can specify an optional
1150 \displayMusic #(open-output-file "display.txt") @{ c'4\f @}
1154 This will overwrite a previous output file whenever it is called; if you
1155 need to write more than one expression, you would use a variable for
1156 your port and reuse it:
1159 port = #(open-output-file "display.txt")
1160 \displayMusic \port @{ c'4\f @}
1161 \displayMusic \port @{ d'4 @}
1162 #(close-output-port port)
1166 Guile's manual describes ports in detail. Closing the port is actually
1167 only necessary if you need to read the file before LilyPond finishes; in
1168 the first example, we did not bother to do so.
1170 A bit of reformatting makes the above information easier to read:
1173 (make-music 'SequentialMusic
1175 (make-music 'NoteEvent
1176 'articulations (list
1177 (make-music 'AbsoluteDynamicEvent
1180 'duration (ly:make-duration 2 0 1/1)
1181 'pitch (ly:make-pitch 0 0 0))))
1184 A @code{@{ @dots{} @}} music sequence has the name
1185 @code{SequentialMusic}, and its inner expressions are stored as a list
1186 in its @code{'elements} property. A note is represented as a
1187 @code{NoteEvent} object (storing the duration and pitch properties) with
1188 attached information (in this case, an @code{AbsoluteDynamicEvent} with
1189 a @code{"f"} text property) stored in its @code{articulations} property.
1192 @code{\displayMusic} returns the music it displays, so it will get
1193 interpreted as well as displayed. To avoid interpretation, write
1194 @code{\void} before @code{\displayMusic}.
1196 @node Music properties
1197 @subsection Music properties
1200 TODO -- make sure we delineate between @emph{music} properties,
1201 @emph{context} properties, and @emph{layout} properties. These
1202 are potentially confusing.
1205 Let's look at an example:
1209 \displayMusic \someNote
1214 (ly:make-duration 2 0 1/1)
1216 (ly:make-pitch 0 0 0))
1219 The @code{NoteEvent} object is the representation of @code{someNote}.
1220 Straightforward. How about putting c' in a chord?
1224 \displayMusic \someNote
1232 (ly:make-duration 2 0 1/1)
1234 (ly:make-pitch 0 0 0))))
1237 Now the @code{NoteEvent} object is the first object of the
1238 @code{'elements} property of @code{someNote}.
1240 The @code{display-scheme-music} function is the function used by
1241 @code{\displayMusic} to display the Scheme representation of a music
1245 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1250 (ly:make-duration 2 0 1/1)
1252 (ly:make-pitch 0 0 0))
1255 Then the note pitch is accessed through the @code{'pitch} property
1256 of the @code{NoteEvent} object.
1259 #(display-scheme-music
1260 (ly:music-property (first (ly:music-property someNote 'elements))
1263 (ly:make-pitch 0 0 0)
1266 The note pitch can be changed by setting this @code{'pitch} property.
1268 @funindex \displayLilyMusic
1271 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1273 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
1274 \displayLilyMusic \someNote
1280 @node Doubling a note with slurs (example)
1281 @subsection Doubling a note with slurs (example)
1283 Suppose we want to create a function that translates input like
1284 @code{a} into @code{@{ a( a) @}}. We begin by examining the internal
1285 representation of the desired result.
1288 \displayMusic@{ a'( a') @}
1301 (ly:make-duration 2 0 1/1)
1303 (ly:make-pitch 0 5 0))
1312 (ly:make-duration 2 0 1/1)
1314 (ly:make-pitch 0 5 0))))
1317 The bad news is that the @code{SlurEvent} expressions
1318 must be added @q{inside} the note (in its @code{articulations}
1321 Now we examine the input.
1329 (ly:make-duration 2 0 1/1)
1331 (ly:make-pitch 0 5 0))))
1334 So in our function, we need to clone this expression (so that we have
1335 two notes to build the sequence), add a @code{SlurEvent} to the
1336 @code{'articulations} property of each one, and finally make a
1337 @code{SequentialMusic} with the two @code{NoteEvent} elements. For adding to a
1338 property, it is useful to know that an unset property is read out as
1339 @code{'()}, the empty list, so no special checks are required before we
1340 put another element at the front of the @code{articulations} property.
1343 doubleSlur = #(define-music-function (note) (ly:music?)
1344 "Return: @{ note ( note ) @}.
1345 `note' is supposed to be a single note."
1346 (let ((note2 (ly:music-deep-copy note)))
1347 (set! (ly:music-property note 'articulations)
1348 (cons (make-music 'SlurEvent 'span-direction -1)
1349 (ly:music-property note 'articulations)))
1350 (set! (ly:music-property note2 'articulations)
1351 (cons (make-music 'SlurEvent 'span-direction 1)
1352 (ly:music-property note2 'articulations)))
1353 (make-music 'SequentialMusic 'elements (list note note2))))
1357 @node Adding articulation to notes (example)
1358 @subsection Adding articulation to notes (example)
1360 The easy way to add articulation to notes is to merge two music
1361 expressions into one context.
1362 However, suppose that we want to write a music function that does this.
1363 This will have the additional advantage that we can use that music
1364 function to add an articulation (like a fingering instruction) to a
1365 single note inside of a chord which is not possible if we just merge
1368 A @code{$variable} inside the @code{#@{@dots{}#@}} notation is like
1369 a regular @code{\variable} in classical LilyPond notation. We
1377 will not work in LilyPond. We could avoid this problem by attaching
1378 the articulation to an empty chord,
1381 @{ << \music <> -. -> >> @}
1385 but for the sake of this example, we will learn how to do this in
1386 Scheme. We begin by examining our input and desired output.
1395 (ly:make-duration 2 0 1/1)
1397 (ly:make-pitch -1 0 0))))
1410 (ly:make-duration 2 0 1/1)
1412 (ly:make-pitch -1 0 0))
1415 We see that a note (@code{c4}) is represented as an @code{NoteEvent}
1416 expression. To add an accent articulation, an @code{ArticulationEvent}
1417 expression must be added to the @code{articulations} property of the
1418 @code{NoteEvent} expression.
1420 To build this function, we begin with
1423 (define (add-accent note-event)
1424 "Add an accent ArticulationEvent to the articulations of `note-event',
1425 which is supposed to be a NoteEvent expression."
1426 (set! (ly:music-property note-event 'articulations)
1427 (cons (make-music 'ArticulationEvent
1428 'articulation-type "accent")
1429 (ly:music-property note-event 'articulations)))
1433 The first line is the way to define a function in Scheme: the function
1434 name is @code{add-accent}, and has one variable called
1435 @code{note-event}. In Scheme, the type of variable is often clear
1436 from its name. (this is good practice in other programming languages,
1440 "Add an accent@dots{}"
1444 is a description of what the function does. This is not strictly
1445 necessary, but just like clear variable names, it is good practice.
1447 You may wonder why we modify the note event directly instead of working
1448 on a copy (@code{ly:music-deep-copy} can be used for that). The reason
1449 is a silent contract: music functions are allowed to modify their
1450 arguments: they are either generated from scratch (like user input) or
1451 are already copied (referencing a music variable with @samp{\name} or
1452 music from immediate Scheme expressions @samp{$(@dots{})} provides a
1453 copy). Since it would be inefficient to create unnecessary copies, the
1454 return value from a music function is @emph{not} copied. So to heed
1455 that contract, you must not use any arguments more than once, and
1456 returning it counts as one use.
1458 In an earlier example, we constructed music by repeating a given music
1459 argument. In that case, at least one repetition had to be a copy of its
1460 own. If it weren't, strange things may happen. For example, if you use
1461 @code{\relative} or @code{\transpose} on the resulting music containing
1462 the same elements multiple times, those will be subjected to
1463 relativation or transposition multiple times. If you assign them to a
1464 music variable, the curse is broken since referencing @samp{\name} will
1465 again create a copy which does not retain the identity of the repeated
1468 Now while the above function is not a music function, it will normally
1469 be used within music functions. So it makes sense to heed the same
1470 contract we use for music functions: the input may be modified for
1471 producing the output, and the caller is responsible for creating copies
1472 if it still needs the unchanged argument itself. If you take a look at
1473 LilyPond's own functions like @code{music-map}, you'll find that they
1474 stick with the same principles.
1476 Where were we? Now we have a @code{note-event} we may modify, not
1477 because of using @code{ly:music-deep-copy} but because of a long-winded
1478 explanation. We add the accent to its @code{'articulations} list
1482 (set! place new-value)
1485 Here, what we want to set (the @q{place}) is the @code{'articulations}
1486 property of @code{note-event} expression.
1489 (ly:music-property note-event 'articulations)
1492 @code{ly:music-property} is the function used to access music properties
1493 (the @code{'articulations}, @code{'duration}, @code{'pitch}, etc, that we
1494 see in the @code{\displayMusic} output above). The new value is the
1495 former @code{'articulations} property, with an extra item: the
1496 @code{ArticulationEvent} expression, which we copy from the
1497 @code{\displayMusic} output,
1500 (cons (make-music 'ArticulationEvent
1501 'articulation-type "accent")
1502 (ly:music-property result-event-chord 'articulations))
1505 @code{cons} is used to add an element to the front of a list without
1506 modifying the original list. This is what we want: the same list as
1507 before, plus the new @code{ArticulationEvent} expression. The order
1508 inside the @code{'articulations} property is not important here.
1510 Finally, once we have added the accent articulation to its
1511 @code{articulations} property, we can return @code{note-event}, hence
1512 the last line of the function.
1514 Now we transform the @code{add-accent} function into a music function (a
1515 matter of some syntactic sugar and a declaration of the type of its
1519 addAccent = #(define-music-function (note-event)
1521 "Add an accent ArticulationEvent to the articulations of `note-event',
1522 which is supposed to be a NoteEvent expression."
1523 (set! (ly:music-property note-event 'articulations)
1524 (cons (make-music 'ArticulationEvent
1525 'articulation-type "accent")
1526 (ly:music-property note-event 'articulations)))
1530 We then verify that this music function works correctly:
1533 \displayMusic \addAccent c4
1542 * Tweaking with Scheme::
1545 @c @nod e Tweaking with Scheme
1546 @c @sectio n Tweaking with Scheme
1548 We have seen how LilyPond output can be heavily modified using
1550 @code{\override TextScript.extra-offset = ( 1 . -1)}. But
1551 we have even more power if we use Scheme. For a full explanation
1552 of this, see the @ref{Scheme tutorial}, and
1553 @ref{Interfaces for programmers}.
1555 We can use Scheme to simply @code{\override} commands,
1557 TODO Find a simple example
1558 @c This isn't a valid example with skylining
1559 @c It works fine without padText -td
1563 @lilypond[quote,verbatim,ragged-right]
1564 padText = #(define-music-function (padding) (number?)
1566 \once \override TextScript.padding = #padding
1570 c'''4^"piu mosso" b a b
1572 c4^"piu mosso" d e f
1574 c4^"piu mosso" fis a g
1580 We can use it to create new commands:
1582 @c Check this is a valid example with skylining
1583 @c It is - 'padding still works
1586 @lilypond[quote,verbatim,ragged-right]
1587 tempoPadded = #(define-music-function (padding tempotext)
1590 \once \override Score.MetronomeMark.padding = #padding
1591 \tempo \markup { \bold #tempotext }
1595 \tempo \markup { "Low tempo" }
1597 \tempoPadded #4.0 "High tempo"
1603 Even music expressions can be passed in:
1605 @lilypond[quote,verbatim,ragged-right]
1606 pattern = #(define-music-function (x y) (ly:music? ly:music?)
1613 \pattern {d16 dis} { ais16-> b\p }