]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/extending/scheme-tutorial.itely
Doc:Extending: Change @unnumberedsubsubsec to @subheading
[lilypond.git] / Documentation / extending / scheme-tutorial.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
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..
9 @end ignore
10
11 @c \version "2.12.0"
12
13 @node Scheme tutorial
14 @chapter Scheme tutorial
15
16 @funindex #
17 @cindex Scheme
18 @cindex GUILE
19 @cindex Scheme, in-line code
20 @cindex accessing Scheme
21 @cindex evaluating Scheme
22 @cindex LISP
23
24 LilyPond uses the Scheme programming language, both as part of the
25 input syntax, and as internal mechanism to glue modules of the program
26 together.  This section is a very brief overview of entering data in
27 Scheme.  If you want to know more about Scheme, see
28 @uref{http://@/www@/.schemers@/.org}.
29
30 LilyPond uses the GNU Guile implementation of Scheme, which is
31 based on the Scheme @qq{R5RS} standard. If you are learning Scheme
32 to use with LilyPond, working with a different implementation (or
33 referring to a different standard) is not recommended. Information
34 on guile can be found at @uref{http://www.gnu.org/software/guile/}.
35 The @qq{R5RS} Scheme standard is located at
36 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
37
38 @menu
39 * Introduction to Scheme::
40 * Scheme in LilyPond::
41 * Building complicated functions::
42 @end menu
43
44 @node Introduction to Scheme
45 @section Introduction to Scheme
46
47 We begin with an introduction to Scheme.  For this brief introduction,
48 we will use the GUILE interpreter to explore how the language works.
49 Once we are familiar with Scheme, we will show how the language can
50 be integrated in LilyPond files.
51
52
53 @menu
54 * Scheme sandbox::
55 * Scheme variables::
56 * Scheme simple data types::
57 * Scheme compound data types::
58 * Calculations in Scheme::
59 * Scheme procedures::
60 * Scheme conditionals::
61 @end menu
62
63 @node Scheme sandbox
64 @subsection Scheme sandbox
65
66 The LilyPond installation includes the Guile implementation of
67 Scheme.  On most systems you can experiment in a Scheme sandbox by
68 opening a terminal window and typing @q{guile}.  On some systems,
69 notably Windows, you may need to set the environment variable
70 @code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
71 in the LilyPond installation. For the full path to this directory
72 see @rlearning{Other sources of information}.  Alternatively, Windows
73 users may simply choose @q{Run} from the Start menu and enter
74 @q{guile}.
75
76 Once the guile sandbox is running, you will received a guile prompt:
77
78 @lisp
79 guile>
80 @end lisp
81
82 You can enter Scheme expressions at this prompt to experiment with Scheme.
83
84 @node Scheme variables
85 @subsection Scheme variables
86
87 Scheme variables can have any valid scheme value, including a Scheme
88 procedure.
89
90 Scheme variables are created with @code{define}:
91
92 @lisp
93 guile> (define a 2)
94 guile>
95 @end lisp
96
97 Scheme variables can be evaluated at the guile prompt simply by
98 typing the variable name:
99
100 @lisp
101 guile> a
102 2
103 guile>
104 @end lisp
105
106 Scheme variables can be printed on the display by use of the display function:
107
108 @lisp
109 guile> (display a)
110 2guile>
111 @end lisp
112
113 @noindent
114 Note that the value @code{2} and the guile prompt @code{guile} both
115 showed up on the same line.  This can be avoided by calling the newline
116 procedure or displaying a newline character.
117
118 @lisp
119 guile> (display a)(newline)
120 2
121 guile> (display a)(display "\n")
122 2
123 guile>
124 @end lisp
125
126 Once a variable has been created, its value can be changed with @code{set!}:
127
128 @lisp
129 guile> (set! a 12345)
130 guile> a
131 12345
132 guile>
133 @end lisp
134
135 @node Scheme simple data types
136 @subsection Scheme simple data types
137
138 The most basic concept in a language is data typing: numbers, character
139 strings, lists, etc.  Here is a list of simple Scheme data types that are
140 often used with LilyPond.
141
142 @table @asis
143 @item Booleans
144 Boolean values are True or False.  The Scheme for True is @code{#t}
145 and False is @code{#f}.
146 @funindex ##t
147 @funindex ##f
148
149 @item Numbers
150 Numbers are entered in the standard fashion,
151 @code{1} is the (integer) number one, while @code{-1.5} is a
152 floating point number (a non-integer number).
153
154 @item Strings
155 Strings are enclosed in double quotes,
156
157 @example
158 "this is a string"
159 @end example
160
161 Strings may span several lines:
162
163 @example
164 "this
165 is
166 a string"
167 @end example
168
169 @noindent
170 and the newline characters at the end of each line will be included
171 in the string.
172
173 Newline characters can also be added by including @code{\n} in the
174 string.
175
176 @example
177 "this\nis a\nmultiline string"
178 @end example
179
180
181 Quotation marks and backslashes are added to strings
182 by preceding them with a backslash.
183 The string @code{\a said "b"} is entered as
184
185 @example
186 "\\a said \"b\""
187 @end example
188
189 @end table
190
191 There are additional Scheme data types that are not discussed here.
192 For a complete listing see the Guile reference guide,
193 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
194
195 @node Scheme compound data types
196 @subsection Scheme compound data types
197
198 There are also compound data types in Scheme.  The  types commonly used in
199 LilyPond programming include pairs, lists, alists, and hash tables.
200
201 @subheading Pairs
202
203 The foundational compound data type of Scheme is the @code{pair}.  As
204 might be expected from its name, a pair is two values glued together.
205 The operator used to form a pair is called @code{cons}.
206
207 @lisp
208 guile> (cons 4 5)
209 (4 . 5)
210 guile>
211 @end lisp
212
213 Note that the pair is displayed as two items surrounded by
214 parentheses and separated by whitespace, a period (@code{.}), and
215 more whitespace.  The period is @emph{not} a decimal point, but
216 rather an indicator of the pair.
217
218 Pairs can also be entered as literal values by preceding them with
219 a single quote character.
220
221 @lisp
222 guile> '(4 . 5)
223 (4 . 5)
224 guile>
225 @end lisp
226
227 The two elements of a pair may be any valid Scheme value:
228
229 @lisp
230 guile> (cons #t #f)
231 (#t . #f)
232 guile> '("blah-blah" . 3.1415926535)
233 ("blah-blah" . 3.1415926535)
234 guile>
235 @end lisp
236
237 The first and second elements of the pair can be accessed by the
238 Scheme procedures @code{car} and @code{cdr}, respectively.
239
240 @lisp
241 guile> (define mypair (cons 123 "hello there")
242 ... )
243 guile> (car mypair)
244 123
245 guile> (cdr mypair)
246 "hello there"
247 guile>
248 @end lisp
249
250 @noindent
251
252 Note:  @code{cdr} is pronounced "could-er", according Sussman and
253 Abelson, see
254 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
255
256 @subheading Lists
257
258 A very common Scheme data structure is the @emph{list}.  Formally, a
259 list is defined as either the empty list (represented as @code{'()},
260 or a pair whose @code{cdr} is a list.
261
262 There are many ways of creating lists.  Perhaps the most common is
263 with the @code{list} procedure:
264
265 @lisp
266 guile> (list 1 2 3 "abc" 17.5)
267 (1 2 3 "abc" 17.5)
268 @end lisp
269
270 As can be seen, a list is displayed in the form of individual elements
271 separated by whitespace and enclosed in parentheses.  Unlike a pair,
272 there is no period between the elements.
273
274 A list can also be entered as a literal list by enclosing its
275 elements in parentheses, and adding a quote:
276
277 @lisp
278 guile> '(17 23 "foo" "bar" "bazzle")
279 (17 23 "foo" "bar" "bazzle")
280 @end lisp
281
282 Lists are a central part of Scheme.  In, fact, Scheme is considered
283 a dialect of lisp, where @q{lisp} is an abbreviation for
284 @q{List Processing}.  Scheme expressions are all lists.
285
286 @subheading Association lists (alists)
287
288 A special type of list is an @emph{association list} or @emph{alist}.
289 An alist is used to store data for easy retrieval.
290
291 Alists are lists whose elements are pairs.  The @code{car} of each
292 element is called the @emph{key}, and the @code{cdr} of each element
293 is called the @emph{value}.  The Scheme procedure @code{assoc} is
294 used to retrieve an entry from the alist, and @code{cdr} is used to
295 retrieve the value:
296
297 @lisp
298 guile> (define my-alist '((1  . "A") (2 . "B") (3 . "C")))
299 guile> my-alist
300 ((1 . "A") (2 . "B") (3 . "C"))
301 guile> (assoc 2 my-alist)
302 (2 . "B")
303 guile> (cdr (assoc 2 my-alist))
304 "B"
305 guile>
306 @end lisp
307
308 Alists are widely used in LilyPond to store properties and other data.
309
310 @subheading Hash tables
311
312 A data structure that is used occasionally in LilyPond.  A hash table
313 is similar to an array, but the indexes to the array can be any type
314 of Scheme value, not just integers.
315
316 Hash tables are more efficient than alists if there is a lot of data
317 to store and the data changes very infrequently.
318
319 The syntax to create hash tables is a bit complex, but you
320 can see examples of it in the LilyPond source.
321
322 @lisp
323 guile> (define h (make-hash-table 10))
324 guile> h
325 #<hash-table 0/31>
326 guile> (hashq-set! h 'key1 "val1")
327 "val1"
328 guile> (hashq-set! h 'key2 "val2")
329 "val2"
330 guile> (hashq-set! h 3 "val3")
331 "val3"
332 @end lisp
333
334 Values are retrieved from hash tables with @code{hashq-ref}.
335
336 @lisp
337 guile> (hashq-ref h 3)
338 "val3"
339 guile> (hashq-ref h 'key2)
340 "val2"
341 guile>
342 @end lisp
343
344 Keys and values are retrieved as a pair with @code{hashq-get-handle}.
345 This is a preferred way, because it will return @code{#f} if a key is
346 not found.
347
348 @lisp
349 guile> (hashq-get-handle h 'key1)
350 (key1 . "val1")
351 guile> (hashq-get-handle h 'frob)
352 #f
353 guile>
354 @end lisp
355
356 @node Calculations in Scheme
357 @subsection Calculations in Scheme
358
359 @ignore
360 We have been using lists all along.  A calculation, like @code{(+ 1 2)}
361 is also a list (containing the symbol @code{+} and the numbers 1
362 and@tie{}2).  Normally lists are interpreted as calculations, and the
363 Scheme interpreter substitutes the outcome of the calculation.  To enter a
364 list, we stop the evaluation.  This is done by quoting the list with a
365 quote @code{'} symbol.  So, for calculations do not use a quote.
366
367 Inside a quoted list or pair, there is no need to quote anymore.  The
368 following is a pair of symbols, a list of symbols and a list of lists
369 respectively,
370
371 @example
372 #'(stem . head)
373 #'(staff clef key-signature)
374 #'((1) (2))
375 @end example
376 @end ignore
377
378 Scheme can be used to do calculations.  It uses @emph{prefix}
379 syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
380 traditional @math{1+2}.
381
382 @lisp
383 guile> (+ 1 2)
384 3
385 @end lisp
386
387 Calculations may be nested; the result of a function may
388 be used for another calculation.
389
390 @lisp
391 guile> (+ 1 (* 3 4))
392 13
393 @end lisp
394
395 These calculations are examples of evaluations; an expression like
396 @code{(* 3 4)} is replaced by its value @code{12}.
397
398 Scheme calculations are sensitive to the differences between integers
399 and non-integers.  Integer calculations are exact, while non-integers
400 are calculated to the appropriate limits of precision:
401
402 @lisp
403 guile> (/ 7 3)
404 7/3
405 guile> (/ 7.0 3.0)
406 2.33333333333333
407 @end lisp
408
409 When the scheme interpreter encounters an expression that is a list, the
410 first element of the list is treated as a procedure to be evaluated
411 with the arguments of the remainder of the list.  Therefore, all operators
412 in Scheme are prefix operators.
413
414 If the first element of a Scheme expression that is a list passed to the
415 interpreter`is @emph{not} an operator or procedure, an error will occur:
416
417 @lisp
418 guile> (1 2 3)
419
420 Backtrace:
421 In current input:
422   52: 0* [1 2 3]
423
424 <unnamed port>:52:1: In expression (1 2 3):
425 <unnamed port>:52:1: Wrong type to apply: 1
426 ABORT: (misc-error)
427 guile>
428 @end lisp
429
430 Here you can see that the interpreter was trying to treat 1 as an operator
431 or procedure, and it couldn't.  Hence the error is "Wrong type to apply: 1".
432
433 To create a list, then , we need to use the list operator, or we need to
434 quote the list so that the interpreter will not try to evaluate it.
435
436 @lisp
437 guile> (list 1 2 3)
438 (1 2 3)
439 guile> '(1 2 3)
440 (1 2 3)
441 guile>
442 @end lisp
443
444 This is an error that can appear as you are working with Scheme in LilyPond.
445
446 @ignore
447 The same assignment can be done in completely in Scheme as well,
448
449 @example
450 #(define twentyFour (* 2 twelve))
451 @end example
452
453 @c this next section is confusing -- need to rewrite
454
455 The @emph{name} of a variable is also an expression, similar to a
456 number or a string.  It is entered as
457
458 @example
459 #'twentyFour
460 @end example
461
462 @funindex #'symbol
463 @cindex quoting in Scheme
464
465 The quote mark @code{'} prevents the Scheme interpreter from substituting
466 @code{24} for the @code{twentyFour}.  Instead, we get the name
467 @code{twentyFour}.
468 @end ignore
469
470
471 @node Scheme procedures
472 @subsection Scheme procedures
473
474 Scheme procedures are executable scheme expressions that return
475 a value resulting from their execution.,  They can also manipulate
476 variables defined outside of the procedure.
477
478 @subheading Defining procedures
479
480 Procedures are defined in Scheme with define
481
482 @example
483 (define (function-name arg1 arg2 ... argn)
484  scheme-expression-that-gives-a-return-value)
485 @end example
486
487 For example, we could define a procedure to calculate the average:
488
489 @lisp
490 guile> (define (average x y) (/ (+ x y) 2))
491 guile> average
492 #<procedure average (x y)>
493 @end lisp
494
495 Once a procedure is defined, it is called by putting the procedure
496 name and the arguments in a list.  For example, we can calculate
497 the average of 3 and 12:
498
499 @lisp
500 guile> (average 3 12)
501 15/2
502 @end lisp
503
504 @subheading Predicates
505
506 Scheme procedures that return boolean values are often called
507 @emph{predicates}.  By convention (but not necessity), predicate names
508 typically end in a question mark:
509
510 @lisp
511 guile> (define (less-than-ten? x) (< x 10))
512 guile> (less-than-ten? 9)
513 #t
514 guile> (less-than-ten? 15)
515 #f
516 @end lisp
517
518 @subheading Return values
519
520 Sometimes the user would like to have multiple Scheme expressions in
521 a procedure.  There are two ways that multiple expressions can be
522 combined.  The first is the @code{begin} procedure, which allows
523 multiple expressions to be evaluated, and returns the value of
524 the last expression.
525
526 @lisp
527 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
528 4
529 @end lisp
530
531 The second way to combine multiple expressions is in a @code{let} block.
532 In a let block, a series of bindings are created, and then a sequence
533 of expressions that can include those bindings is evaluated.  The
534 return value of the let block is the return value of the last
535 statement in the let block:
536
537 @lisp
538 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
539 ... (+ (* x y) (/ z x)))
540 508
541 @end lisp
542
543 @node Scheme conditionals
544 @subsection Scheme conditionals
545
546 @subheading if
547
548 Scheme has an @code{if} procedure:
549
550 @example
551 (if test-expression true-expression false-expression)
552 @end example
553
554 @var{test-expression} is an expression that returns a boolean
555 value.  If @var{test-expression} returns @code{#t}, the if
556 procedure returns the value of @var{true-expression}, otherwise
557 it returns the value of @var{false-expression}.
558
559 @lisp
560 guile> (define a 3)
561 guile> (define b 5)
562 guile> (if (> a b) "a is greater than b" "a is not greater than b")
563 "a is not greater than b"
564 @end lisp
565
566 @subheading cond
567
568 Another conditional procedure in scheme is @code{cond}:
569
570 @example
571 (cond (test-expression-1 result-expression-sequence-1)
572       (test-expression-2 result-expression-sequence-2)
573       ...
574       (test-expression-n result-expression-sequence-n))
575 @end example
576
577 For example:
578
579 @lisp
580 guile> (define a 6)
581 guile> (define b 8)
582 guile> (cond ((< a b) "a is less than b")
583 ...          ((= a b) "a equals b")
584 ...          ((> a b) "a is greater than b"))
585 "a is less than b"
586 @end lisp
587
588 @node Scheme in LilyPond
589 @section Scheme in LilyPond
590
591
592 @menu
593 * LilyPond Scheme syntax::
594 * LilyPond variables::
595 * Input variables and Scheme::
596 * Object properties::
597 * LilyPond compound variables::
598 * Internal music representation::
599 @end menu
600
601 @node LilyPond Scheme syntax
602 @subsection LilyPond Scheme syntax
603
604 In a music file, snippets of Scheme code are introduced with the hash
605 mark @code{#}.  So, the previous examples translated to LilyPond are
606
607 @example
608 ##t ##f
609 #1 #-1.5
610 #"this is a string"
611 #"this
612 is
613 a string"
614 @end example
615
616 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
617 be used within Scheme code.  Comments in Guile Scheme are entered
618 as follows:
619
620 @example
621 ; this is a single-line comment
622
623 #!
624   This a (non-nestable) Guile-style block comment
625   But these are rarely used by Schemers and never in
626   LilyPond source code
627 !#
628 @end example
629
630 Multiple consecutive scheme expressions in a music file can be
631 combined using the @code{begin} operator. This permits the number
632 of hash marks to be reduced to one.
633
634 @example
635 #(begin
636   (define foo 0)
637   (define bar 1))
638 @end example
639
640 @c todo -- # introduces a scheme *expression*
641 @c         need the concept of an expression
642
643 If @code{#} is followed by an opening parenthesis, @code{(}, as in
644 the example above, the parser will remain in Scheme mode until
645 a matching closing parenthesis, @code{)}, is found, so further
646 @code{#} symbols to introduce a Scheme section are not required.
647
648 For the rest of this section, we will assume that the data is entered
649 in a music file, so we add @code{#}s everywhere.
650
651 @node LilyPond variables
652 @subsection LilyPond variables
653
654
655 TODO -- make this read right
656
657 A similar thing
658 happens with variables.  After defining a variable
659
660 @example
661 twelve = 12
662 @end example
663
664 @noindent
665 variables can also be used in expressions, here
666
667 @example
668 twentyFour = (* 2 twelve)
669 @end example
670
671 @noindent
672 the number 24 is stored in the variable @code{twentyFour}.
673
674 @node Input variables and Scheme
675 @subsection Input variables and Scheme
676
677 The input format supports the notion of variables: in the following
678 example, a music expression is assigned to a variable with the name
679 @code{traLaLa}.
680
681 @example
682 traLaLa = @{ c'4 d'4 @}
683 @end example
684
685 @noindent
686
687 There is also a form of scoping: in the following example, the
688 @code{\layout} block also contains a @code{traLaLa} variable, which is
689 independent of the outer @code{\traLaLa}.
690 @example
691 traLaLa = @{ c'4 d'4 @}
692 \layout @{ traLaLa = 1.0 @}
693 @end example
694 @c
695 In effect, each input file is a scope, and all @code{\header},
696 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
697 toplevel scope.
698
699 Both variables and scoping are implemented in the GUILE module system.
700 An anonymous Scheme module is attached to each scope.  An assignment of
701 the form
702 @example
703 traLaLa = @{ c'4 d'4 @}
704 @end example
705
706 @noindent
707 is internally converted to a Scheme definition
708 @example
709 (define traLaLa @var{Scheme value of `@code{... }'})
710 @end example
711
712 This means that input variables and Scheme variables may be freely
713 mixed.  In the following example, a music fragment is stored in the
714 variable @code{traLaLa}, and duplicated using Scheme.  The result is
715 imported in a @code{\score} block by means of a second variable
716 @code{twice}:
717
718 @lilypond[verbatim]
719 traLaLa = { c'4 d'4 }
720
721 %% dummy action to deal with parser lookahead
722 #(display "this needs to be here, sorry!")
723
724 #(define newLa (map ly:music-deep-copy
725   (list traLaLa traLaLa)))
726 #(define twice
727   (make-sequential-music newLa))
728
729 { \twice }
730 @end lilypond
731
732 @c Due to parser lookahead
733
734 In this example, the assignment happens after the parser has
735 verified that nothing interesting happens after
736 @code{traLaLa = @{ ... @}}.  Without the dummy statement in the
737 above example, the @code{newLa} definition is executed before
738 @code{traLaLa} is defined, leading to a syntax error.
739
740 The above example shows how to @q{export} music expressions from the
741 input to the Scheme interpreter.  The opposite is also possible.  By
742 wrapping a Scheme value in the function @code{ly:export}, a Scheme
743 value is interpreted as if it were entered in LilyPond syntax.
744 Instead of defining @code{\twice}, the example above could also have
745 been written as
746
747 @example
748 ...
749 @{ #(ly:export (make-sequential-music (list newLa))) @}
750 @end example
751
752 Scheme code is evaluated as soon as the parser encounters it.  To
753 define some Scheme code in a macro (to be called later), use
754 @ref{Void functions}, or
755
756 @example
757 #(define (nopc)
758   (ly:set-option 'point-and-click #f))
759
760 ...
761 #(nopc)
762 @{ c'4 @}
763 @end example
764
765 @knownissues
766
767 Mixing Scheme and LilyPond variables is not possible with the
768 @code{--safe} option.
769
770
771
772
773 @node Object properties
774 @subsection Object properties
775
776 This syntax will be used very frequently, since many of the layout
777 tweaks involve assigning (Scheme) values to internal variables, for
778 example
779
780 @example
781 \override Stem #'thickness = #2.6
782 @end example
783
784 This instruction adjusts the appearance of stems.  The value @code{2.6}
785 is put into the @code{thickness} variable of a @code{Stem}
786 object.  @code{thickness} is measured relative to the thickness of
787 staff lines, so these stem lines will be @code{2.6} times the
788 width of staff lines.  This makes stems almost twice as thick as their
789 normal size.  To distinguish between variables defined in input files (like
790 @code{twentyFour} in the example above) and variables of internal
791 objects, we will call the latter @q{properties} and the former
792 @q{variables.}  So, the stem object has a @code{thickness} property,
793 while @code{twentyFour} is an variable.
794
795 @cindex properties vs. variables
796 @cindex variables vs. properties
797
798 @c  todo -- here we're getting interesting.  We're now introducing
799 @c  LilyPond variable types.  I think this deserves a section all
800 @c  its own
801
802 @node LilyPond compound variables
803 @subsection LilyPond compound variables
804
805 @subheading Offsets
806
807 Two-dimensional offsets (X and Y coordinates) as well as object sizes
808 (intervals with a left and right point) are entered as @code{pairs}.  A
809 pair@footnote{In Scheme terminology, the pair is called @code{cons},
810 and its two elements are called @code{car} and @code{cdr} respectively.}
811 is entered as @code{(first . second)} and, like symbols, they must be quoted,
812
813 @example
814 \override TextScript #'extra-offset = #'(1 . 2)
815 @end example
816
817 This assigns the pair (1, 2) to the @code{extra-offset} property of the
818 TextScript object.  These numbers are measured in staff-spaces, so
819 this command moves the object 1 staff space to the right, and 2 spaces up.
820
821 @subheading Extents
822
823 todo -- write something about extents
824
825 @subheading Property alists
826
827 todo -- write something about property alists
828
829 @subheading Alist chains
830
831 todo -- write something about alist chains
832
833 @node Internal music representation
834 @subsection Internal music representation
835
836 When a music expression is parsed, it is converted into a set of
837 Scheme music objects.  The defining property of a music object is that
838 it takes up time.  Time is a rational number that measures the length
839 of a piece of music in whole notes.
840
841 A music object has three kinds of types:
842 @itemize
843 @item
844 music name: Each music expression has a name.  For example, a note
845 leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
846 a @rinternals{SimultaneousMusic}.  A list of all expressions
847 available is in the Internals Reference manual, under
848 @rinternals{Music expressions}.
849
850 @item
851 @q{type} or interface: Each music name has several @q{types} or
852 interfaces, for example, a note is an @code{event}, but it is also a
853 @code{note-event}, a @code{rhythmic-event}, and a
854 @code{melodic-event}.  All classes of music are listed in the
855 Internals Reference, under
856 @rinternals{Music classes}.
857
858 @item
859 C++ object: Each music object is represented by an object of the C++
860 class @code{Music}.
861 @end itemize
862
863 The actual information of a music expression is stored in properties.
864 For example, a @rinternals{NoteEvent} has @code{pitch} and
865 @code{duration} properties that store the pitch and duration of that
866 note.  A list of all properties available can be found in the
867 Internals Reference, under @rinternals{Music properties}.
868
869 A compound music expression is a music object that contains other
870 music objects in its properties.  A list of objects can be stored in
871 the @code{elements} property of a music object, or a single @q{child}
872 music object in the @code{element} property.  For example,
873 @rinternals{SequentialMusic} has its children in @code{elements},
874 and @rinternals{GraceMusic} has its single argument in
875 @code{element}.  The body of a repeat is stored in the @code{element}
876 property of @rinternals{RepeatedMusic}, and the alternatives in
877 @code{elements}.
878
879 @node Building complicated functions
880 @section Building complicated functions
881
882 This section explains how to gather the information necessary
883 to create complicated music functions.
884
885 @menu
886 * Displaying music expressions::
887 * Music properties::
888 * Doubling a note with slurs (example)::
889 * Adding articulation to notes (example)::
890 @end menu
891
892 @node Displaying music expressions
893 @subsection Displaying music expressions
894
895 @cindex internal storage
896 @cindex displaying music expressions
897 @cindex internal representation, displaying
898 @cindex displayMusic
899 @funindex \displayMusic
900
901 When writing a music function it is often instructive to inspect how
902 a music expression is stored internally.  This can be done with the
903 music function @code{\displayMusic}
904
905 @example
906 @{
907   \displayMusic @{ c'4\f @}
908 @}
909 @end example
910
911 @noindent
912 will display
913
914 @example
915 (make-music
916   'SequentialMusic
917   'elements
918   (list (make-music
919           'EventChord
920           'elements
921           (list (make-music
922                   'NoteEvent
923                   'duration
924                   (ly:make-duration 2 0 1 1)
925                   'pitch
926                   (ly:make-pitch 0 0 0))
927                 (make-music
928                   'AbsoluteDynamicEvent
929                   'text
930                   "f")))))
931 @end example
932
933 By default, LilyPond will print these messages to the console along
934 with all the other messages.  To split up these messages and save
935 the results of @code{\display@{STUFF@}}, redirect the output to
936 a file.
937
938 @example
939 lilypond file.ly >display.txt
940 @end example
941
942 With a bit of reformatting, the above information is
943 easier to read,
944
945 @example
946 (make-music 'SequentialMusic
947   'elements (list (make-music 'EventChord
948                     'elements (list (make-music 'NoteEvent
949                                       'duration (ly:make-duration 2 0 1 1)
950                                       'pitch (ly:make-pitch 0 0 0))
951                                     (make-music 'AbsoluteDynamicEvent
952                                       'text "f")))))
953 @end example
954
955 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
956 and its inner expressions are stored as a list in its @code{'elements}
957 property.  A note is represented as an @code{EventChord} expression,
958 containing a @code{NoteEvent} object (storing the duration and
959 pitch properties) and any extra information (in this case, an
960 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
961
962
963 @node Music properties
964 @subsection Music properties
965
966 The @code{NoteEvent} object is the first object of the
967 @code{'elements} property of @code{someNote}.
968
969 @example
970 someNote = c'
971 \displayMusic \someNote
972 ===>
973 (make-music
974   'EventChord
975   'elements
976   (list (make-music
977           'NoteEvent
978           'duration
979           (ly:make-duration 2 0 1 1)
980           'pitch
981           (ly:make-pitch 0 0 0))))
982 @end example
983
984 The @code{display-scheme-music} function is the function used by
985 @code{\displayMusic} to display the Scheme representation of a music
986 expression.
987
988 @example
989 #(display-scheme-music (first (ly:music-property someNote 'elements)))
990 ===>
991 (make-music
992   'NoteEvent
993   'duration
994   (ly:make-duration 2 0 1 1)
995   'pitch
996   (ly:make-pitch 0 0 0))
997 @end example
998
999 Then the note pitch is accessed through the @code{'pitch} property
1000 of the @code{NoteEvent} object,
1001
1002 @example
1003 #(display-scheme-music
1004    (ly:music-property (first (ly:music-property someNote 'elements))
1005                       'pitch))
1006 ===>
1007 (ly:make-pitch 0 0 0)
1008 @end example
1009
1010 The note pitch can be changed by setting this @code{'pitch} property,
1011
1012 @funindex \displayLilyMusic
1013
1014 @example
1015 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1016                           'pitch)
1017        (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
1018 \displayLilyMusic \someNote
1019 ===>
1020 d'
1021 @end example
1022
1023
1024 @node Doubling a note with slurs (example)
1025 @subsection Doubling a note with slurs (example)
1026
1027 Suppose we want to create a function that translates input like
1028 @code{a} into @code{a( a)}.  We begin by examining the internal
1029 representation of the desired result.
1030
1031 @example
1032 \displayMusic@{ a'( a') @}
1033 ===>
1034 (make-music
1035   'SequentialMusic
1036   'elements
1037   (list (make-music
1038           'EventChord
1039           'elements
1040           (list (make-music
1041                   'NoteEvent
1042                   'duration
1043                   (ly:make-duration 2 0 1 1)
1044                   'pitch
1045                   (ly:make-pitch 0 5 0))
1046                 (make-music
1047                   'SlurEvent
1048                   'span-direction
1049                   -1)))
1050         (make-music
1051           'EventChord
1052           'elements
1053           (list (make-music
1054                   'NoteEvent
1055                   'duration
1056                   (ly:make-duration 2 0 1 1)
1057                   'pitch
1058                   (ly:make-pitch 0 5 0))
1059                 (make-music
1060                   'SlurEvent
1061                   'span-direction
1062                   1)))))
1063 @end example
1064
1065 The bad news is that the @code{SlurEvent} expressions
1066 must be added @q{inside} the note (or more precisely,
1067 inside the @code{EventChord} expression).
1068
1069 Now we examine the input,
1070
1071 @example
1072 (make-music
1073   'SequentialMusic
1074   'elements
1075   (list (make-music
1076           'EventChord
1077           'elements
1078           (list (make-music
1079                   'NoteEvent
1080                   'duration
1081                   (ly:make-duration 2 0 1 1)
1082                   'pitch
1083                   (ly:make-pitch 0 5 0))))))
1084 @end example
1085
1086 So in our function, we need to clone this expression (so that we
1087 have two notes to build the sequence), add @code{SlurEvents} to the
1088 @code{'elements} property of each one, and finally make a
1089 @code{SequentialMusic} with the two @code{EventChords}.
1090
1091 @example
1092 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1093          "Return: @{ note ( note ) @}.
1094          `note' is supposed to be an EventChord."
1095          (let ((note2 (ly:music-deep-copy note)))
1096            (set! (ly:music-property note 'elements)
1097                  (cons (make-music 'SlurEvent 'span-direction -1)
1098                        (ly:music-property note 'elements)))
1099            (set! (ly:music-property note2 'elements)
1100                  (cons (make-music 'SlurEvent 'span-direction 1)
1101                        (ly:music-property note2 'elements)))
1102            (make-music 'SequentialMusic 'elements (list note note2))))
1103 @end example
1104
1105
1106 @node Adding articulation to notes (example)
1107 @subsection Adding articulation to notes (example)
1108
1109 The easy way to add articulation to notes is to merge two music
1110 expressions into one context, as explained in
1111 @ruser{Creating contexts}.  However, suppose that we want to write
1112 a music function that does this.
1113
1114 A @code{$variable} inside the @code{#@{...#@}} notation is like
1115 a regular @code{\variable} in classical LilyPond notation.  We
1116 know that
1117
1118 @example
1119 @{ \music -. -> @}
1120 @end example
1121
1122 @noindent
1123 will not work in LilyPond.  We could avoid this problem by attaching
1124 the articulation to a fake note,
1125
1126 @example
1127 @{ << \music s1*0-.-> @}
1128 @end example
1129
1130 @noindent
1131 but for the sake of this example, we will learn how to do this in
1132 Scheme.  We begin by examining our input and desired output,
1133
1134 @example
1135 %  input
1136 \displayMusic c4
1137 ===>
1138 (make-music
1139   'EventChord
1140   'elements
1141   (list (make-music
1142           'NoteEvent
1143           'duration
1144           (ly:make-duration 2 0 1 1)
1145           'pitch
1146           (ly:make-pitch -1 0 0))))
1147 =====
1148 %  desired output
1149 \displayMusic c4->
1150 ===>
1151 (make-music
1152   'EventChord
1153   'elements
1154   (list (make-music
1155           'NoteEvent
1156           'duration
1157           (ly:make-duration 2 0 1 1)
1158           'pitch
1159           (ly:make-pitch -1 0 0))
1160         (make-music
1161           'ArticulationEvent
1162           'articulation-type
1163           "marcato")))
1164 @end example
1165
1166 We see that a note (@code{c4}) is represented as an @code{EventChord}
1167 expression, with a @code{NoteEvent} expression in its elements list.  To
1168 add a marcato articulation, an @code{ArticulationEvent} expression must
1169 be added to the elements property of the @code{EventChord}
1170 expression.
1171
1172 To build this function, we begin with
1173
1174 @example
1175 (define (add-marcato event-chord)
1176   "Add a marcato ArticulationEvent to the elements of `event-chord',
1177   which is supposed to be an EventChord expression."
1178   (let ((result-event-chord (ly:music-deep-copy event-chord)))
1179     (set! (ly:music-property result-event-chord 'elements)
1180           (cons (make-music 'ArticulationEvent
1181                   'articulation-type "marcato")
1182                 (ly:music-property result-event-chord 'elements)))
1183     result-event-chord))
1184 @end example
1185
1186 The first line is the way to define a function in Scheme: the function
1187 name is @code{add-marcato}, and has one variable called
1188 @code{event-chord}.  In Scheme, the type of variable is often clear
1189 from its name.  (this is good practice in other programming languages,
1190 too!)
1191
1192 @example
1193 "Add a marcato..."
1194 @end example
1195
1196 @noindent
1197 is a description of what the function does.  This is not strictly
1198 necessary, but just like clear variable names, it is good practice.
1199
1200 @example
1201 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1202 @end example
1203
1204 @code{let} is used to declare local variables.  Here we use one local
1205 variable, named @code{result-event-chord}, to which we give the value
1206 @code{(ly:music-deep-copy event-chord)}.  @code{ly:music-deep-copy} is
1207 a function specific to LilyPond, like all functions prefixed by
1208 @code{ly:}.  It is use to make a copy of a music
1209 expression.  Here we copy @code{event-chord} (the parameter of the
1210 function).  Recall that our purpose is to add a marcato to an
1211 @code{EventChord} expression.  It is better to not modify the
1212 @code{EventChord} which was given as an argument, because it may be
1213 used elsewhere.
1214
1215 Now we have a @code{result-event-chord}, which is a
1216 @code{NoteEventChord} expression and is a copy of
1217 @code{event-chord}.  We add the marcato to its @code{'elements}
1218 list property.
1219
1220 @example
1221 (set! place new-value)
1222 @end example
1223
1224 Here, what we want to set (the @q{place}) is the @code{'elements}
1225 property of @code{result-event-chord} expression.
1226
1227 @example
1228 (ly:music-property result-event-chord 'elements)
1229 @end example
1230
1231 @code{ly:music-property} is the function used to access music properties
1232 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
1233 see in the @code{\displayMusic} output above).  The new value is the
1234 former @code{'elements} property, with an extra item: the
1235 @code{ArticulationEvent} expression, which we copy from the
1236 @code{\displayMusic} output,
1237
1238 @example
1239 (cons (make-music 'ArticulationEvent
1240         'articulation-type "marcato")
1241       (ly:music-property result-event-chord 'elements))
1242 @end example
1243
1244 @code{cons} is used to add an element to a list without modifying
1245 the original list.  This is what we want: the same list as before,
1246 plus the new @code{ArticulationEvent} expression.  The order
1247 inside the @code{'elements} property is not important here.
1248
1249 Finally, once we have added the marcato articulation to its @code{elements}
1250 property, we can return @code{result-event-chord}, hence the last line of
1251 the function.
1252
1253 Now we transform the @code{add-marcato} function into a music
1254 function,
1255
1256 @example
1257 addMarcato = #(define-music-function (parser location event-chord)
1258                                      (ly:music?)
1259     "Add a marcato ArticulationEvent to the elements of `event-chord',
1260     which is supposed to be an EventChord expression."
1261     (let ((result-event-chord (ly:music-deep-copy event-chord)))
1262       (set! (ly:music-property result-event-chord 'elements)
1263             (cons (make-music 'ArticulationEvent
1264                     'articulation-type "marcato")
1265                   (ly:music-property result-event-chord 'elements)))
1266       result-event-chord))
1267 @end example
1268
1269 We may verify that this music function works correctly,
1270
1271 @example
1272 \displayMusic \addMarcato c4
1273 @end example
1274
1275
1276
1277
1278
1279
1280 @ignore
1281 @menu
1282 * Tweaking with Scheme::
1283 @end menu
1284
1285 @c @node Tweaking with Scheme
1286 @c @section Tweaking with Scheme
1287
1288 We have seen how LilyPond output can be heavily modified using
1289 commands like
1290 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
1291 we have even more power if we use Scheme.  For a full explanation
1292 of this, see the @ref{Scheme tutorial}, and
1293 @ref{Interfaces for programmers}.
1294
1295 We can use Scheme to simply @code{\override} commands,
1296
1297 TODO Find a simple example
1298 @c This isn't a valid example with skylining
1299 @c It works fine without padText  -td
1300 @end ignore
1301
1302 @ignore
1303 @lilypond[quote,verbatim,ragged-right]
1304 padText = #(define-music-function (parser location padding) (number?)
1305 #{
1306   \once \override TextScript #'padding = #$padding
1307 #})
1308
1309 \relative c''' {
1310   c4^"piu mosso" b a b
1311   \padText #1.8
1312   c4^"piu mosso" d e f
1313   \padText #2.6
1314   c4^"piu mosso" fis a g
1315 }
1316 @end lilypond
1317 @end ignore
1318
1319 @ignore
1320 We can use it to create new commands:
1321
1322 @c Check this is a valid example with skylining
1323 @c It is - 'padding still works
1324
1325
1326 @lilypond[quote,verbatim,ragged-right]
1327 tempoPadded = #(define-music-function (parser location padding tempotext)
1328   (number? string?)
1329 #{
1330   \once \override Score.MetronomeMark #'padding = $padding
1331   \tempo \markup { \bold $tempotext }
1332 #})
1333
1334 \relative c'' {
1335   \tempo \markup { "Low tempo" }
1336   c4 d e f g1
1337   \tempoPadded #4.0 #"High tempo"
1338   g4 f e d c1
1339 }
1340 @end lilypond
1341
1342
1343 Even music expressions can be passed in:
1344
1345 @lilypond[quote,verbatim,ragged-right]
1346 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1347 #{
1348   $x e8 a b $y b a e
1349 #})
1350
1351 \relative c''{
1352   \pattern c8 c8\f
1353   \pattern {d16 dis} { ais16-> b\p }
1354 }
1355 @end lilypond
1356 @end ignore