]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/extending/scheme-tutorial.itely
Doc-ja: Add ja-NR
[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.13.36"
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 receive 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 using the display function:
107
108 @lisp
109 guile> (display a)
110 2guile>
111 @end lisp
112
113 @noindent
114 Note that both the value @code{2} and the guile prompt @code{guile}
115 showed up on the same line.  This can be avoided by calling the
116 newline 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,
410 the first element of the list is treated as a procedure to be
411 evaluated with the arguments of the remainder of the list.  Therefore,
412 all operators in Scheme are prefix operators.
413
414 If the first element of a Scheme expression that is a list passed to
415 the interpreter is @emph{not} an operator or procedure, an error will
416 occur:
417
418 @lisp
419 guile> (1 2 3)
420
421 Backtrace:
422 In current input:
423   52: 0* [1 2 3]
424
425 <unnamed port>:52:1: In expression (1 2 3):
426 <unnamed port>:52:1: Wrong type to apply: 1
427 ABORT: (misc-error)
428 guile>
429 @end lisp
430
431 Here you can see that the interpreter was trying to treat 1 as an
432 operator or procedure, and it couldn't.  Hence the error is "Wrong
433 type to apply: 1".
434
435 Therefore, to create a list we need to use the list operator, or to
436 quote the list so that the interpreter will not try to evaluate it.
437
438 @lisp
439 guile> (list 1 2 3)
440 (1 2 3)
441 guile> '(1 2 3)
442 (1 2 3)
443 guile>
444 @end lisp
445
446 This is an error that can appear as you are working with Scheme in LilyPond.
447
448 @ignore
449 The same assignment can be done in completely in Scheme as well,
450
451 @example
452 #(define twentyFour (* 2 twelve))
453 @end example
454
455 @c this next section is confusing -- need to rewrite
456
457 The @emph{name} of a variable is also an expression, similar to a
458 number or a string.  It is entered as
459
460 @example
461 #'twentyFour
462 @end example
463
464 @funindex #'symbol
465 @cindex quoting in Scheme
466
467 The quote mark @code{'} prevents the Scheme interpreter from substituting
468 @code{24} for the @code{twentyFour}.  Instead, we get the name
469 @code{twentyFour}.
470 @end ignore
471
472
473 @node Scheme procedures
474 @subsection Scheme procedures
475
476 Scheme procedures are executable scheme expressions that return a
477 value resulting from their execution.  They can also manipulate
478 variables defined outside of the procedure.
479
480 @subheading Defining procedures
481
482 Procedures are defined in Scheme with define
483
484 @example
485 (define (function-name arg1 arg2 ... argn)
486  scheme-expression-that-gives-a-return-value)
487 @end example
488
489 For example, we could define a procedure to calculate the average:
490
491 @lisp
492 guile> (define (average x y) (/ (+ x y) 2))
493 guile> average
494 #<procedure average (x y)>
495 @end lisp
496
497 Once a procedure is defined, it is called by putting the procedure
498 name and the arguments in a list.  For example, we can calculate
499 the average of 3 and 12:
500
501 @lisp
502 guile> (average 3 12)
503 15/2
504 @end lisp
505
506 @subheading Predicates
507
508 Scheme procedures that return boolean values are often called
509 @emph{predicates}.  By convention (but not necessity), predicate names
510 typically end in a question mark:
511
512 @lisp
513 guile> (define (less-than-ten? x) (< x 10))
514 guile> (less-than-ten? 9)
515 #t
516 guile> (less-than-ten? 15)
517 #f
518 @end lisp
519
520 @subheading Return values
521
522 Scheme procedures always return a return value, which is the value
523 of the last expression executed in the procedure.  The return
524 value can be any valid Scheme value, including a complex data
525 structure or a procedure.
526
527 Sometimes the user would like to have multiple Scheme expressions in
528 a procedure.  There are two ways that multiple expressions can be
529 combined.  The first is the @code{begin} procedure, which allows
530 multiple expressions to be evaluated, and returns the value of
531 the last expression.
532
533 @lisp
534 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
535 4
536 @end lisp
537
538 The second way to combine multiple expressions is in a @code{let} block.
539 In a let block, a series of bindings are created, and then a sequence
540 of expressions that can include those bindings is evaluated.  The
541 return value of the let block is the return value of the last
542 statement in the let block:
543
544 @lisp
545 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
546 ... (+ (* x y) (/ z x)))
547 508
548 @end lisp
549
550 @node Scheme conditionals
551 @subsection Scheme conditionals
552
553 @subheading if
554
555 Scheme has an @code{if} procedure:
556
557 @example
558 (if test-expression true-expression false-expression)
559 @end example
560
561 @var{test-expression} is an expression that returns a boolean
562 value.  If @var{test-expression} returns @code{#t}, the if
563 procedure returns the value of @var{true-expression}, otherwise
564 it returns the value of @var{false-expression}.
565
566 @lisp
567 guile> (define a 3)
568 guile> (define b 5)
569 guile> (if (> a b) "a is greater than b" "a is not greater than b")
570 "a is not greater than b"
571 @end lisp
572
573 @subheading cond
574
575 Another conditional procedure in scheme is @code{cond}:
576
577 @example
578 (cond (test-expression-1 result-expression-sequence-1)
579       (test-expression-2 result-expression-sequence-2)
580       ...
581       (test-expression-n result-expression-sequence-n))
582 @end example
583
584 For example:
585
586 @lisp
587 guile> (define a 6)
588 guile> (define b 8)
589 guile> (cond ((< a b) "a is less than b")
590 ...          ((= a b) "a equals b")
591 ...          ((> a b) "a is greater than b"))
592 "a is less than b"
593 @end lisp
594
595 @node Scheme in LilyPond
596 @section Scheme in LilyPond
597
598
599 @menu
600 * LilyPond Scheme syntax::
601 * LilyPond variables::
602 * Input variables and Scheme::
603 * Object properties::
604 * LilyPond compound variables::
605 * Internal music representation::
606 @end menu
607
608 @node LilyPond Scheme syntax
609 @subsection LilyPond Scheme syntax
610
611 The Guile interpreter is part of LilyPond, which means that
612 Scheme can be included in LilyPond input files.  The hash mark @code{#}
613 is used to tell the LilyPond parser that the next value is a Scheme
614 value.
615
616 Once the parser sees a hash mark, input is passed to the Guile
617 interpreter to evaluate the Scheme expression.  The interpreter continues
618 to process input until the end of a Scheme expression is seen.
619
620 Scheme procedures can be defined in LilyPond input files:
621
622 @example
623 #(define (average a b c) (/ (+ a b c) 3))
624 @end example
625
626 Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
627 be used within Scheme code, even in a LilyPond input file, because
628 the Guile interpreter, not the LilyPond parser, is interpreting
629 the Scheme expression.  Comments in Guile Scheme are entered
630 as follows:
631
632 @example
633 ; this is a single-line comment
634
635 #!
636   This a (non-nestable) Guile-style block comment
637   But these are rarely used by Schemers and never in
638   LilyPond source code
639 !#
640 @end example
641
642 For the rest of this section, we will assume that the data is entered
643 in a music file, so we add @code{#}s at the beginning of each Scheme
644 expression.
645
646 All of the top-level Scheme expressions in a LilyPond input file can
647 be combined into a single Scheme expression by the use of the
648 @code{begin} statement:
649
650 @example
651 #(begin
652   (define foo 0)
653   (define bar 1))
654 @end example
655
656
657 @node LilyPond variables
658 @subsection LilyPond variables
659
660 LilyPond variables are stored internally in the form of Scheme
661 variables.  Thus,
662
663 @example
664 twelve = 12
665 @end example
666
667 @noindent
668 is equivalent to
669
670 @example
671 #(define twelve 12)
672 @end example
673
674 This means that LilyPond variables are available
675 for use in Scheme expressions.  For example, we could use
676
677 @example
678 twentyFour = #(* 2 twelve)
679 @end example
680
681 @noindent
682 which would result in the number 24 being stored in the
683 LilyPond (and Scheme) variable @code{twentyFour}.
684
685 @node Input variables and Scheme
686 @subsection Input variables and Scheme
687
688 The input format supports the notion of variables: in the following
689 example, a music expression is assigned to a variable with the name
690 @code{traLaLa}.
691
692 @example
693 traLaLa = @{ c'4 d'4 @}
694 @end example
695
696 @noindent
697
698 There is also a form of scoping: in the following example, the
699 @code{\layout} block also contains a @code{traLaLa} variable, which is
700 independent of the outer @code{\traLaLa}.
701
702 @example
703 traLaLa = @{ c'4 d'4 @}
704 \layout @{ traLaLa = 1.0 @}
705 @end example
706
707 @c
708 In effect, each input file is a scope, and all @code{\header},
709 @code{\midi}, and @code{\layout} blocks are scopes nested inside that
710 toplevel scope.
711
712 Both variables and scoping are implemented in the GUILE module system.
713 An anonymous Scheme module is attached to each scope.  An assignment of
714 the form:
715
716 @example
717 traLaLa = @{ c'4 d'4 @}
718 @end example
719
720 @noindent
721 is internally converted to a Scheme definition:
722
723 @example
724 (define traLaLa @var{Scheme value of `@code{... }'})
725 @end example
726
727 This means that LilyPond variables and Scheme variables may be freely
728 mixed.  In the following example, a music fragment is stored in the
729 variable @code{traLaLa}, and duplicated using Scheme.  The result is
730 imported in a @code{\score} block by means of a second variable
731 @code{twice}:
732
733 @lilypond[verbatim]
734 traLaLa = { c'4 d'4 }
735
736 %% dummy action to deal with parser lookahead
737 #(display "this needs to be here, sorry!")
738
739 #(define newLa (map ly:music-deep-copy
740   (list traLaLa traLaLa)))
741 #(define twice
742   (make-sequential-music newLa))
743
744 { \twice }
745 @end lilypond
746
747 @c Due to parser lookahead
748
749 In this example, the assignment happens after the parser has
750 verified that nothing interesting happens after
751 @code{traLaLa = @{ ... @}}.  Without the dummy statement in the
752 above example, the @code{newLa} definition is executed before
753 @code{traLaLa} is defined, leading to a syntax error.
754
755 The above example shows how to @q{export} music expressions from the
756 input to the Scheme interpreter.  The opposite is also possible.  By
757 wrapping a Scheme value in the function @code{ly:export}, a Scheme
758 value is interpreted as if it were entered in LilyPond syntax.
759 Instead of defining @code{\twice}, the example above could also have
760 been written as
761
762 @example
763 ...
764 @{ #(ly:export (make-sequential-music (list newLa))) @}
765 @end example
766
767 Scheme code is evaluated as soon as the parser encounters it.  To
768 define some Scheme code in a macro (to be called later), use
769 @ref{Void functions}, or
770
771 @example
772 #(define (nopc)
773   (ly:set-option 'point-and-click #f))
774
775 ...
776 #(nopc)
777 @{ c'4 @}
778 @end example
779
780 @knownissues
781
782 Mixing Scheme and LilyPond variables is not possible with the
783 @code{--safe} option.
784
785
786 @node Object properties
787 @subsection Object properties
788
789 Object properties are stored in LilyPond in the form of alist-chains,
790 which are lists of alists.  Properties are set by adding values at
791 the beginning of the property list.  Properties are read by retrieving
792 values from the alists.
793
794 Setting a new value for a property requires assigning a value to
795 the alist with both a key and a value.  The LilyPond syntax for doing
796 this is:
797
798 @example
799 \override Stem #'thickness = #2.6
800 @end example
801
802 This instruction adjusts the appearance of stems.  An alist entry
803 @code{'(thickness . 2.6)} is added to the property list of the
804 @code{Stem}
805 object.  @code{thickness} is measured relative to the thickness of
806 staff lines, so these stem lines will be @code{2.6} times the
807 width of staff lines.  This makes stems almost twice as thick as their
808 normal size.  To distinguish between variables defined in input files (like
809 @code{twentyFour} in the example above) and variables of internal
810 objects, we will call the latter @q{properties} and the former
811 @q{variables.}  So, the stem object has a @code{thickness} property,
812 while @code{twentyFour} is a variable.
813
814 @cindex properties vs. variables
815 @cindex variables vs. properties
816
817 @c  todo -- here we're getting interesting.  We're now introducing
818 @c  LilyPond variable types.  I think this deserves a section all
819 @c  its own
820
821 @node LilyPond compound variables
822 @subsection LilyPond compound variables
823
824 @subheading Offsets
825
826 Two-dimensional offsets (X and Y coordinates) are stored as @code{pairs}.
827 The @code{car} of the offset is the X coordinate, and the @code{cdr} is
828 the Y coordinate.
829
830 @example
831 \override TextScript #'extra-offset = #'(1 . 2)
832 @end example
833
834 This assigns the pair @code{(1 . 2)} to the @code{extra-offset}
835 property of the
836 TextScript object.  These numbers are measured in staff-spaces, so
837 this command moves the object 1 staff space to the right, and 2 spaces up.
838
839 Procedures for working with offsets are found in @file{scm/lily-library.scm}.
840
841 @subheading Extents
842
843 Pairs are also used to store intervals, which represent a range of numbers
844 from the minimum (the @code{car}) to the maximum (the @code{cdr}).
845 Intervals are used to store the X- and Y- extents of printable objects.
846 For X extents, the @code{car} is the left hand X coordinate, and the
847 @code{cdr} is the right hand X coordinate.  For Y extents, the @code{car}
848 is the bottom coordinate, and the @code{cdr} is the top coordinate.
849
850 Procedures for working with intervals are found in
851 @file{scm/lily-library.scm}.  These procedures should be used when possible
852 to ensure consistency of code.
853
854 @subheading Property alists
855
856 A property alist is a LilyPond data structure that is an alist whose
857 keys are properties and whose values are Scheme expressions that give
858 the desired value for the property.
859
860 LilyPond properties are Scheme symbols, such as @code{'thickness}.
861
862 @subheading Alist chains
863
864 An alist chain is a list containing property alists.
865
866 The set of all properties that will apply to a grob is typically
867 stored as an alist chain.  In order to find the value for a particular
868 property that a grob should have, each alist in the chain is searched in
869 order, looking for an entry containing the property key.  The first alist
870 entry found is returned, and the value is the property value.
871
872 The Scheme procedure @code{chain-assoc-get} is normally used to get
873 grob property values.
874
875 @node Internal music representation
876 @subsection Internal music representation
877
878 Internally, music is represented as a Scheme list.  The list contains
879 various elements that affect the printed output.  Parsing is the process
880 of converting music from the LilyPond input representation to the
881 internal Scheme representation.
882
883 When a music expression is parsed, it is converted into a set of
884 Scheme music objects.  The defining property of a music object is that
885 it takes up time.  The time it takes up is called its @emph{duration}.
886 Durations are expressed as a rational number that measures the length
887 of the music object in whole notes.
888
889 A music object has three kinds of types:
890 @itemize
891 @item
892 music name: Each music expression has a name.  For example, a note
893 leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
894 a @rinternals{SimultaneousMusic}.  A list of all expressions
895 available is in the Internals Reference manual, under
896 @rinternals{Music expressions}.
897
898 @item
899 @q{type} or interface: Each music name has several @q{types} or
900 interfaces, for example, a note is an @code{event}, but it is also a
901 @code{note-event}, a @code{rhythmic-event}, and a
902 @code{melodic-event}.  All classes of music are listed in the
903 Internals Reference, under
904 @rinternals{Music classes}.
905
906 @item
907 C++ object: Each music object is represented by an object of the C++
908 class @code{Music}.
909 @end itemize
910
911 The actual information of a music expression is stored in properties.
912 For example, a @rinternals{NoteEvent} has @code{pitch} and
913 @code{duration} properties that store the pitch and duration of that
914 note.  A list of all properties available can be found in the
915 Internals Reference, under @rinternals{Music properties}.
916
917 A compound music expression is a music object that contains other
918 music objects in its properties.  A list of objects can be stored in
919 the @code{elements} property of a music object, or a single @q{child}
920 music object in the @code{element} property.  For example,
921 @rinternals{SequentialMusic} has its children in @code{elements},
922 and @rinternals{GraceMusic} has its single argument in
923 @code{element}.  The body of a repeat is stored in the @code{element}
924 property of @rinternals{RepeatedMusic}, and the alternatives in
925 @code{elements}.
926
927 @node Building complicated functions
928 @section Building complicated functions
929
930 This section explains how to gather the information necessary
931 to create complicated music functions.
932
933 @menu
934 * Displaying music expressions::
935 * Music properties::
936 * Doubling a note with slurs (example)::
937 * Adding articulation to notes (example)::
938 @end menu
939
940 @node Displaying music expressions
941 @subsection Displaying music expressions
942
943 @cindex internal storage
944 @cindex displaying music expressions
945 @cindex internal representation, displaying
946 @cindex displayMusic
947 @funindex \displayMusic
948
949 When writing a music function it is often instructive to inspect how
950 a music expression is stored internally.  This can be done with the
951 music function @code{\displayMusic}
952
953 @example
954 @{
955   \displayMusic @{ c'4\f @}
956 @}
957 @end example
958
959 @noindent
960 will display
961
962 @example
963 (make-music
964   'SequentialMusic
965   'elements
966   (list (make-music
967           'EventChord
968           'elements
969           (list (make-music
970                   'NoteEvent
971                   'duration
972                   (ly:make-duration 2 0 1 1)
973                   'pitch
974                   (ly:make-pitch 0 0 0))
975                 (make-music
976                   'AbsoluteDynamicEvent
977                   'text
978                   "f")))))
979 @end example
980
981 By default, LilyPond will print these messages to the console along
982 with all the other messages.  To split up these messages and save
983 the results of @code{\display@{STUFF@}}, redirect the output to
984 a file.
985
986 @example
987 lilypond file.ly >display.txt
988 @end example
989
990 With a bit of reformatting, the above information is easier to read,
991
992 @example
993 (make-music 'SequentialMusic
994   'elements (list (make-music 'EventChord
995                     'elements (list (make-music 'NoteEvent
996                                       'duration (ly:make-duration 2 0 1 1)
997                                       'pitch (ly:make-pitch 0 0 0))
998                                     (make-music 'AbsoluteDynamicEvent
999                                       'text "f")))))
1000 @end example
1001
1002 A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
1003 and its inner expressions are stored as a list in its @code{'elements}
1004 property.  A note is represented as an @code{EventChord} expression,
1005 containing a @code{NoteEvent} object (storing the duration and
1006 pitch properties) and any extra information (in this case, an
1007 @code{AbsoluteDynamicEvent} with a @code{"f"} text property.
1008
1009
1010 @node Music properties
1011 @subsection Music properties
1012
1013 TODO -- make sure we delineate between @emph{music} properties,
1014 @emph{context} properties, and @emph{layout} properties.  These
1015 are potentially confusing.
1016
1017 The @code{NoteEvent} object is the first object of the
1018 @code{'elements} property of @code{someNote}.
1019
1020 @example
1021 someNote = c'
1022 \displayMusic \someNote
1023 ===>
1024 (make-music
1025   'EventChord
1026   'elements
1027   (list (make-music
1028           'NoteEvent
1029           'duration
1030           (ly:make-duration 2 0 1 1)
1031           'pitch
1032           (ly:make-pitch 0 0 0))))
1033 @end example
1034
1035 The @code{display-scheme-music} function is the function used by
1036 @code{\displayMusic} to display the Scheme representation of a music
1037 expression.
1038
1039 @example
1040 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1041 ===>
1042 (make-music
1043   'NoteEvent
1044   'duration
1045   (ly:make-duration 2 0 1 1)
1046   'pitch
1047   (ly:make-pitch 0 0 0))
1048 @end example
1049
1050 Then the note pitch is accessed through the @code{'pitch} property
1051 of the @code{NoteEvent} object,
1052
1053 @example
1054 #(display-scheme-music
1055    (ly:music-property (first (ly:music-property someNote 'elements))
1056                       'pitch))
1057 ===>
1058 (ly:make-pitch 0 0 0)
1059 @end example
1060
1061 The note pitch can be changed by setting this @code{'pitch} property,
1062
1063 @funindex \displayLilyMusic
1064
1065 @example
1066 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1067                           'pitch)
1068        (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
1069 \displayLilyMusic \someNote
1070 ===>
1071 d'
1072 @end example
1073
1074
1075 @node Doubling a note with slurs (example)
1076 @subsection Doubling a note with slurs (example)
1077
1078 Suppose we want to create a function that translates input like
1079 @code{a} into @code{a( a)}.  We begin by examining the internal
1080 representation of the desired result.
1081
1082 @example
1083 \displayMusic@{ a'( a') @}
1084 ===>
1085 (make-music
1086   'SequentialMusic
1087   'elements
1088   (list (make-music
1089           'EventChord
1090           'elements
1091           (list (make-music
1092                   'NoteEvent
1093                   'duration
1094                   (ly:make-duration 2 0 1 1)
1095                   'pitch
1096                   (ly:make-pitch 0 5 0))
1097                 (make-music
1098                   'SlurEvent
1099                   'span-direction
1100                   -1)))
1101         (make-music
1102           'EventChord
1103           'elements
1104           (list (make-music
1105                   'NoteEvent
1106                   'duration
1107                   (ly:make-duration 2 0 1 1)
1108                   'pitch
1109                   (ly:make-pitch 0 5 0))
1110                 (make-music
1111                   'SlurEvent
1112                   'span-direction
1113                   1)))))
1114 @end example
1115
1116 The bad news is that the @code{SlurEvent} expressions
1117 must be added @q{inside} the note (or more precisely,
1118 inside the @code{EventChord} expression).
1119
1120 Now we examine the input,
1121
1122 @example
1123 (make-music
1124   'SequentialMusic
1125   'elements
1126   (list (make-music
1127           'EventChord
1128           'elements
1129           (list (make-music
1130                   'NoteEvent
1131                   'duration
1132                   (ly:make-duration 2 0 1 1)
1133                   'pitch
1134                   (ly:make-pitch 0 5 0))))))
1135 @end example
1136
1137 So in our function, we need to clone this expression (so that we
1138 have two notes to build the sequence), add a @code{SlurEvent} to the
1139 @code{'elements} property of each one, and finally make a
1140 @code{SequentialMusic} with the two @code{EventChords}.
1141
1142 @example
1143 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1144          "Return: @{ note ( note ) @}.
1145          `note' is supposed to be an EventChord."
1146          (let ((note2 (ly:music-deep-copy note)))
1147            (set! (ly:music-property note 'elements)
1148                  (cons (make-music 'SlurEvent 'span-direction -1)
1149                        (ly:music-property note 'elements)))
1150            (set! (ly:music-property note2 'elements)
1151                  (cons (make-music 'SlurEvent 'span-direction 1)
1152                        (ly:music-property note2 'elements)))
1153            (make-music 'SequentialMusic 'elements (list note note2))))
1154 @end example
1155
1156
1157 @node Adding articulation to notes (example)
1158 @subsection Adding articulation to notes (example)
1159
1160 The easy way to add articulation to notes is to merge two music
1161 expressions into one context, as explained in
1162 @ruser{Creating contexts}.  However, suppose that we want to write
1163 a music function that does this.
1164
1165 A @code{$variable} inside the @code{#@{...#@}} notation is like
1166 a regular @code{\variable} in classical LilyPond notation.  We
1167 know that
1168
1169 @example
1170 @{ \music -. -> @}
1171 @end example
1172
1173 @noindent
1174 will not work in LilyPond.  We could avoid this problem by attaching
1175 the articulation to a fake note,
1176
1177 @example
1178 @{ << \music s1*0-.-> @}
1179 @end example
1180
1181 @noindent
1182 but for the sake of this example, we will learn how to do this in
1183 Scheme.  We begin by examining our input and desired output,
1184
1185 @example
1186 %  input
1187 \displayMusic c4
1188 ===>
1189 (make-music
1190   'EventChord
1191   'elements
1192   (list (make-music
1193           'NoteEvent
1194           'duration
1195           (ly:make-duration 2 0 1 1)
1196           'pitch
1197           (ly:make-pitch -1 0 0))))
1198 =====
1199 %  desired output
1200 \displayMusic c4->
1201 ===>
1202 (make-music
1203   'EventChord
1204   'elements
1205   (list (make-music
1206           'NoteEvent
1207           'duration
1208           (ly:make-duration 2 0 1 1)
1209           'pitch
1210           (ly:make-pitch -1 0 0))
1211         (make-music
1212           'ArticulationEvent
1213           'articulation-type
1214           "marcato")))
1215 @end example
1216
1217 We see that a note (@code{c4}) is represented as an @code{EventChord}
1218 expression, with a @code{NoteEvent} expression in its elements list.  To
1219 add a marcato articulation, an @code{ArticulationEvent} expression must
1220 be added to the elements property of the @code{EventChord}
1221 expression.
1222
1223 To build this function, we begin with
1224
1225 @example
1226 (define (add-marcato event-chord)
1227   "Add a marcato ArticulationEvent to the elements of `event-chord',
1228   which is supposed to be an EventChord expression."
1229   (let ((result-event-chord (ly:music-deep-copy event-chord)))
1230     (set! (ly:music-property result-event-chord 'elements)
1231           (cons (make-music 'ArticulationEvent
1232                   'articulation-type "marcato")
1233                 (ly:music-property result-event-chord 'elements)))
1234     result-event-chord))
1235 @end example
1236
1237 The first line is the way to define a function in Scheme: the function
1238 name is @code{add-marcato}, and has one variable called
1239 @code{event-chord}.  In Scheme, the type of variable is often clear
1240 from its name.  (this is good practice in other programming languages,
1241 too!)
1242
1243 @example
1244 "Add a marcato..."
1245 @end example
1246
1247 @noindent
1248 is a description of what the function does.  This is not strictly
1249 necessary, but just like clear variable names, it is good practice.
1250
1251 @example
1252 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1253 @end example
1254
1255 @code{let} is used to declare local variables.  Here we use one local
1256 variable, named @code{result-event-chord}, to which we give the value
1257 @code{(ly:music-deep-copy event-chord)}.  @code{ly:music-deep-copy} is
1258 a function specific to LilyPond, like all functions prefixed by
1259 @code{ly:}.  It is use to make a copy of a music
1260 expression.  Here we copy @code{event-chord} (the parameter of the
1261 function).  Recall that our purpose is to add a marcato to an
1262 @code{EventChord} expression.  It is better to not modify the
1263 @code{EventChord} which was given as an argument, because it may be
1264 used elsewhere.
1265
1266 Now we have a @code{result-event-chord}, which is a
1267 @code{NoteEventChord} expression and is a copy of
1268 @code{event-chord}.  We add the marcato to its @code{'elements}
1269 list property.
1270
1271 @example
1272 (set! place new-value)
1273 @end example
1274
1275 Here, what we want to set (the @q{place}) is the @code{'elements}
1276 property of @code{result-event-chord} expression.
1277
1278 @example
1279 (ly:music-property result-event-chord 'elements)
1280 @end example
1281
1282 @code{ly:music-property} is the function used to access music properties
1283 (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we
1284 see in the @code{\displayMusic} output above).  The new value is the
1285 former @code{'elements} property, with an extra item: the
1286 @code{ArticulationEvent} expression, which we copy from the
1287 @code{\displayMusic} output,
1288
1289 @example
1290 (cons (make-music 'ArticulationEvent
1291         'articulation-type "marcato")
1292       (ly:music-property result-event-chord 'elements))
1293 @end example
1294
1295 @code{cons} is used to add an element to a list without modifying
1296 the original list.  This is what we want: the same list as before,
1297 plus the new @code{ArticulationEvent} expression.  The order
1298 inside the @code{'elements} property is not important here.
1299
1300 Finally, once we have added the marcato articulation to its @code{elements}
1301 property, we can return @code{result-event-chord}, hence the last line of
1302 the function.
1303
1304 Now we transform the @code{add-marcato} function into a music
1305 function,
1306
1307 @example
1308 addMarcato = #(define-music-function (parser location event-chord)
1309                                      (ly:music?)
1310     "Add a marcato ArticulationEvent to the elements of `event-chord',
1311     which is supposed to be an EventChord expression."
1312     (let ((result-event-chord (ly:music-deep-copy event-chord)))
1313       (set! (ly:music-property result-event-chord 'elements)
1314             (cons (make-music 'ArticulationEvent
1315                     'articulation-type "marcato")
1316                   (ly:music-property result-event-chord 'elements)))
1317       result-event-chord))
1318 @end example
1319
1320 We may verify that this music function works correctly,
1321
1322 @example
1323 \displayMusic \addMarcato c4
1324 @end example
1325
1326
1327
1328
1329
1330 @ignore
1331 @menu
1332 * Tweaking with Scheme::
1333 @end menu
1334
1335 @c @nod e Tweaking with Scheme
1336 @c @sectio n Tweaking with Scheme
1337
1338 We have seen how LilyPond output can be heavily modified using
1339 commands like
1340 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
1341 we have even more power if we use Scheme.  For a full explanation
1342 of this, see the @ref{Scheme tutorial}, and
1343 @ref{Interfaces for programmers}.
1344
1345 We can use Scheme to simply @code{\override} commands,
1346
1347 TODO Find a simple example
1348 @c This isn't a valid example with skylining
1349 @c It works fine without padText  -td
1350 @end ignore
1351
1352 @ignore
1353 @lilypond[quote,verbatim,ragged-right]
1354 padText = #(define-music-function (parser location padding) (number?)
1355 #{
1356   \once \override TextScript #'padding = #$padding
1357 #})
1358
1359 \relative c''' {
1360   c4^"piu mosso" b a b
1361   \padText #1.8
1362   c4^"piu mosso" d e f
1363   \padText #2.6
1364   c4^"piu mosso" fis a g
1365 }
1366 @end lilypond
1367 @end ignore
1368
1369 @ignore
1370 We can use it to create new commands:
1371
1372 @c Check this is a valid example with skylining
1373 @c It is - 'padding still works
1374
1375
1376 @lilypond[quote,verbatim,ragged-right]
1377 tempoPadded = #(define-music-function (parser location padding tempotext)
1378   (number? string?)
1379 #{
1380   \once \override Score.MetronomeMark #'padding = $padding
1381   \tempo \markup { \bold $tempotext }
1382 #})
1383
1384 \relative c'' {
1385   \tempo \markup { "Low tempo" }
1386   c4 d e f g1
1387   \tempoPadded #4.0 #"High tempo"
1388   g4 f e d c1
1389 }
1390 @end lilypond
1391
1392
1393 Even music expressions can be passed in:
1394
1395 @lilypond[quote,verbatim,ragged-right]
1396 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1397 #{
1398   $x e8 a b $y b a e
1399 #})
1400
1401 \relative c''{
1402   \pattern c8 c8\f
1403   \pattern {d16 dis} { ais16-> b\p }
1404 }
1405 @end lilypond
1406 @end ignore