1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
4 Translation of GIT committish: 70aaf0159410169678942abd39eb13c876521437
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..
15 @translationof Scheme tutorial
20 @cindex Scheme, in einer LilyPond-Datei
22 @cindex Auswertung von Scheme-Code
24 LilyPond verwendet die Scheme-Programmiersprache sowohl als Teil
25 der Eingabesyntax als auch als internen Mechanismus, um Programmmodule
26 zusammenzufügen. Dieser Abschnitt ist ein sehr kurzer Überblick über
27 die Dateneingabe mit Scheme. Wenn Sie mehr über Scheme wissen wollen,
28 gehen Sie zu @uref{http://@/www@/.schemers@/.org}.
30 LilyPond benutzt die GNU Guile-Implementation von Scheme, die auf dem
31 @qq{R5RS}-Standard von Scheme basiert. Wenn Sie Scheme lernen wollen,
32 um es innerhalb von LilyPond zu benutzen, wird es nicht empfohlen,
33 mit einer anderen Implementation (die sich auf einen anderen
34 Standard bezieht) zu arbeiten. Information zu Guile findet sich
35 unter @uref{http://www.gnu.org/software/guile/}. Der
36 @qq{R5RS}-Standard von Scheme befindet sich unter der Adresse
37 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
41 * Einleitung in Scheme::
42 * Scheme in LilyPond::
43 * Komplizierte Funktionen erstellen::
46 @node Einleitung in Scheme
47 @section Einleitung in Scheme
48 @translationof Introduction to Scheme
50 Wir wollen mit einer Einführung in Scheme beginnen. Für diese kurze Einfürung
51 soll der GUILE-Interpreter genommen werden, um zu erforschen, wie die Sprache
52 funktioniert. Nach besserer Bekanntschaft mit Scheme soll gezeigt werden, wie
53 die Sprache in LilyPond-Dateien eingefügt werden kann.
58 * Einfache Scheme-Datentypen::
59 * Zusammengesetzte Scheme-Datentypen::
60 * Berechnungen in Scheme::
62 * Scheme-Konditionale::
65 @node Scheme-Sandkasten
66 @subsection Scheme-Sandkasten
67 @translationof Scheme sandbox
69 Die LilyPond-Installation enthält gleichzeitig auch die
70 Guile-Implementation von Scheme. Auf den meisten Systemen kann
71 man in einer Scheme-sandbox experimentieren, indem man ein
72 Kommandozeilen-Fenster öffnet und @code{guile} aufruft. Unter
73 einigen Systemen, insbesondere unter Windows, muss man evtl.
74 die Umgebungsvariable @code{GUILE_LOAD_PATH} auf das Verzeichnis
75 @code{../usr/shr/guile/1.8} innerhalb des LilyPond-Installationsverzeichnisses
76 setzen (der vollständige Pfad ist erklärt in @rlearning{Mehr Information}).
77 Alternativ können Windows-Benutzer auch einfach @qq{Ausführen} im
78 Startmenü wählen und @code{guile} schreiben.
80 Wenn guile einmal läuft, erhält man die Eingabeaufforderung von guile:
86 Man kann Scheme-Ausdrucke hier eingeben und mit Scheme experimentieren.
89 @node Scheme-Variablen
90 @subsection Scheme-Variablen
91 @translationof Scheme variables
93 Scheme-Variablen können jedlichen gültigen Scheme-Wert erhalten, auch
96 Scheme-Variablen werden mit @code{define} definiert:
103 Scheme-Variablen können an der Guile-Eingabeaufforderung ausgewertet werden,
104 indem man einfach die Variable eintippt.
112 Scheme-Variablen können auf dem Bildschirm ausgegeben werden, indem man
113 @code{display} zum Anzeigen benutzt:
120 Sowohl der Wert @code{2} als auch die Eingabeaufforderung @code{guile}
121 werden auf der gleichen Zeile ausgegeben. Das kann man vermeiden, indem
122 man eine @code{newline}-Prozedur für eine Leerzeile aufruft oder das
123 Zeichen für eine neue Zeile anzeigen lässt:
126 guile> (display a)(newline)
128 guile> (display a)(display "\n")
133 Wenn eine Variable einmal erstellt wurde, kann ihr Wert durch @code{set!}
137 guile> (set! a 12345)
143 @node Einfache Scheme-Datentypen
144 @subsection Einfache Scheme-Datentypen
145 @translationof Scheme simple data types
147 Das Grundlegendste an einer Sprache sind Daten: Zahlen, Zeichen,
148 Zeichenketten, Listen usw. Hier ist eine Liste der Datentypen, die für
149 LilyPond-Eingabedateien relevant sind.
152 @item Boolesche Variablen
153 Werte einer Booleschen Variable sind Wahr oder Falsch. Die Scheme-Entsprechung
154 für Wahr ist @code{#t} und für Falsch @code{#f}.
159 Zahlen werden wie üblich eingegeben, @code{1} ist die (ganze)
160 Zahl Eins, während @code{-1.5} eine Gleitkommazahl (also
161 eine nicht-ganze) ist.
164 Zeichenketten werden in doppelte Anführungszeichen gesetzt:
167 "Das ist eine Zeichenkette"
170 Zeichenketten können über mehrere Zeilen reichen:
179 und die Zeichen für eine neue Zeile am Ende jeder Zeile werden auch
180 in die Zeichenkette aufgenommen.
182 Zeichen für eine neue Zeile können auch hinzugefügt werden, indem man
183 @code{\n} in die Zeichenkette aufnimmt.
186 "das\nist eine\nmehrzeilige Zeichenkette"
189 Anführungszeichen und neue Zeilen können auch mit sogenannten
190 Fluchtsequenzen eingefügt werden. Die Zeichenkette
191 @code{a sagt "b"} wird wie folgt eingegeben:
199 Weitere zusätzliche Scheme-Datentypen, die hier nicht besprochen wurden,
200 finden sich in einer vollständigen Liste der Scheme-Datentypen in der
201 Guile-Referenzanleitung:
202 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
205 @node Zusammengesetzte Scheme-Datentypen
206 @subsection Zusammengesetzte Scheme-Datentypen
207 @translationof Scheme compound data types
209 Es gibt auch zusammengesetzte Datentypen in Scheme. Die Datentypen, die in
210 LilyPond häufig benutzt werden, beinhalten Paare, Listen, assoziative Listen
213 @subheading Paare (pair)
215 Der wichtigeste zusammengesetzte Datentyp in Scheme ist ein Paar (@code{pair}).
216 Wie aus dem Namen schon hervorgeht, besteht ein Paar aus zwei zusammengeschweißten
217 Werten. Die Prozedur um ein Paar zu erstellen ist @code{cons}.
225 Das Paar wird dargestellt als zwei Elemente, von Klammern umgeben
226 und durch Leerzeichen und einen Punkt (@code{.}) getrennt. Der Punkt ist
227 @emph{kein} Dezimalpunkt, sondern markiert die Gruppe als Paar.
229 Paare können auch wörtlich eingegeben werden, indem man ihnen voraus ein
230 einfaches Anführungszeichen (@code{'} setzt.
238 Beide Elemente eines Paares können beliebige gültige Scheme-Werte sein:
243 guile> '("blah-blah" . 3.1415926535)
244 ("blah-blah" . 3.1415926535)
248 Das erste Element eines Paares kann mit der Prozedur @code{car},
249 das zweite mit der Prozedur @code{cdr} angesprochen werden.
252 guile> (define mypair (cons 123 "hello there")
263 Achtung: @code{cdr} wird ausgeprochen wie "kudd-err", nach Sussman und
265 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
267 @subheading Listen (list)
269 Ein sehr häufiger Datentyp in Scheme ist die Liste (@emph{list}). Formal
270 gesehen wird eine Liste entweder als leere Liste definiert
271 (repräsentiert als @code{'()}), oder als ein Paar, dessen @code{cdr}
274 Es gibt viele Arten, Listen zu erstellen. Die vielleicht häufigste Methode
275 ist die @code{list}-Prozedur:
278 guile> (list 1 2 3 "abc" 17.5)
282 Wie man sehen kann, wird eine Liste dargestellt in Form der einzelnen
283 Elemente, getrennt durch ein Leerzeichen und als Gruppe in Klammern eingeschlossen.
284 Anders als bei einem Paar, befindet sich kein Punkt zwischen den Elementen.
286 Eine Liste kann auch als wörtliche Liste notiert werden, indem man die
287 enthaltenen Elemente in Klammern einschließt und ein einfaches Anführungszeichen
291 guile> '(17 23 "foo" "bar" "bazzle")
292 (17 23 "foo" "bar" "bazzle")
295 Listen haben eine zentrale Stellung in Scheme. Scheme wird als Dialekt
296 von Lisp angesehen, und das Wort @qq{lisp} steht für @qq{List Processing}.
297 Scheme-Ausdrücke sind immer Listen.
299 @subheading Assoziative Listen (alist)
301 Eine besonderer Listentyp ist die @emph{assoziative Liste} oder @emph{alist}.
302 Eine Alist wird benutzt, um Daten zum einfachen Abrufen zu speichern.
304 Alisten sind Listen, deren Elemente als Paare kommen. Der @code{car}-Teil
305 jedes Elements wird als @emph{Schlüssel} (key) bezeichnet, der
306 @code{cdr}-Teil jedes Elements wird @emph{Wert} (value) genannt.
307 Die Scheme-Prozedur @code{assoc} wird benutzt, um einen Eintrag aus einer
308 Aliste aufzurufen, und mit @code{cdr} wird sein Wert abgefragt:
311 guile> (define my-alist '((1 . "A") (2 . "B") (3 . "C")))
313 ((1 . "A") (2 . "B") (3 . "C"))
314 guile> (assoc 2 my-alist)
316 guile> (cdr (assoc 2 my-alist))
321 Alisten werden sehr viel in LilyPond genutzt, um Eigenschaften und
322 andere Daten zu speichern.
324 @subheading Hash-Tabellen (hash table)
326 Eine Datenstruktur, die ab und zu in LilyPond eingesetzt wird.
327 Eine Hash-Tabelle ähnelt einem Array, aber die Indexe des Arrays
328 können beliebige Scheme-Werte sein, nicht nur Integre.
330 Hash-Tabellen sind effizienter als Alisten, wenn man viele Daten
331 speichern will und die Daten sich oft ändern.
333 Die Syntax, mit der Hash-Tabellen erstellt werden, ist etwas komplex,
334 aber man kann Beispiele hierzu im LilyPond-Quellcode finden.
337 guile> (define h (make-hash-table 10))
340 guile> (hashq-set! h 'key1 "val1")
342 guile> (hashq-set! h 'key2 "val2")
344 guile> (hashq-set! h 3 "val3")
348 Werte werden aus den Hash-Tabellen mit @code{hashq-ref} ausgelesen.
351 guile> (hashq-ref h 3)
353 guile> (hashq-ref h 'key2)
358 Schlüssel und Werte werden als Paar mit @code{hashq-get-handle} ausgelesen.
359 Das ist die beste Art, weil hier @code{#f} ausgegeben wird, wenn ein
360 Schlüssel nicht gefunden werden kann.
363 guile> (hashq-get-handle h 'key1)
365 guile> (hashq-get-handle h 'frob)
371 @node Berechnungen in Scheme
372 @subsection Berechnungen in Scheme
373 @translationof Calculations in Scheme
376 We have been using lists all along. A calculation, like @code{(+ 1 2)}
377 is also a list (containing the symbol @code{+} and the numbers 1
378 and@tie{}2). Normally lists are interpreted as calculations, and the
379 Scheme interpreter substitutes the outcome of the calculation. To enter a
380 list, we stop the evaluation. This is done by quoting the list with a
381 quote @code{'} symbol. So, for calculations do not use a quote.
383 Inside a quoted list or pair, there is no need to quote anymore. The
384 following is a pair of symbols, a list of symbols and a list of lists
389 #'(staff clef key-signature)
394 Scheme kann verwendet werden, um Berechnungen durchzuführen. Es
395 verwendet eine @emph{Präfix}-Syntax. Um 1 und@tie{}2 zu addieren, muss
396 man @code{(+ 1 2)} schreiben, und nicht @math{1+2}, wie in traditioneller
404 Berechnungen können geschachtelt werden und das Ergebnis einer Berechnung
405 kann für eine neue Berechnung eingesetzt werden.
412 Diese Berechnungen sind Beispiele von Auswertungen. Ein Ausdruck
413 wie @code{(* 3 4)} wird durch seinen Wert @code{12} ersetzt.
415 Scheme-Berechnungen können zwischen Integren und Nich-Integren
416 unterscheiden. Integre Berechnungen sind exakt, während Nicht-Integre
417 nach den passenden Genauigkeitseinschränkungen berechnet werden:
426 Wenn der Scheme-Berechner einen Ausdruck antrifft, der eine Liste darstellt,
427 wird das erste Element der Liste als Prozedur behandelt, die mit
428 Argumenten des Restes der Liste ausgewertet werden. Darum sind alle
429 Operatoren in Scheme vorangestellt.
431 Wenn das erste Element eines Scheme-Ausdrucks, der eine Liste darstellt,
432 @emph{kein} Operator oder keine Prozedur ist, gibt es einen Fehler:
441 <unnamed port>:52:1: In expression (1 2 3):
442 <unnamed port>:52:1: Wrong type to apply: 1
447 Hier kann man sehen, dass Scheme versucht hat, 1 als einen Operator oder
448 eine Prozedur zu behandeln, was aber nicht möglich war. Darum der Fehler
449 "Wrong type to apply: 1".
451 Wenn man also eine Liste erstellen will, braucht man also einen Listen-Operator
452 oder man muss die Liste als wörtliches Zitat schreiben, sodass Scheme sie
453 nicht auszuwerten versucht.
463 Dieser Fehler kann durchaus vorkommen, wenn man Scheme unter LilyPond
467 The same assignment can be done in completely in Scheme as well,
470 #(define twentyFour (* 2 twelve))
473 @c this next section is confusing -- need to rewrite
475 The @emph{name} of a variable is also an expression, similar to a
476 number or a string. It is entered as
483 @cindex quoting in Scheme
485 The quote mark @code{'} prevents the Scheme interpreter from substituting
486 @code{24} for the @code{twentyFour}. Instead, we get the name
491 @node Scheme-Prozeduren
492 @subsection Scheme-Prozeduren
493 @translationof Scheme procedures
495 Scheme-Prozeduren sind ausführbare Scheme-Ausdrücke, die einen
496 Wert ausgeben, der das Resultat ihrer Ausführung darstellt. Sie können
497 auch Variablen verändern, die außerhalb dieser Prozedur definiert wurden.
499 @subheading Prozeduren definieren
501 Prozeduren werden in Scheme mit @code{define} definiert:
504 (define (function-name arg1 arg2 ... argn)
505 scheme-expression-that-gives-a-return-value)
508 Beispielsweise könnte man eine Prozedur definieren, die den Durchschnitt
512 guile> (define (average x y) (/ (+ x y) 2))
514 #<procedure average (x y)>
517 Wenn die Prozedur einmal definiert ist, wird sie aufgerufen indem man
518 die Prozedur und die Argumente in eine Liste schreibt. Man könnte also den
519 Durchschnitt von 3 und 12 berechnen:
522 guile> (average 3 12)
526 @subheading Prädikate
528 Scheme-Prozeduren, die Boolsche Werte ausgeben, werden oft als Prädikate
529 (predicate) bezeichnet. Es herrscht die Übereinkunft, Prädikat-Bezeichnungen
530 mit einem Fragezeichen abzuschließen:
533 guile> (define (less-than-ten? x) (< x 10))
534 guile> (less-than-ten? 9)
536 guile> (less-than-ten? 15)
540 @subheading Wiedergabe-Werte
542 Scheme-Prozeduren geben immer einen Wiedergabe-Wert (return value) aus, welcher
543 der Wert des letzten Ausdrucks ist, der in der Prozedur ausgeführt wurde. Der
544 Wiedergabewert kann ein beliebiger gültiger Scheme-Wert sein, auch eine
545 komplexe Datenstruktur oder eine Prozedur.
547 Manchmal würden Benutzer gerne mehrere Scheme-Ausdrucke in einer Prozedur haben.
548 Es gibt zwei Arten, wie merhere Ausdrücke kombiniert werden können. Die erste
549 Art ist die @code{begin}-Prozedur, der es ermöglicht, dass mehrere Ausdrücke
550 ausgewertet werden und den Wert des letzten Ausdrucks wiedergibt.
553 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
557 Die andere Art, mehrere Ausdrücke zu kombinieren, ist eine @code{let}-Umgebung.
558 In dieser Umgebung wird eine Serie von Verbindungen erstellt, und dann wird eine
559 Sequenz von Ausdrücken ausgewertet, die diese Bindungen einschließen können.
560 Der Wiedergabewert der let-Umgebung ist der Wiedergabewert der letzten Aussage
564 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
565 ... (+ (* x y) (/ z x)))
570 @node Scheme-Konditionale
571 @subsection Scheme-Konditionale
572 @translationof Scheme conditionals
576 Scheme hat eine @code{if}-Prozedur:
579 (if test-expression true-expression false-expression)
582 @var{test-expression} ist ein Ausdruck, der einen Booleschen
583 Wert zurück gibt. Wenn @var{test-expression} den Wert @code{#t}
584 ausgibt, gibt die if-Prozedur den Wert von @var{true-expression} aus,
585 in allen anderen Fällen den Wert von @var{false-expression}.
590 guile> (if (> a b) "a is greater than b" "a is not greater than b")
591 "a is not greater than b"
596 Eine andere konditionale Prozedur in Scheme ist
600 (cond (test-expression-1 result-expression-sequence-1)
601 (test-expression-2 result-expression-sequence-2)
603 (test-expression-n result-expression-sequence-n))
611 guile> (cond ((< a b) "a is less than b")
612 ... ((= a b) "a equals b")
613 ... ((> a b) "a is greater than b"))
619 @node Scheme in LilyPond
620 @section Scheme in LilyPond
621 @translationof Scheme in LilyPond
624 * LilyPond Scheme-Syntax::
625 * LilyPond-Variablen::
626 * Eingabe-Variablen und Scheme::
627 * Objekteigenschaften::
628 * Zusammengesetzte LilyPond-Variablen::
629 * Interne musikalische Repräsentation::
632 @node LilyPond Scheme-Syntax
633 @subsection LilyPond Scheme-Syntax
634 @translationof LilyPond Scheme syntax
636 Der Guile-Auswerter ist ein Teil von LilyPond, sodass Scheme also auch in
637 normale LilyPond-Eingabedateien eingefügt werden kann. Das Rautenzeichen
638 (@code{#}) wird benutzt, um dem LilyPond-Parser mitzuteilen, dass der nächste
639 Wert ein Scheme-Wert ist.
641 Wenn der Parser eine Raute sieht, wird der Eingabe-Code an den Guile-Auswerter
642 weitergereicht, der den Scheme-Ausdruck auswertet. Der Auswerter behandelt
643 die Eingabe so lange, bis er zum Ende eines Scheme-Ausdrucks kommt.
645 Scheme-Prozeduren können in LilyPond-Eingabedateien definiert werden:
648 #(define (average a b c) (/ (+ a b c) 3))
651 LilyPond-Kommentare (@code{%} oder @code{%@{ %@}}) können innerhalb
652 von Scheme-Code nicht benutzt werden. Kommentare in Guile Scheme
653 werden wie folgt notiert:
656 ; Einzeiliges Kommentar
659 Guile-Stil Blockkommentar (nicht schachtelbar)
660 Diese Kommentare werden von Scheme-Programmierern
661 selten benutzt und nie im Quellcode
666 Für den Rest dieses Abschnitts soll angenommen werden, dass die Daten in
667 einer LilyPond-Eingabedatei notiert werden sollen, sodass immer @code{#}
668 vor die Scheme-Ausdrücke gestellt wird.
670 Alle Scheme-Ausdrücke auf oberster Ebene in einer LilyPond-Eingabedatei
671 können in einen einzigen Scheme-Ausdruck zusammengefasst werden mit
681 @node LilyPond-Variablen
682 @subsection LilyPond-Variablen
683 @translationof LilyPond variables
685 LilyPond-Variablen werden intern als Scheme-Variablen gespeichert. Darum
699 Das bedeutet, dass Scheme-Ausdrücke auf LilyPond-Variablen zugreifen können.
700 Man könnte also schreiben:
703 Vierundzwanzig = #(* 2 Zwoelf)
707 was zur Folge hätte, dass die Zahl 24 in der LilyPond (und Scheme-)Variablen
708 @code{Vierundzwanzig} gespeichert wird.
711 @node Eingabe-Variablen und Scheme
712 @subsection Eingabe-Variablen und Scheme
713 @translationof Input variables and Scheme
715 Das Eingabeformat unterstützt die Notation von Variablen: Im folgenden
716 Beispiel wird ein musikalischer Ausdruck einer Variablen mit der
717 Bezeichnung @code{traLaLa} zugewiesen:
720 traLaLa = @{ c'4 d'4 @}
723 Variablen haben beschränkte Geltungsbereiche: im unten stehenden Beispiel
724 enthält auch die @code{\layout}-Umgebung eine @code{traLaLa}-Variable,
725 die sich aber von der @code{traLaLa}-Variable auf oberster Ebene unterscheidet:
728 traLaLa = @{ c'4 d'4 @}
729 \layout @{ traLaLa = 1.0 @}
732 Jede Eingabedatei ist solch ein Gültigkeitsbereich, und alle
733 @code{\header}-, @code{\midi}- und @code{\layout}-Umgebungen
734 sind Gültigkeitsbereiche, die in diesen obersten Gültigkeitsbereich
737 Sowohl Variablen als auch Gültigkeitsbereiche sind im Guile Modulsystem
738 eingebaut. Ein anonymes Scheme-Modul wird jedem Gültigkeitsbereich
739 angehängt. Eine Zuweisen in der Form von
742 traLaLa = @{ c'4 d'4 @}
746 wird intern in die Scheme-Definition
749 (define traLaLa @var{Scheme-Wert von `@code{... }'})
755 Das bedeutet, dass LilyPond-Variablen und Scheme-Variablen frei gemischt
756 werden können. Im folgenden Beispiel wird ein Notenfragment in der
757 Variable @code{traLaLa} gespeichert und mit Scheme dupliziert. Das
758 Resultat wird in eine @code{\score}-Umgebung mit einer weiteren
759 Variable @code{twice} importiert:
762 traLaLa = { c'4 d'4 }
764 %% dummy action to deal with parser lookahead
765 #(display "this needs to be here, sorry!")
767 #(define newLa (map ly:music-deep-copy
768 (list traLaLa traLaLa)))
770 (make-sequential-music newLa))
775 In diesem Beispiel geschieht die Zuweisung, nachdem der Parser sichergestellt
776 hat, dass nichts interessantes mehr nach @code{traLaLa = @{ ... @}} passiert.
777 Ohne die Dummy-Aussage in dem Beispiel würde die @code{newLa}-Definition ausgeführt,
778 bevor @code{traLaLa} definiert ist, was einen Syntax-Fehler hervorrufen würde.
780 Das Beispiel zeigt, wie man musikalische Ausdrücke aus der Eingabe in den
781 Scheme-Auswerter @qq{exportieren} kann. Es geht auch andersherum. Indem
782 man Scheme-Werten in die Funktion @code{ly:export} einschließt, wird ein
783 Scheme-Wert interpretiert, als ob er in LilyPond-Syntax eingeben wäre.
784 Anstatt @code{\twice} zu definieren, könne man also auch schreiben:
788 @{ #(ly:export (make-sequential-music (list newLa))) @}
791 Scheme-Code wird sofort interpretiert, wenn der Parser darauf stößt. Um
792 Scheme-Code als Makro zu definieren (das später aufgerufen werden soll),
793 muss man @ref{Leere Funktionen} benutzen oder
797 (ly:set-option 'point-and-click #f))
806 Scheme- und LilyPond-Variablen können nicht gemischt werden, wenn man die
807 @code{--safe}-Option benutzt.
810 @node Objekteigenschaften
811 @subsection Objekteigenschaften
812 @translationof Object properties
814 Objekteigenschaften werden in LilyPond in Form von Alisten-Ketten
815 gespeichert, also als Listen von Alisten. Eigenschaften werden
816 geändert, indem man Werte an den Anfang der Eigenschaftsliste
817 hinzufügt. Eigenschaften werden gelesen, indem Werte aus der
818 Aliste gelesen werden.
820 Ein neuer Wert für eine Eigenschaft kann gesetzt werden, indem man
821 der Alist einen Wert mit Schlüssel und dem Wert zuweist. Die
822 LilyPond-Syntax hierfür ist:
825 \override Stem #'thickness = #2.6
828 Diese Anweisung verändert die Erscheinung der Notenhälse. Der Alist-Eintrag
829 @code{'(thickness . 2.6)} wird zu der Eigenschaftsliste eines
830 @code{Stem}-(Hals-)Objektes hinzugefügt.
831 @code{thickness} wird relativ zu den Notenlinien errechnet, in diesem
832 Fall sind die Hälse also 2,6 mal so dick wie die Notenlinien. Dadurch
833 werden Hälse fast zweimal so dick dargestellt, wie sie normalerweise sind.
834 Um zwischen Variablen zu unterscheiden, die in den Quelldateien direkt
835 definiert werden (wie @code{Vierundzwanzig} weiter oben), und zwischen denen,
836 die für interne Objekte zuständig sind, werden hier die ersteren
837 @qq{Variablen} genannt, die letzteren dagegen @qq{Eigenschaften}.
838 Das Hals-Objekt hat also eine @code{thickness}-Eigenschaft, während
839 @code{Vierundzwanzig} eine Variable ist.
841 @cindex Eigenschaften versus Bezeichner
842 @cindex Bezeichner versus Eigenschaften
845 @node Zusammengesetzte LilyPond-Variablen
846 @subsection Zusammengesetzte LilyPond-Variablen
847 @translationof LilyPond compound variables
849 @subheading Abstände (offset)
853 Zweidimensionale Abstände (X- und Y-Koordinaten) werden
854 als @code{pairs} (Paare) gespeichert. Der @code{car}-Wert des
855 Abstands ist die X-Koordinate und der @code{cdr}-Wert die
859 \override TextScript #'extra-offset = #'(1 . 2)
862 Hierdurch wird das Paar @code{(1 . 2)} mit der Eigenschaft @code{extra-offset}
863 des TextScript-Objektes verknüpft. Diese Zahlen werden in
864 Systembreiten gemessen, so dass der Befehl das Objekt eine Systembreite
865 nach rechts verschiebt und zwei Breiten nach oben.
867 Prozeduren, um mit Abständen zu arbeiten, finden sich in @file{scm/lily-library.scm}.
869 @subheading Bereiche (extend)
871 Paare werden auch benutzt, um Intervalle zu speichern, die einen Zahlenbereich
872 vom Minimum (dem @code{car}) bis zum Maximum (dem @code{cdr}) darstellen.
873 Intervalle werden benutzt, um die X- und Y-Ausdehnung von druckbaren
874 Objekten zu speichern. Bei X-Ausdehnungen ist @code{car} die linke
875 X-Koordinate und @code{cdr} die rechte X-Koordinate. Für Y-Ausdehnungen
876 ist @code{car} die untere Koordinate und @code{cdr} die obere Koordinate.
878 Prozeduren, um mit Intervallen zu arbeiten, finden sich in
879 @file{scm/lily-library.scm}. Diese Prozeduren sollten benutzt, wenn es möglich
880 ist, um den Code konsistent zu halten.
882 @subheading Eigenschafts-Alisten (property alist)
884 Eine Eigenschafts-Aliste ist eine LilyPond-Datenstruktur, die eine Aliste
885 darstellt, deren Schlüssel Eigenschaften sind und deren Werte
886 Scheme-Ausdrücke sind, die den erwünschen Wert der Eigenschaft ausgeben.
888 LilyPond-Eigenschaften sind Scheme-Symbole, wie etwa @code{'thickness}
891 @subheading Alisten-Ketten (alist chains)
893 Eine Alisten-Kette ist eine Liste, die Eigenschafts-Alisten enthält.
895 Die Menge aller Eigenschaften, die sich auf einen Grob auswirken, wird
896 typischerweise in einer Alisten-Kette gespeichert. Um den Wert einer
897 bestimmten Eigenschaft zu finden, die ein Grob haben soll, wird jede
898 Liste in der Kette nach einander durchsucht, wobei nach einem Eintrag
899 geschaut wird, der den Eigenschaftsschlüssel enthält. Der erste
900 gefundene Alisten-Eintrag wird benutzt und dessen Wert ist der
901 Wert der Eigenschaft.
903 Die Scheme-Prozedur @code{chain-assoc-get} wird normalerweise benutzt,
904 um Grob-Eigenschaftenwerte zu erhalten.
907 @node Interne musikalische Repräsentation
908 @subsection Interne musikalische Repräsentation
909 @translationof Internal music representation
911 Intern werden Noten als Scheme-Liste dargestellt. Die Liste enthält
912 verschiedene Elemente, die die Druckausgabe beeinflussen. Parsen
913 nennt man den Prozess, der die Noten aus der LilyPond-Repräsentation
914 in die interne Scheme-Repräsentation überführt.
916 Wenn ein musikalischer Ausdruck geparst wird, wird er in eine Gruppe
917 von Scheme-Musikobjekten konvertiert. Die definierende Eigenschaft
918 eines Musikobjektes ist, dass es Zeit einnimmt. Die Zeit, die
919 ein Objekt braucht, wird Dauer (engl. @emph{duration}) genannt.
920 Dauern werden in rationalen Zahlen ausgedrückt, die die Länge des
921 Musikobjekts in Ganzen Noten angeben.
923 Ein Musikobjekt hat drei Typen:
927 Musikbezeichnung (music name): Jeder Musikausdruck hat eine Bezeichnung. Eine
928 Note beispielsweise erzeugt ein @rinternals{NoteEvent} und @code{\simultaneous}
929 produziert @rinternals{SimultaneousMusic}. Eine Liste aller möglichen
930 Ausdrücke findet sich in der Referenz der Interna, unter
931 @rinternals{Music expressions}.
934 Typ (type) oder Schnittstelle (interface): Jede Musikbezeichnung hat mehrere
935 Typen oder Schnittstellen, beispielsweise eine Note ist ein Ereignis (@code{event}),
936 aber auch ein Notenereignis (@code{note-event}), ein rhythmisches Ereignis
937 (@code{rhythmic-event}) und ein Melodieereignis (@code{melodic-event}).
938 Alle Musikklassen sind in der Referenz der Interna aufgelistet, unter
939 @rinternals{Music classes}.
942 C++-Objekt: Jedes Musikobjekt ist durch ein Objekt der C++-Klasse @code{Music}
946 Die eigentliche Information eines musikalischen Ausdrucks wird in Eigenschaften
947 gespeichert. Ein @rinternals{NoteEvent} beispielsweise hat die Eigenschaften
948 Tonhöhe (@code{pitch}) und Dauer (@code{duration}), die die Dauer und die
949 Tonhöhe der Note speichern. Eine Liste aller möglichen Eigenschaften findet
950 sich in der Referenz der Interna, unter
951 @rinternals{Music properties}.
953 Ein zusammengesetzter musikalischer Ausdruck ist ein Musikobjekt, das andere
954 Musikobjekte als Eigenschaften enthält. Eine Liste an Objekten kann in der
955 @code{elements}-Eigenschaft eines Musikobjekts bzw. ein einziges
956 Ableger-Musikelement in der @code{element}-Eigenschaft gespeichert werden.
957 @rinternals{SequentialMusic} beispielsweise hat sein einziges Argument in
958 @code{element}. Der Körper einer Wiederholung wird in der @code{element}-Eigenschaft
959 von @rinternals{RepeatedMusic} gespeichert, und die alternativen Endungen
963 @node Komplizierte Funktionen erstellen
964 @section Komplizierte Funktionen erstellen
965 @translationof Building complicated functions
967 Dieser Abschnitt zeigt, wie man Information zusammensucht,
968 um komplizierte musikalische Funktionen zu erstellen.
971 * Musikalische Funktionen darstellen::
972 * Eigenschaften von Musikobjekten::
973 * Verdoppelung einer Note mit Bindebögen (Beispiel)::
974 * Artikulationszeichen zu Noten hinzufügen (Beispiel)::
978 @node Musikalische Funktionen darstellen
979 @subsection Musikalische Funktionen darstellen
980 @translationof Displaying music expressions
982 @cindex interne Speicherung
983 @cindex Musikausdrücke anzeigen
984 @cindex Anzeigen von Musikausdrücken
986 @funindex displayMusic
987 @funindex \displayMusic
989 Wenn man eine musikalische Funktion erstellt, ist es oft
990 hilfreich sich anzuschauen, wie musikalische Funktionen
991 intern gespeichert werden. Das kann mit der Funktion
992 @code{\displayMusic} erreicht werden:
996 \displayMusic @{ c'4\f @}
1013 (ly:make-duration 2 0 1 1)
1015 (ly:make-pitch 0 0 0))
1017 'AbsoluteDynamicEvent
1022 Normalerweise gibt LilyPond diese Ausgabe auf der Konsole mit
1023 allen anderen Nachrichten aus. Um die wichtigen Nachrichten
1024 in einer Datei zu speichern, kann die Ausgabe in eine Datei
1028 lilypond file.ly >display.txt
1031 Mit etwas Umformatierung ist die gleiche Information sehr viel
1035 (make-music 'SequentialMusic
1036 'elements (list (make-music 'EventChord
1037 'elements (list (make-music 'NoteEvent
1038 'duration (ly:make-duration 2 0 1 1)
1039 'pitch (ly:make-pitch 0 0 0))
1040 (make-music 'AbsoluteDynamicEvent
1044 Eine musikalische @code{@{ ... @}}-Sequenz hat die Bezeichnung
1045 @code{SequentialMusic} und ihre inneren Ausdrücke werden als
1046 Liste in seiner @code{'elements}-Eigenschaft gespeichert. Eine
1047 Note ist als als ein @code{EventChord}-Ausdruck dargestellt,
1048 der ein @code{NoteEvent}-Objekt (welches Dauer und
1049 Tonhöhe speichert) und zusätzliche Information enthält (in
1050 diesem Fall ein @code{AbsoluteDynamicEvent} mit einer
1051 @code{"f"}-Text-Eigenschaft.
1054 @node Eigenschaften von Musikobjekten
1055 @subsection Eigenschaften von Musikobjekten
1056 @translationof Music properties
1058 Das @code{NoteEvent}-Objekt ist das erste Objekt der
1059 @code{'elements}-Eigenschaft von @code{someNote}.
1063 \displayMusic \someNote
1071 (ly:make-duration 2 0 1 1)
1073 (ly:make-pitch 0 0 0))))
1076 Die @code{display-scheme-music}-Funktion ist die Funktion, die von
1077 @code{\displayMusic} eingesetzt wird, um die Scheme-Repräsentation
1078 eines musikalischen Ausdrucks anzuzeigen.
1081 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1086 (ly:make-duration 2 0 1 1)
1088 (ly:make-pitch 0 0 0))
1091 Danach wird die Tonhöhe der Note von der @code{'pitch}-Eigenschaft
1092 des @code{NoteEvent}-Objektes gelesen:
1095 #(display-scheme-music
1096 (ly:music-property (first (ly:music-property someNote 'elements))
1099 (ly:make-pitch 0 0 0)
1102 Die Tonhöhe einer Note kann geändert werden, indem man diese
1103 @code{'pitch}-Eigenschaft umdefiniert:
1105 @funindex \displayLilyMusic
1106 @funindex displayLilyMusic
1109 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1111 (ly:make-pitch 0 1 0)) ;; Die Tonhöhen auf d' verändern.
1112 \displayLilyMusic \someNote
1118 @node Verdoppelung einer Note mit Bindebögen (Beispiel)
1119 @subsection Verdoppelung einer Note mit Bindebögen (Beispiel)
1120 @translationof Doubling a note with slurs (example)
1122 In diesem Abschnitt soll gezeigt, werden, wie man eine
1123 Funktion erstellt, die eine Eingabe wie @code{a}
1124 nach @code{a( a)} umdefiniert. Dazu wird zuerst die
1125 interne Repräsentation der Musik betrachtet, die
1126 das Endergebnis darstellt:
1129 \displayMusic@{ a'( a') @}
1140 (ly:make-duration 2 0 1 1)
1142 (ly:make-pitch 0 5 0))
1153 (ly:make-duration 2 0 1 1)
1155 (ly:make-pitch 0 5 0))
1162 Eine schlechte Nachricht ist, dass die
1163 @code{SlurEvent}-Ausdrücke @qq{innerhalb}
1164 der Noten (bzw. innerhalb der
1165 @code{EventChord}-Ausdrücke) hinzugefügt werden müssen.
1167 Jetzt folgt eine Betrachtung der Eingabe:
1179 (ly:make-duration 2 0 1 1)
1181 (ly:make-pitch 0 5 0))))))
1184 In der gewünschten Funktion muss also dieser Ausdruck
1185 kopiert werden (sodass zwei Noten vorhanden sind, die
1186 eine Sequenz bilden), dann müssen @code{SlurEvent}
1187 zu der @code{'elements}-Eigenschaft jeder Noten hinzugefügt
1188 werden, und schließlich muss eine @code{SequentialMusic}
1189 mit den beiden @code{EventChords} erstellt werden.
1192 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1193 "Return: @{ note ( note ) @}.
1194 `note' is supposed to be an EventChord."
1195 (let ((note2 (ly:music-deep-copy note)))
1196 (set! (ly:music-property note 'elements)
1197 (cons (make-music 'SlurEvent 'span-direction -1)
1198 (ly:music-property note 'elements)))
1199 (set! (ly:music-property note2 'elements)
1200 (cons (make-music 'SlurEvent 'span-direction 1)
1201 (ly:music-property note2 'elements)))
1202 (make-music 'SequentialMusic 'elements (list note note2))))
1206 @node Artikulationszeichen zu Noten hinzufügen (Beispiel)
1207 @subsection Artikulationszeichen zu Noten hinzufügen (Beispiel)
1208 @translationof Adding articulation to notes (example)
1210 Am einfachsten können Artikulationszeichen zu Noten
1211 hinzugefügt werden, indem man zwei musikalische Funktionen
1212 in einen Kontext einfügt, wie erklärt in
1213 @ruser{Kontexte erstellen}. Hier soll jetzt eine musikalische
1214 Funktion entwickelt werden, die das vornimmt.
1216 Eine @code{$variable} innerhalb von @code{#@{...#@}} ist das
1217 gleiche wie die normale Befehlsform @code{\variable} in
1218 üblicher LilyPond-Notation. Es ist bekannt dass
1225 in LilyPond nicht funktioniert. Das Problem könnte vermieden
1226 werden, indem das Artikulationszeichen an eine Pseudonote
1230 @{ << \music s1*0-.-> @}
1234 aber in diesem Beispiel soll gezeigt werden, wie man das in
1235 Scheme vornimmt. Zunächst wird die Eingabe und die gewünschte
1248 (ly:make-duration 2 0 1 1)
1250 (ly:make-pitch -1 0 0))))
1252 % gewünschte Ausgabe
1261 (ly:make-duration 2 0 1 1)
1263 (ly:make-pitch -1 0 0))
1270 Dabei ist zu sehen, dass eine Note (@code{c4}) als @code{EventChord}
1271 repräsentiert ist, mit einem @code{NoteEvent}-Ausdruck in ihrer
1272 Elementenliste. Um eine Marcato-Artikulation hinzuzufügen, muss
1273 ein @code{ArticulationEvent}-Ausdruck zu der Elementeigenschaft
1274 des @code{EventChord}-Ausdrucks hinzugefügt werden.
1276 Um diese Funktion zu bauen, wird folgendermaßen begonnen:
1279 (define (add-marcato event-chord)
1280 "Add a marcato ArticulationEvent to the elements of `event-chord',
1281 which is supposed to be an EventChord expression."
1282 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1283 (set! (ly:music-property result-event-chord 'elements)
1284 (cons (make-music 'ArticulationEvent
1285 'articulation-type "marcato")
1286 (ly:music-property result-event-chord 'elements)))
1287 result-event-chord))
1290 Die erste Zeile definiert eine Funktion in Scheme: Die Bezeichnung
1291 der Funktion ist @code{add-marcato} und sie hat eine Variable
1292 mit der Bezeichnung @code{event-chord}. In Scheme geht der Typ
1293 einer Variable oft direkt aus der Bezeichnung hervor (das ist auch
1294 eine gute Methode für andere Programmiersprachen).
1301 ist eine (englische) Beschreibung, was diese Funktion tut. Sie ist
1302 nicht unbedingt notwendig, aber genauso wie klare Variablen-Bezeichnungen
1303 ist auch das eine gute Methode.
1306 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1309 @code{let} wird benutzt, um die lokalen Variablen zu definieren. Hier
1310 wird eine lokale Variable benutzt: @code{result-event-chord}. Sie erhält
1311 den Wert @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy}
1312 ist eine LilyPond-spezifische Funktion, die wie alle Funktionen mit dem
1313 Präfix @code{ly:} versehen ist. Sie wird benutzt, um eine Kopie eines
1314 musikalischen Ausdrucks anzufertigen. Hier wird @code{event-chord}
1315 (der Parameter der Funktion) kopiert. Die Funktion soll ja nur ein
1316 Artikulationszeichen an einen @code{EventChord} gehängt werden, deshalb ist es besser,
1317 den @code{EventChord}, der als Argument gegeben wurde, nicht zu
1318 verändern, weil er woanders benutzt werden könnte.
1320 Jetzt gibt es @code{result-event-chord}, wobei es sich um einen
1321 @code{NoteEventChord}-Ausdruck handelt, welcher gleichzeitig eine Kopie
1322 von @code{event-chord} ist. Das Makro wird seiner Eigenschaftsliste
1326 (set! place new-value)
1329 Was in diesem Fall @qq{gesetzt} werden soll (@qq{place}) ist die
1330 @q{elements}-Eigenschaft des @code{result-event-chord}-Ausdrucks.
1333 (ly:music-property result-event-chord 'elements)
1336 @code{ly:music-property} ist die Funktion, mit der musikalische
1337 Eigenschaften erreicht werden können (die @code{'elements},
1338 @code{'duration}, @code{'pitch} usw., die in der Ausgabe von
1339 @code{\displayMusic} weiter oben angezeigt werden). Der neue
1340 Wert ist, was ehemals die Elementeigenschaft war, mit einem
1341 zusätzlichen Element: dem @code{ArticulationEvent}-Ausdruck,
1342 der aus der Ausgabe von
1343 @code{\displayMusic} kopiert werden kann:
1346 (cons (make-music 'ArticulationEvent
1347 'articulation-type "marcato")
1348 (ly:music-property result-event-chord 'elements))
1351 @code{cons} wird benutzt, um ein Element zu einer Liste hinzuzufügen,
1352 ohne dass die originale Liste verändert wird. Das ist es, was die
1353 Funktion tun soll: die gleiche Liste, aber mit dem neuen
1354 @code{ArticulationEvent}-Ausdruck. Die Reihenfolge innerhalb
1355 der Elementeeigenschaft ist hier nicht relevant.
1357 Wenn schließlich die Marcato-Artikulation zu der entsprechenden
1358 @code{elements}-Eigenschaft hinzugefügt ist, kann
1359 @code{result-event-chord} ausgegeben werden, darum die letzte Zeile
1362 Jetzt wird die @code{add-marcato}-Funktion in eine musikalische
1363 Funktion umgewandelt:
1366 addMarcato = #(define-music-function (parser location event-chord)
1368 "Add a marcato ArticulationEvent to the elements of `event-chord',
1369 which is supposed to be an EventChord expression."
1370 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1371 (set! (ly:music-property result-event-chord 'elements)
1372 (cons (make-music 'ArticulationEvent
1373 'articulation-type "marcato")
1374 (ly:music-property result-event-chord 'elements)))
1375 result-event-chord))
1378 Eine Überprüfung, dass die Funktion richtig arbeitet, geschieht
1382 \displayMusic \addMarcato c4
1393 * Optimierungen mit Scheme::
1396 @c node Optimierungen mit Scheme
1397 @c appendixsec Optimierungen mit Scheme
1398 @c translationof Tweaking with Scheme
1400 Wir haben gesehen wie LilyPond-Eingabe massiv beeinflusst
1401 werden kann, indem Befehle wie etwa
1402 @code{\override TextScript #'extra-offset = ( 1 . -1)}
1403 benutzt werden. Aber es wurde gezeigt, dass Scheme noch
1404 mächtiger ist. Eine bessere Erklärung findet sich in der@ref{Scheme-Übung} und in
1405 @ruser{Schnittstellen für Programmierer}.
1407 Scheme kann auch in einfachen @code{\override}-Befehlen
1410 TODO Find a simple example
1411 @c This isn't a valid example with skylining
1412 @c It works fine without padText -td
1415 @lilypond[quote,verbatim,ragged-right]
1416 padText = #(define-music-function (parser location padding) (number?)
1418 \once \override TextScript #'padding = #$padding
1422 c4^"piu mosso" b a b
1424 c4^"piu mosso" d e f
1426 c4^"piu mosso" fis a g
1431 Es kann auch benutzt werden, um Befehle zu erstellen:
1433 @c Check this is a valid example with skylining
1434 @c It is - 'padding still works
1436 @lilypond[quote,verbatim,ragged-right]
1437 tempoPadded = #(define-music-function (parser location padding tempotext)
1440 \once \override Score.MetronomeMark #'padding = $padding
1441 \tempo \markup { \bold $tempotext }
1445 \tempo \markup { "Low tempo" }
1447 \tempoPadded #4.0 #"High tempo"
1452 Sogar ganze Musikausdrücke können eingefügt werden:
1454 @lilypond[quote,verbatim,ragged-right]
1455 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1462 \pattern {d16 dis} { ais16-> b\p }