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/shr/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 Scheme.
90 @node Scheme variables
91 @subsection Scheme variables
93 Scheme variables can have any valid scheme value, including a Scheme
96 Scheme variables are created with @code{define}:
103 Scheme variables can be evaluated at the guile prompt simply by
104 typing the variable name:
112 Scheme variables can be printed on the display by using the display function:
120 Note that both the value @code{2} and the guile prompt @code{guile}
121 showed up on the same line. This can be avoided by calling the
122 newline procedure or displaying a newline character.
125 guile> (display a)(newline)
127 guile> (display a)(display "\n")
132 Once a variable has been created, its value can be changed with @code{set!}:
135 guile> (set! a 12345)
141 @node Scheme simple data types
142 @subsection Scheme simple data types
144 The most basic concept in a language is data typing: numbers, character
145 strings, lists, etc. Here is a list of simple Scheme data types that are
146 often used with LilyPond.
150 Boolean values are True or False. The Scheme for True is @code{#t}
151 and False is @code{#f}.
156 Numbers are entered in the standard fashion,
157 @code{1} is the (integer) number one, while @w{@code{-1.5}} is a
158 floating point number (a non-integer number).
161 Strings are enclosed in double quotes:
167 Strings may span several lines:
176 and the newline characters at the end of each line will be included
179 Newline characters can also be added by including @code{\n} in the
183 "this\nis a\nmultiline string"
187 Quotation marks and backslashes are added to strings
188 by preceding them with a backslash.
189 The string @code{\a said "b"} is entered as
197 There are additional Scheme data types that are not discussed here.
198 For a complete listing see the Guile reference guide,
199 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
201 @node Scheme compound data types
202 @subsection Scheme compound data types
204 There are also compound data types in Scheme. The types commonly used in
205 LilyPond programming include pairs, lists, alists, and hash tables.
209 The foundational compound data type of Scheme is the @code{pair}. As
210 might be expected from its name, a pair is two values glued together.
211 The operator used to form a pair is called @code{cons}.
219 Note that the pair is displayed as two items surrounded by
220 parentheses and separated by whitespace, a period (@code{.}), and
221 more whitespace. The period is @emph{not} a decimal point, but
222 rather an indicator of the pair.
224 Pairs can also be entered as literal values by preceding them with
225 a single quote character.
233 The two elements of a pair may be any valid Scheme value:
238 guile> '("blah-blah" . 3.1415926535)
239 ("blah-blah" . 3.1415926535)
243 The first and second elements of the pair can be accessed by the
244 Scheme procedures @code{car} and @code{cdr}, respectively.
247 guile> (define mypair (cons 123 "hello there")
258 Note: @code{cdr} is pronounced "could-er", according Sussman and
260 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
264 A very common Scheme data structure is the @emph{list}. Formally, a
265 list is defined as either the empty list (represented as @code{'()},
266 or a pair whose @code{cdr} is a list.
268 There are many ways of creating lists. Perhaps the most common is
269 with the @code{list} procedure:
272 guile> (list 1 2 3 "abc" 17.5)
276 As can be seen, a list is displayed in the form of individual elements
277 separated by whitespace and enclosed in parentheses. Unlike a pair,
278 there is no period between the elements.
280 A list can also be entered as a literal list by enclosing its
281 elements in parentheses, and adding a quote:
284 guile> '(17 23 "foo" "bar" "bazzle")
285 (17 23 "foo" "bar" "bazzle")
288 Lists are a central part of Scheme. In, fact, Scheme is considered
289 a dialect of lisp, where @q{lisp} is an abbreviation for
290 @q{List Processing}. Scheme expressions are all lists.
292 @subheading Association lists (alists)
294 A special type of list is an @emph{association list} or @emph{alist}.
295 An alist is used to store data for easy retrieval.
297 Alists are lists whose elements are pairs. The @code{car} of each
298 element is called the @emph{key}, and the @code{cdr} of each element
299 is called the @emph{value}. The Scheme procedure @code{assoc} is
300 used to retrieve an entry from the alist, and @code{cdr} is used to
304 guile> (define my-alist '((1 . "A") (2 . "B") (3 . "C")))
306 ((1 . "A") (2 . "B") (3 . "C"))
307 guile> (assoc 2 my-alist)
309 guile> (cdr (assoc 2 my-alist))
314 Alists are widely used in LilyPond to store properties and other data.
316 @subheading Hash tables
318 A data structure that is used occasionally in LilyPond. A hash table
319 is similar to an array, but the indexes to the array can be any type
320 of Scheme value, not just integers.
322 Hash tables are more efficient than alists if there is a lot of data
323 to store and the data changes very infrequently.
325 The syntax to create hash tables is a bit complex, but you
326 can see examples of it in the LilyPond source.
329 guile> (define h (make-hash-table 10))
332 guile> (hashq-set! h 'key1 "val1")
334 guile> (hashq-set! h 'key2 "val2")
336 guile> (hashq-set! h 3 "val3")
340 Values are retrieved from hash tables with @code{hashq-ref}.
343 guile> (hashq-ref h 3)
345 guile> (hashq-ref h 'key2)
350 Keys and values are retrieved as a pair with @code{hashq-get-handle}.
351 This is a preferred way, because it will return @code{#f} if a key is
355 guile> (hashq-get-handle h 'key1)
357 guile> (hashq-get-handle h 'frob)
362 @node Calculations in Scheme
363 @subsection Calculations in Scheme
366 We have been using lists all along. A calculation, like @code{(+ 1 2)}
367 is also a list (containing the symbol @code{+} and the numbers 1
368 and@tie{}2). Normally lists are interpreted as calculations, and the
369 Scheme interpreter substitutes the outcome of the calculation. To enter a
370 list, we stop the evaluation. This is done by quoting the list with a
371 quote @code{'} symbol. So, for calculations do not use a quote.
373 Inside a quoted list or pair, there is no need to quote anymore. The
374 following is a pair of symbols, a list of symbols and a list of lists
379 #'(staff clef key-signature)
384 Scheme can be used to do calculations. It uses @emph{prefix}
385 syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
386 traditional @math{1+2}.
393 Calculations may be nested; the result of a function may
394 be used for another calculation.
401 These calculations are examples of evaluations; an expression like
402 @code{(* 3 4)} is replaced by its value @code{12}.
404 Scheme calculations are sensitive to the differences between integers
405 and non-integers. Integer calculations are exact, while non-integers
406 are calculated to the appropriate limits of precision:
415 When the scheme interpreter encounters an expression that is a list,
416 the first element of the list is treated as a procedure to be
417 evaluated with the arguments of the remainder of the list. Therefore,
418 all operators in Scheme are prefix operators.
420 If the first element of a Scheme expression that is a list passed to
421 the interpreter is @emph{not} an operator or procedure, an error will
431 <unnamed port>:52:1: In expression (1 2 3):
432 <unnamed port>:52:1: Wrong type to apply: 1
437 Here you can see that the interpreter was trying to treat 1 as an
438 operator or procedure, and it couldn't. Hence the error is "Wrong
441 Therefore, to create a list we need to use the list operator, or to
442 quote the list so that the interpreter will not try to evaluate it.
452 This is an error that can appear as you are working with Scheme in LilyPond.
455 The same assignment can be done in completely in Scheme as well,
458 #(define twentyFour (* 2 twelve))
461 @c this next section is confusing -- need to rewrite
463 The @emph{name} of a variable is also an expression, similar to a
464 number or a string. It is entered as
471 @cindex quoting in Scheme
473 The quote mark @code{'} prevents the Scheme interpreter from substituting
474 @code{24} for the @code{twentyFour}. Instead, we get the name
479 @node Scheme procedures
480 @subsection Scheme procedures
482 Scheme procedures are executable scheme expressions that return a
483 value resulting from their execution. They can also manipulate
484 variables defined outside of the procedure.
486 @subheading Defining procedures
488 Procedures are defined in Scheme with define
491 (define (function-name arg1 arg2 ... argn)
492 scheme-expression-that-gives-a-return-value)
495 For example, we could define a procedure to calculate the average:
498 guile> (define (average x y) (/ (+ x y) 2))
500 #<procedure average (x y)>
503 Once a procedure is defined, it is called by putting the procedure
504 name and the arguments in a list. For example, we can calculate
505 the average of 3 and 12:
508 guile> (average 3 12)
512 @subheading Predicates
514 Scheme procedures that return boolean values are often called
515 @emph{predicates}. By convention (but not necessity), predicate names
516 typically end in a question mark:
519 guile> (define (less-than-ten? x) (< x 10))
520 guile> (less-than-ten? 9)
522 guile> (less-than-ten? 15)
526 @subheading Return values
528 Scheme procedures always return a return value, which is the value
529 of the last expression executed in the procedure. The return
530 value can be any valid Scheme value, including a complex data
531 structure or a procedure.
533 Sometimes the user would like to have multiple Scheme expressions in
534 a procedure. There are two ways that multiple expressions can be
535 combined. The first is the @code{begin} procedure, which allows
536 multiple expressions to be evaluated, and returns the value of
540 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
544 The second way to combine multiple expressions is in a @code{let} block.
545 In a let block, a series of bindings are created, and then a sequence
546 of expressions that can include those bindings is evaluated. The
547 return value of the let block is the return value of the last
548 statement in the let block:
551 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
552 ... (+ (* x y) (/ z x)))
556 @node Scheme conditionals
557 @subsection Scheme conditionals
561 Scheme has an @code{if} procedure:
564 (if test-expression true-expression false-expression)
567 @var{test-expression} is an expression that returns a boolean
568 value. If @var{test-expression} returns @code{#t}, the if
569 procedure returns the value of @var{true-expression}, otherwise
570 it returns the value of @var{false-expression}.
575 guile> (if (> a b) "a is greater than b" "a is not greater than b")
576 "a is not greater than b"
581 Another conditional procedure in scheme is @code{cond}:
584 (cond (test-expression-1 result-expression-sequence-1)
585 (test-expression-2 result-expression-sequence-2)
587 (test-expression-n result-expression-sequence-n))
595 guile> (cond ((< a b) "a is less than b")
596 ... ((= a b) "a equals b")
597 ... ((> a b) "a is greater than b"))
601 @node Scheme in LilyPond
602 @section Scheme in LilyPond
606 * LilyPond Scheme syntax::
607 * LilyPond variables::
608 * Input variables and Scheme::
609 * Object properties::
610 * LilyPond compound variables::
611 * Internal music representation::
614 @node LilyPond Scheme syntax
615 @subsection LilyPond Scheme syntax
619 The Guile interpreter is part of LilyPond, which means that
620 Scheme can be included in LilyPond input files. There are several
621 methods for including Scheme in LilyPond.
623 The simplest way is to use a hash mark@tie{}@code{#} before a Scheme
626 Now LilyPond's input is structured into tokens and expressions, much
627 like human language is structured into words and sentences. LilyPond
628 has a lexer that recognizes tokens (literal numbers, strings, Scheme
629 elements, pitches and so on), and a parser that understands the syntax,
630 @ruser{LilyPond grammar}. Once it knows that a particular syntax rule
631 applies, it executes actions associated with it.
633 The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
634 for this system. Once the lexer sees a hash mark, it calls the Scheme
635 reader to read one full Scheme expression (this can be an identifier, an
636 expression enclosed in parentheses, or several other things). After the
637 Scheme expression is read, it is stored away as the value for an
638 @code{SCM_TOKEN} in the grammar. Once the parser knows how to make use
639 of this token, it calls Guile for evaluating the Scheme expression.
640 Since the parser usually requires a bit of lookahead from the lexer to
641 make its parsing decisions, this separation of reading and evaluation
642 between lexer and parser is exactly what is needed to keep the execution
643 of LilyPond and Scheme expressions in sync. For this reason, you should
644 use the hash mark@tie{}@code{#} for calling Scheme whenever this is
647 Another way to call the Scheme interpreter from LilyPond is the use of
648 dollar@tie{}@code{$} instead of a hash mark for introducing Scheme
649 expressions. In this case, Lilypond evaluates the code right after the
650 lexer has read it. It checks the resulting type of the Scheme
651 expression and then picks a token type (one of several
652 @code{xxx_IDENTIFIER} in the syntax) for it. It creates a @emph{copy}
653 of the value and uses that for the value of the token. If the value of
654 the expression is void (Guile's value of @code{*unspecified*}), nothing
655 at all is passed to the parser.
657 This is, in fact, exactly the same mechanism that Lilypond employs when
658 you call any variable or music function by name, as @code{\name}, with
659 the only difference that its end is determined by the Lilypond lexer
660 without consulting the Scheme reader, and thus only variable names
661 consistent with the current Lilypond mode are accepted.
663 The immediate action of @code{$} can lead to surprises, @ref{Input
664 variables and Scheme}. Using @code{#} where the parser supports it is
667 Now let's take a look at some actual Scheme code. Scheme procedures can
668 be defined in LilyPond input files:
671 #(define (average a b c) (/ (+ a b c) 3))
674 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
675 be used within Scheme code, even in a LilyPond input file, because
676 the Guile interpreter, not the LilyPond lexer, is reading
677 the Scheme expression. Comments in Guile Scheme are entered
681 ; this is a single-line comment
684 This a (non-nestable) Guile-style block comment
685 But these are rarely used by Schemers and never in
690 For the rest of this section, we will assume that the data is entered
691 in a music file, so we add@tie{}@code{#}s at the beginning of each Scheme
694 All of the top-level Scheme expressions in a LilyPond input file can
695 be combined into a single Scheme expression by the use of the
696 @code{begin} statement:
705 @node LilyPond variables
706 @subsection LilyPond variables
708 LilyPond variables are stored internally in the form of Scheme
722 This means that LilyPond variables are available
723 for use in Scheme expressions. For example, we could use
726 twentyFour = #(* 2 twelve)
730 which would result in the number 24 being stored in the
731 LilyPond (and Scheme) variable @code{twentyFour}.
733 The usual way to refer to Lilypond variables, @ref{LilyPond Scheme
734 syntax}, is to call them using a backslash, i.e., @code{\twentyFour}.
735 Since this creates a copy of the value for most of LilyPond's internal
736 types, in particular music expressions, music functions don't usually
737 create copies of material they change. For this reason, music
738 expressions given with @code{#} should usually not contain material that
739 is not either created from scratch or explicitly copied rather than
742 @node Input variables and Scheme
743 @subsection Input variables and Scheme
745 The input format supports the notion of variables: in the following
746 example, a music expression is assigned to a variable with the name
750 traLaLa = @{ c'4 d'4 @}
755 There is also a form of scoping: in the following example, the
756 @code{\layout} block also contains a @code{traLaLa} variable, which is
757 independent of the outer @code{\traLaLa}.
760 traLaLa = @{ c'4 d'4 @}
761 \layout @{ traLaLa = 1.0 @}
765 In effect, each input file is a scope, and all @code{\header},
766 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
769 Both variables and scoping are implemented in the GUILE module system.
770 An anonymous Scheme module is attached to each scope. An assignment of
774 traLaLa = @{ c'4 d'4 @}
778 is internally converted to a Scheme definition:
781 (define traLaLa @var{Scheme value of `@code{... }'})
784 This means that LilyPond variables and Scheme variables may be freely
785 mixed. In the following example, a music fragment is stored in the
786 variable @code{traLaLa}, and duplicated using Scheme. The result is
787 imported in a @code{\score} block by means of a second variable
791 traLaLa = { c'4 d'4 }
793 #(define newLa (map ly:music-deep-copy
794 (list traLaLa traLaLa)))
796 (make-sequential-music newLa))
801 @c Due to parser lookahead
803 This is actually a rather interesting example. The assignment will only
804 take place after the parser has ascertained that nothing akin to
805 @code{\addlyrics} follows, so it needs to check what comes next. It
806 reads @code{#} and the following Scheme expression @emph{without}
807 evaluating it, so it can go ahead with the assignment, and
808 @emph{afterwards} execute the Scheme code without problem.
810 The above example shows how to @q{export} music expressions from the
811 input to the Scheme interpreter. The opposite is also possible. By
812 placing it after @code{$}, a Scheme
813 value is interpreted as if it were entered in LilyPond syntax.
814 Instead of defining @code{\twice}, the example above could also have
819 @{ $(make-sequential-music (list newLa)) @}
822 You can use @code{$} with a Scheme expression anywhere you could use
823 @code{\@var{name}} after having assigned the Scheme expression to a
824 variable @var{name}. This replacement happens in the @q{lexer}, so
825 Lilypond is not even aware of the difference.
827 One drawback, however, is that of timing. If we had been using @code{$}
828 instead of @code{#} for defining @code{newLa} in the above example, the
829 following Scheme definition would have failed because @code{traLaLa}
830 would not yet have been defined. For an explanation of this timing
831 problem, @ref{LilyPond Scheme syntax}.
833 In any case, evaluation of Scheme code happens in the parser at latest.
834 If you need it to be executed at a later point of time, @ref{Void scheme
835 functions}, or store it in a macro:
839 (ly:set-option 'point-and-click #f))
848 Mixing Scheme and LilyPond variables is not possible with the
849 @option{--safe} option.
852 @node Object properties
853 @subsection Object properties
855 Object properties are stored in LilyPond in the form of alist-chains,
856 which are lists of alists. Properties are set by adding values at
857 the beginning of the property list. Properties are read by retrieving
858 values from the alists.
860 Setting a new value for a property requires assigning a value to
861 the alist with both a key and a value. The LilyPond syntax for doing
865 \override Stem #'thickness = #2.6
868 This instruction adjusts the appearance of stems. An alist entry
869 @code{'(thickness . 2.6)} is added to the property list of the
871 object. @code{thickness} is measured relative to the thickness of
872 staff lines, so these stem lines will be @code{2.6} times the
873 width of staff lines. This makes stems almost twice as thick as their
874 normal size. To distinguish between variables defined in input files (like
875 @code{twentyFour} in the example above) and variables of internal
876 objects, we will call the latter @q{properties} and the former
877 @q{variables.} So, the stem object has a @code{thickness} property,
878 while @code{twentyFour} is a variable.
880 @cindex properties vs. variables
881 @cindex variables vs. properties
883 @c todo -- here we're getting interesting. We're now introducing
884 @c LilyPond variable types. I think this deserves a section all
887 @node LilyPond compound variables
888 @subsection LilyPond compound variables
892 Two-dimensional offsets (X and Y coordinates) are stored as @code{pairs}.
893 The @code{car} of the offset is the X coordinate, and the @code{cdr} is
897 \override TextScript #'extra-offset = #'(1 . 2)
900 This assigns the pair @code{(1 . 2)} to the @code{extra-offset}
902 TextScript object. These numbers are measured in staff-spaces, so
903 this command moves the object 1 staff space to the right, and 2 spaces up.
905 Procedures for working with offsets are found in @file{scm/lily-library.scm}.
909 Pairs are also used to store intervals, which represent a range of numbers
910 from the minimum (the @code{car}) to the maximum (the @code{cdr}).
911 Intervals are used to store the X- and Y- extents of printable objects.
912 For X extents, the @code{car} is the left hand X coordinate, and the
913 @code{cdr} is the right hand X coordinate. For Y extents, the @code{car}
914 is the bottom coordinate, and the @code{cdr} is the top coordinate.
916 Procedures for working with intervals are found in
917 @file{scm/lily-library.scm}. These procedures should be used when possible
918 to ensure consistency of code.
920 @subheading Property alists
922 A property alist is a LilyPond data structure that is an alist whose
923 keys are properties and whose values are Scheme expressions that give
924 the desired value for the property.
926 LilyPond properties are Scheme symbols, such as @code{'thickness}.
928 @subheading Alist chains
930 An alist chain is a list containing property alists.
932 The set of all properties that will apply to a grob is typically
933 stored as an alist chain. In order to find the value for a particular
934 property that a grob should have, each alist in the chain is searched in
935 order, looking for an entry containing the property key. The first alist
936 entry found is returned, and the value is the property value.
938 The Scheme procedure @code{chain-assoc-get} is normally used to get
939 grob property values.
941 @node Internal music representation
942 @subsection Internal music representation
944 Internally, music is represented as a Scheme list. The list contains
945 various elements that affect the printed output. Parsing is the process
946 of converting music from the LilyPond input representation to the
947 internal Scheme representation.
949 When a music expression is parsed, it is converted into a set of
950 Scheme music objects. The defining property of a music object is that
951 it takes up time. The time it takes up is called its @emph{duration}.
952 Durations are expressed as a rational number that measures the length
953 of the music object in whole notes.
955 A music object has three kinds of types:
958 music name: Each music expression has a name. For example, a note
959 leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
960 a @rinternals{SimultaneousMusic}. A list of all expressions
961 available is in the Internals Reference manual, under
962 @rinternals{Music expressions}.
965 @q{type} or interface: Each music name has several @q{types} or
966 interfaces, for example, a note is an @code{event}, but it is also a
967 @code{note-event}, a @code{rhythmic-event}, and a
968 @code{melodic-event}. All classes of music are listed in the
969 Internals Reference, under
970 @rinternals{Music classes}.
973 C++ object: Each music object is represented by an object of the C++
977 The actual information of a music expression is stored in properties.
978 For example, a @rinternals{NoteEvent} has @code{pitch} and
979 @code{duration} properties that store the pitch and duration of that
980 note. A list of all properties available can be found in the
981 Internals Reference, under @rinternals{Music properties}.
983 A compound music expression is a music object that contains other
984 music objects in its properties. A list of objects can be stored in
985 the @code{elements} property of a music object, or a single @q{child}
986 music object in the @code{element} property. For example,
987 @rinternals{SequentialMusic} has its children in @code{elements},
988 and @rinternals{GraceMusic} has its single argument in
989 @code{element}. The body of a repeat is stored in the @code{element}
990 property of @rinternals{RepeatedMusic}, and the alternatives in
993 @node Building complicated functions
994 @section Building complicated functions
996 This section explains how to gather the information necessary
997 to create complicated music functions.
1000 * Displaying music expressions::
1001 * Music properties::
1002 * Doubling a note with slurs (example)::
1003 * Adding articulation to notes (example)::
1006 @node Displaying music expressions
1007 @subsection Displaying music expressions
1009 @cindex internal storage
1010 @cindex displaying music expressions
1011 @cindex internal representation, displaying
1012 @cindex displayMusic
1013 @funindex \displayMusic
1015 When writing a music function it is often instructive to inspect how
1016 a music expression is stored internally. This can be done with the
1017 music function @code{\displayMusic}
1021 \displayMusic @{ c'4\f @}
1038 (ly:make-duration 2 0 1 1)
1040 (ly:make-pitch 0 0 0))
1042 'AbsoluteDynamicEvent
1047 By default, LilyPond will print these messages to the console along
1048 with all the other messages. To split up these messages and save
1049 the results of @code{\display@{STUFF@}}, you can specify an optional
1054 \displayMusic #(open-output-file "display.txt") @{ c'4\f @}
1058 This will overwrite a previous output file whenever it is called; if you
1059 need to write more than one expression, you would use a variable for
1060 your port and reuse it:
1063 port = #(open-output-file "display.txt")
1064 \displayMusic \port @{ c'4\f @}
1065 \displayMusic \port @{ d'4 @}
1066 #(close-output-port port)
1070 Guile's manual describes ports in detail. Closing the port is actually
1071 only necessary if you need to read the file before Lilypond finishes; in
1072 the first example, we did not bother to do so.
1074 A bit of reformatting makes the above information easier to read:
1077 (make-music 'SequentialMusic
1078 'elements (list (make-music 'EventChord
1079 'elements (list (make-music 'NoteEvent
1080 'duration (ly:make-duration 2 0 1 1)
1081 'pitch (ly:make-pitch 0 0 0))
1082 (make-music 'AbsoluteDynamicEvent
1086 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
1087 and its inner expressions are stored as a list in its @code{'elements}
1088 property. A note is represented as an @code{EventChord} expression,
1089 containing a @code{NoteEvent} object (storing the duration and
1090 pitch properties) and any extra information (in this case, an
1091 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
1094 @code{\displayMusic} returns the music it displays, so it will get
1095 interpreted as well as displayed. To avoid interpretation, write
1096 @code{\void} before @code{\displayMusic}.
1098 @node Music properties
1099 @subsection Music properties
1101 TODO -- make sure we delineate between @emph{music} properties,
1102 @emph{context} properties, and @emph{layout} properties. These
1103 are potentially confusing.
1105 The @code{NoteEvent} object is the first object of the
1106 @code{'elements} property of @code{someNote}.
1110 \displayMusic \someNote
1118 (ly:make-duration 2 0 1 1)
1120 (ly:make-pitch 0 0 0))))
1123 The @code{display-scheme-music} function is the function used by
1124 @code{\displayMusic} to display the Scheme representation of a music
1128 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1133 (ly:make-duration 2 0 1 1)
1135 (ly:make-pitch 0 0 0))
1138 Then the note pitch is accessed through the @code{'pitch} property
1139 of the @code{NoteEvent} object,
1142 #(display-scheme-music
1143 (ly:music-property (first (ly:music-property someNote 'elements))
1146 (ly:make-pitch 0 0 0)
1149 The note pitch can be changed by setting this @code{'pitch} property,
1151 @funindex \displayLilyMusic
1154 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1156 (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
1157 \displayLilyMusic \someNote
1163 @node Doubling a note with slurs (example)
1164 @subsection Doubling a note with slurs (example)
1166 Suppose we want to create a function that translates input like
1167 @code{a} into @code{a( a)}. We begin by examining the internal
1168 representation of the desired result.
1171 \displayMusic@{ a'( a') @}
1182 (ly:make-duration 2 0 1 1)
1184 (ly:make-pitch 0 5 0))
1195 (ly:make-duration 2 0 1 1)
1197 (ly:make-pitch 0 5 0))
1204 The bad news is that the @code{SlurEvent} expressions
1205 must be added @q{inside} the note (or more precisely,
1206 inside the @code{EventChord} expression).
1208 Now we examine the input,
1220 (ly:make-duration 2 0 1 1)
1222 (ly:make-pitch 0 5 0))))))
1225 So in our function, we need to clone this expression (so that we
1226 have two notes to build the sequence), add a @code{SlurEvent} to the
1227 @code{'elements} property of each one, and finally make a
1228 @code{SequentialMusic} with the two @code{EventChords}.
1231 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1232 "Return: @{ note ( note ) @}.
1233 `note' is supposed to be an EventChord."
1234 (let ((note2 (ly:music-deep-copy note)))
1235 (set! (ly:music-property note 'elements)
1236 (cons (make-music 'SlurEvent 'span-direction -1)
1237 (ly:music-property note 'elements)))
1238 (set! (ly:music-property note2 'elements)
1239 (cons (make-music 'SlurEvent 'span-direction 1)
1240 (ly:music-property note2 'elements)))
1241 (make-music 'SequentialMusic 'elements (list note note2))))
1245 @node Adding articulation to notes (example)
1246 @subsection Adding articulation to notes (example)
1248 The easy way to add articulation to notes is to merge two music
1249 expressions into one context, as explained in
1250 @ruser{Creating contexts}. However, suppose that we want to write
1251 a music function that does this.
1253 A @code{$variable} inside the @code{#@{...#@}} notation is like
1254 a regular @code{\variable} in classical LilyPond notation. We
1262 will not work in LilyPond. We could avoid this problem by attaching
1263 the articulation to a fake note,
1266 @{ << \music s1*0-.-> @}
1270 but for the sake of this example, we will learn how to do this in
1271 Scheme. We begin by examining our input and desired output,
1283 (ly:make-duration 2 0 1 1)
1285 (ly:make-pitch -1 0 0))))
1296 (ly:make-duration 2 0 1 1)
1298 (ly:make-pitch -1 0 0))
1305 We see that a note (@code{c4}) is represented as an @code{EventChord}
1306 expression, with a @code{NoteEvent} expression in its elements list. To
1307 add a marcato articulation, an @code{ArticulationEvent} expression must
1308 be added to the elements property of the @code{EventChord}
1311 To build this function, we begin with
1314 (define (add-marcato event-chord)
1315 "Add a marcato ArticulationEvent to the elements of `event-chord',
1316 which is supposed to be an EventChord expression."
1317 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1318 (set! (ly:music-property result-event-chord 'elements)
1319 (cons (make-music 'ArticulationEvent
1320 'articulation-type "marcato")
1321 (ly:music-property result-event-chord 'elements)))
1322 result-event-chord))
1325 The first line is the way to define a function in Scheme: the function
1326 name is @code{add-marcato}, and has one variable called
1327 @code{event-chord}. In Scheme, the type of variable is often clear
1328 from its name. (this is good practice in other programming languages,
1336 is a description of what the function does. This is not strictly
1337 necessary, but just like clear variable names, it is good practice.
1340 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1343 @code{let} is used to declare local variables. Here we use one local
1344 variable, named @code{result-event-chord}, to which we give the value
1345 @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
1346 a function specific to LilyPond, like all functions prefixed by
1347 @code{ly:}. It is use to make a copy of a music
1348 expression. Here we copy @code{event-chord} (the parameter of the
1349 function). Recall that our purpose is to add a marcato to an
1350 @code{EventChord} expression. It is better to not modify the
1351 @code{EventChord} which was given as an argument, because it may be
1354 Now we have a @code{result-event-chord}, which is a
1355 @code{NoteEventChord} expression and is a copy of
1356 @code{event-chord}. We add the marcato to its @code{'elements}
1360 (set! place new-value)
1363 Here, what we want to set (the @q{place}) is the @code{'elements}
1364 property of @code{result-event-chord} expression.
1367 (ly:music-property result-event-chord 'elements)
1370 @code{ly:music-property} is the function used to access music properties
1371 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
1372 see in the @code{\displayMusic} output above). The new value is the
1373 former @code{'elements} property, with an extra item: the
1374 @code{ArticulationEvent} expression, which we copy from the
1375 @code{\displayMusic} output,
1378 (cons (make-music 'ArticulationEvent
1379 'articulation-type "marcato")
1380 (ly:music-property result-event-chord 'elements))
1383 @code{cons} is used to add an element to a list without modifying
1384 the original list. This is what we want: the same list as before,
1385 plus the new @code{ArticulationEvent} expression. The order
1386 inside the @code{'elements} property is not important here.
1388 Finally, once we have added the marcato articulation to its @code{elements}
1389 property, we can return @code{result-event-chord}, hence the last line of
1392 Now we transform the @code{add-marcato} function into a music
1396 addMarcato = #(define-music-function (parser location event-chord)
1398 "Add a marcato ArticulationEvent to the elements of `event-chord',
1399 which is supposed to be an EventChord expression."
1400 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1401 (set! (ly:music-property result-event-chord 'elements)
1402 (cons (make-music 'ArticulationEvent
1403 'articulation-type "marcato")
1404 (ly:music-property result-event-chord 'elements)))
1405 result-event-chord))
1408 We may verify that this music function works correctly,
1411 \displayMusic \addMarcato c4
1420 * Tweaking with Scheme::
1423 @c @nod e Tweaking with Scheme
1424 @c @sectio n Tweaking with Scheme
1426 We have seen how LilyPond output can be heavily modified using
1428 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
1429 we have even more power if we use Scheme. For a full explanation
1430 of this, see the @ref{Scheme tutorial}, and
1431 @ref{Interfaces for programmers}.
1433 We can use Scheme to simply @code{\override} commands,
1435 TODO Find a simple example
1436 @c This isn't a valid example with skylining
1437 @c It works fine without padText -td
1441 @lilypond[quote,verbatim,ragged-right]
1442 padText = #(define-music-function (parser location padding) (number?)
1444 \once \override TextScript #'padding = #padding
1448 c4^"piu mosso" b a b
1450 c4^"piu mosso" d e f
1452 c4^"piu mosso" fis a g
1458 We can use it to create new commands:
1460 @c Check this is a valid example with skylining
1461 @c It is - 'padding still works
1464 @lilypond[quote,verbatim,ragged-right]
1465 tempoPadded = #(define-music-function (parser location padding tempotext)
1468 \once \override Score.MetronomeMark #'padding = $padding
1469 \tempo \markup { \bold #tempotext }
1473 \tempo \markup { "Low tempo" }
1475 \tempoPadded #4.0 #"High tempo"
1481 Even music expressions can be passed in:
1483 @lilypond[quote,verbatim,ragged-right]
1484 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1491 \pattern {d16 dis} { ais16-> b\p }