1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
4 Translation of GIT committish: e5a609e373eae846857f9a6d70a402a3d42b7d94
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/share/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 Es gibt auch eine direkte Scheme-Umgebung mit allen LilyPond-Voreinstellungen,
81 die man auf der Kommandozeile mit folgendem Befehl aufrufen kann:
84 lilypond scheme-sandbox
88 Wenn guile einmal läuft, erhält man die Eingabeaufforderung von guile:
94 Man kann Scheme-Ausdrucke hier eingeben und mit Scheme experimentieren.
95 Siehe die Datei @file{ly/scheme-sandbox.ly} zu Information, wie man
96 die GNU readline-Bibliothek benutzen kann, um bessere Scheme-Formatierung
97 der Kommandozeile zu erhalten. Wenn die readline-Bibliothek für interaktive
98 Guile-Sitzungen außerhalb von LilyPond schon aktiviert ist, sollte es auch
99 in der Sandbox funktionieren.
102 @node Scheme-Variablen
103 @subsection Scheme-Variablen
104 @translationof Scheme variables
106 Scheme-Variablen können jedlichen gültigen Scheme-Wert erhalten, auch
109 Scheme-Variablen werden mit @code{define} definiert:
116 Scheme-Variablen können an der Guile-Eingabeaufforderung ausgewertet werden,
117 indem man einfach die Variable eintippt.
125 Scheme-Variablen können auf dem Bildschirm ausgegeben werden, indem man
126 @code{display} zum Anzeigen benutzt:
133 Sowohl der Wert @code{2} als auch die Eingabeaufforderung @code{guile}
134 werden auf der gleichen Zeile ausgegeben. Das kann man vermeiden, indem
135 man eine @code{newline}-Prozedur für eine Leerzeile aufruft oder das
136 Zeichen für eine neue Zeile anzeigen lässt:
139 guile> (display a)(newline)
141 guile> (display a)(display "\n")
146 Wenn eine Variable einmal erstellt wurde, kann ihr Wert durch @code{set!}
150 guile> (set! a 12345)
156 @node Einfache Scheme-Datentypen
157 @subsection Einfache Scheme-Datentypen
158 @translationof Scheme simple data types
160 Das Grundlegendste an einer Sprache sind Daten: Zahlen, Zeichen,
161 Zeichenketten, Listen usw. Hier ist eine Liste der Datentypen, die für
162 LilyPond-Eingabedateien relevant sind.
165 @item Boolesche Variablen
166 Werte einer Booleschen Variable sind Wahr oder Falsch. Die Scheme-Entsprechung
167 für Wahr ist @code{#t} und für Falsch @code{#f}.
172 Zahlen werden wie üblich eingegeben, @code{1} ist die (ganze)
173 Zahl Eins, während @w{@code{-1.5}} eine Gleitkommazahl (also
174 eine nicht-ganze) ist.
177 Zeichenketten werden in doppelte Anführungszeichen gesetzt:
180 "Das ist eine Zeichenkette"
183 Zeichenketten können über mehrere Zeilen reichen:
192 und die Zeichen für eine neue Zeile am Ende jeder Zeile werden auch
193 in die Zeichenkette aufgenommen.
195 Zeichen für eine neue Zeile können auch hinzugefügt werden, indem man
196 @code{\n} in die Zeichenkette aufnimmt.
199 "das\nist eine\nmehrzeilige Zeichenkette"
202 Anführungszeichen und neue Zeilen können auch mit sogenannten
203 Fluchtsequenzen eingefügt werden. Die Zeichenkette
204 @code{a sagt "b"} wird wie folgt eingegeben:
212 Weitere zusätzliche Scheme-Datentypen, die hier nicht besprochen wurden,
213 finden sich in einer vollständigen Liste der Scheme-Datentypen in der
214 Guile-Referenzanleitung:
215 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
218 @node Zusammengesetzte Scheme-Datentypen
219 @subsection Zusammengesetzte Scheme-Datentypen
220 @translationof Scheme compound data types
222 Es gibt auch zusammengesetzte Datentypen in Scheme. Die Datentypen, die in
223 LilyPond häufig benutzt werden, beinhalten Paare, Listen, assoziative Listen
226 @subheading Paare (pair)
228 Der wichtigeste zusammengesetzte Datentyp in Scheme ist ein Paar (@code{pair}).
229 Wie aus dem Namen schon hervorgeht, besteht ein Paar aus zwei zusammengeschweißten
230 Werten. Die Prozedur um ein Paar zu erstellen ist @code{cons}.
238 Das Paar wird dargestellt als zwei Elemente, von Klammern umgeben
239 und durch Leerzeichen und einen Punkt (@code{.}) getrennt. Der Punkt ist
240 @emph{kein} Dezimalpunkt, sondern markiert die Gruppe als Paar.
242 Paare können auch wörtlich eingegeben werden, indem man ihnen voraus ein
243 einfaches Anführungszeichen (@code{'} setzt.
251 Beide Elemente eines Paares können beliebige gültige Scheme-Werte sein:
256 guile> '("blah-blah" . 3.1415926535)
257 ("blah-blah" . 3.1415926535)
261 Das erste Element eines Paares kann mit der Prozedur @code{car},
262 das zweite mit der Prozedur @code{cdr} angesprochen werden.
265 guile> (define mypair (cons 123 "hello there")
276 Achtung: @code{cdr} wird ausgeprochen wie "kudd-err", nach Sussman und
278 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
280 @subheading Listen (list)
282 Ein sehr häufiger Datentyp in Scheme ist die Liste (@emph{list}). Formal
283 gesehen wird eine Liste entweder als leere Liste definiert
284 (repräsentiert als @code{'()}), oder als ein Paar, dessen @code{cdr}
287 Es gibt viele Arten, Listen zu erstellen. Die vielleicht häufigste Methode
288 ist die @code{list}-Prozedur:
291 guile> (list 1 2 3 "abc" 17.5)
295 Wie man sehen kann, wird eine Liste dargestellt in Form der einzelnen
296 Elemente, getrennt durch ein Leerzeichen und als Gruppe in Klammern eingeschlossen.
297 Anders als bei einem Paar, befindet sich kein Punkt zwischen den Elementen.
299 Eine Liste kann auch als wörtliche Liste notiert werden, indem man die
300 enthaltenen Elemente in Klammern einschließt und ein einfaches Anführungszeichen
304 guile> '(17 23 "foo" "bar" "bazzle")
305 (17 23 "foo" "bar" "bazzle")
308 Listen haben eine zentrale Stellung in Scheme. Scheme wird als Dialekt
309 von Lisp angesehen, und das Wort @qq{lisp} steht für @qq{List Processing}.
310 Scheme-Ausdrücke sind immer Listen.
312 @subheading Assoziative Listen (alist)
314 Eine besonderer Listentyp ist die @emph{assoziative Liste} oder @emph{alist}.
315 Eine Alist wird benutzt, um Daten zum einfachen Abrufen zu speichern.
317 Alisten sind Listen, deren Elemente als Paare kommen. Der @code{car}-Teil
318 jedes Elements wird als @emph{Schlüssel} (key) bezeichnet, der
319 @code{cdr}-Teil jedes Elements wird @emph{Wert} (value) genannt.
320 Die Scheme-Prozedur @code{assoc} wird benutzt, um einen Eintrag aus einer
321 Aliste aufzurufen, und mit @code{cdr} wird sein Wert abgefragt:
324 guile> (define my-alist '((1 . "A") (2 . "B") (3 . "C")))
326 ((1 . "A") (2 . "B") (3 . "C"))
327 guile> (assoc 2 my-alist)
329 guile> (cdr (assoc 2 my-alist))
334 Alisten werden sehr viel in LilyPond genutzt, um Eigenschaften und
335 andere Daten zu speichern.
337 @subheading Hash-Tabellen (hash table)
339 Eine Datenstruktur, die ab und zu in LilyPond eingesetzt wird.
340 Eine Hash-Tabelle ähnelt einem Array, aber die Indexe des Arrays
341 können beliebige Scheme-Werte sein, nicht nur Integre.
343 Hash-Tabellen sind effizienter als Alisten, wenn man viele Daten
344 speichern will und die Daten sich oft ändern.
346 Die Syntax, mit der Hash-Tabellen erstellt werden, ist etwas komplex,
347 aber man kann Beispiele hierzu im LilyPond-Quellcode finden.
350 guile> (define h (make-hash-table 10))
353 guile> (hashq-set! h 'key1 "val1")
355 guile> (hashq-set! h 'key2 "val2")
357 guile> (hashq-set! h 3 "val3")
361 Werte werden aus den Hash-Tabellen mit @code{hashq-ref} ausgelesen.
364 guile> (hashq-ref h 3)
366 guile> (hashq-ref h 'key2)
371 Schlüssel und Werte werden als Paar mit @code{hashq-get-handle} ausgelesen.
372 Das ist die beste Art, weil hier @code{#f} ausgegeben wird, wenn ein
373 Schlüssel nicht gefunden werden kann.
376 guile> (hashq-get-handle h 'key1)
378 guile> (hashq-get-handle h 'frob)
384 @node Berechnungen in Scheme
385 @subsection Berechnungen in Scheme
386 @translationof Calculations in Scheme
389 We have been using lists all along. A calculation, like @code{(+ 1 2)}
390 is also a list (containing the symbol @code{+} and the numbers 1
391 and@tie{}2). Normally lists are interpreted as calculations, and the
392 Scheme interpreter substitutes the outcome of the calculation. To enter a
393 list, we stop the evaluation. This is done by quoting the list with a
394 quote @code{'} symbol. So, for calculations do not use a quote.
396 Inside a quoted list or pair, there is no need to quote anymore. The
397 following is a pair of symbols, a list of symbols and a list of lists
402 #'(staff clef key-signature)
407 Scheme kann verwendet werden, um Berechnungen durchzuführen. Es
408 verwendet eine @emph{Präfix}-Syntax. Um 1 und@tie{}2 zu addieren, muss
409 man @code{(+ 1 2)} schreiben, und nicht @math{1+2}, wie in traditioneller
417 Berechnungen können geschachtelt werden und das Ergebnis einer Berechnung
418 kann für eine neue Berechnung eingesetzt werden.
425 Diese Berechnungen sind Beispiele von Auswertungen. Ein Ausdruck
426 wie @code{(* 3 4)} wird durch seinen Wert @code{12} ersetzt.
428 Scheme-Berechnungen können zwischen Integren und Nich-Integren
429 unterscheiden. Integre Berechnungen sind exakt, während Nicht-Integre
430 nach den passenden Genauigkeitseinschränkungen berechnet werden:
439 Wenn der Scheme-Berechner einen Ausdruck antrifft, der eine Liste darstellt,
440 wird das erste Element der Liste als Prozedur behandelt, die mit
441 Argumenten des Restes der Liste ausgewertet werden. Darum sind alle
442 Operatoren in Scheme vorangestellt.
444 Wenn das erste Element eines Scheme-Ausdrucks, der eine Liste darstellt,
445 @emph{kein} Operator oder keine Prozedur ist, gibt es einen Fehler:
454 <unnamed port>:52:1: In expression (1 2 3):
455 <unnamed port>:52:1: Wrong type to apply: 1
460 Hier kann man sehen, dass Scheme versucht hat, 1 als einen Operator oder
461 eine Prozedur zu behandeln, was aber nicht möglich war. Darum der Fehler
462 "Wrong type to apply: 1".
464 Wenn man also eine Liste erstellen will, braucht man also einen Listen-Operator
465 oder man muss die Liste als wörtliches Zitat schreiben, sodass Scheme sie
466 nicht auszuwerten versucht.
476 Dieser Fehler kann durchaus vorkommen, wenn man Scheme unter LilyPond
480 The same assignment can be done in completely in Scheme as well,
483 #(define twentyFour (* 2 twelve))
486 @c this next section is confusing -- need to rewrite
488 The @emph{name} of a variable is also an expression, similar to a
489 number or a string. It is entered as
496 @cindex quoting in Scheme
498 The quote mark @code{'} prevents the Scheme interpreter from substituting
499 @code{24} for the @code{twentyFour}. Instead, we get the name
504 @node Scheme-Prozeduren
505 @subsection Scheme-Prozeduren
506 @translationof Scheme procedures
508 Scheme-Prozeduren sind ausführbare Scheme-Ausdrücke, die einen
509 Wert ausgeben, der das Resultat ihrer Ausführung darstellt. Sie können
510 auch Variablen verändern, die außerhalb dieser Prozedur definiert wurden.
512 @subheading Prozeduren definieren
514 Prozeduren werden in Scheme mit @code{define} definiert:
517 (define (function-name arg1 arg2 ... argn)
518 scheme-expression-that-gives-a-return-value)
521 Beispielsweise könnte man eine Prozedur definieren, die den Durchschnitt
525 guile> (define (average x y) (/ (+ x y) 2))
527 #<procedure average (x y)>
530 Wenn die Prozedur einmal definiert ist, wird sie aufgerufen indem man
531 die Prozedur und die Argumente in eine Liste schreibt. Man könnte also den
532 Durchschnitt von 3 und 12 berechnen:
535 guile> (average 3 12)
539 @subheading Prädikate
541 Scheme-Prozeduren, die Boolsche Werte ausgeben, werden oft als Prädikate
542 (predicate) bezeichnet. Es herrscht die Übereinkunft, Prädikat-Bezeichnungen
543 mit einem Fragezeichen abzuschließen:
546 guile> (define (less-than-ten? x) (< x 10))
547 guile> (less-than-ten? 9)
549 guile> (less-than-ten? 15)
553 @subheading Wiedergabe-Werte
555 Scheme-Prozeduren geben immer einen Wiedergabe-Wert (return value) aus, welcher
556 der Wert des letzten Ausdrucks ist, der in der Prozedur ausgeführt wurde. Der
557 Wiedergabewert kann ein beliebiger gültiger Scheme-Wert sein, auch eine
558 komplexe Datenstruktur oder eine Prozedur.
560 Manchmal würden Benutzer gerne mehrere Scheme-Ausdrucke in einer Prozedur haben.
561 Es gibt zwei Arten, wie merhere Ausdrücke kombiniert werden können. Die erste
562 Art ist die @code{begin}-Prozedur, der es ermöglicht, dass mehrere Ausdrücke
563 ausgewertet werden und den Wert des letzten Ausdrucks wiedergibt.
566 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
570 Die andere Art, mehrere Ausdrücke zu kombinieren, ist eine @code{let}-Umgebung.
571 In dieser Umgebung wird eine Serie von Verbindungen erstellt, und dann wird eine
572 Sequenz von Ausdrücken ausgewertet, die diese Bindungen einschließen können.
573 Der Wiedergabewert der let-Umgebung ist der Wiedergabewert der letzten Aussage
577 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
578 ... (+ (* x y) (/ z x)))
583 @node Scheme-Konditionale
584 @subsection Scheme-Konditionale
585 @translationof Scheme conditionals
589 Scheme hat eine @code{if}-Prozedur:
592 (if test-expression true-expression false-expression)
595 @var{test-expression} ist ein Ausdruck, der einen Booleschen
596 Wert zurück gibt. Wenn @var{test-expression} den Wert @code{#t}
597 ausgibt, gibt die if-Prozedur den Wert von @var{true-expression} aus,
598 in allen anderen Fällen den Wert von @var{false-expression}.
603 guile> (if (> a b) "a is greater than b" "a is not greater than b")
604 "a is not greater than b"
609 Eine andere konditionale Prozedur in Scheme ist
613 (cond (test-expression-1 result-expression-sequence-1)
614 (test-expression-2 result-expression-sequence-2)
616 (test-expression-n result-expression-sequence-n))
624 guile> (cond ((< a b) "a is less than b")
625 ... ((= a b) "a equals b")
626 ... ((> a b) "a is greater than b"))
632 @node Scheme in LilyPond
633 @section Scheme in LilyPond
634 @translationof Scheme in LilyPond
637 * LilyPond Scheme-Syntax::
638 * LilyPond-Variablen::
639 * Eingabe-Variablen und Scheme::
640 * Scheme in LilyPond importieren::
641 * Objekteigenschaften::
642 * Zusammengesetzte LilyPond-Variablen::
643 * Interne musikalische Repräsentation::
646 @node LilyPond Scheme-Syntax
647 @subsection LilyPond Scheme-Syntax
648 @translationof LilyPond Scheme syntax
653 Der Guile-Auswerter ist ein Teil von LilyPond, sodass Scheme also auch in
654 normale LilyPond-Eingabedateien eingefügt werden kann. Es gibt mehrere
655 Methoden, um Scheme in LilyPond zu integrieren.
657 Die einfachste Weise ist es, ein Rautenzeichen@tie{}@code{#} vor einem
658 Scheme-Ausdruck zu benutzen.
660 Die Eingabe von LilyPond ist in Zeichen und Ausdrücke gegliedert, so etwa
661 wie die menschliche Sprache sich in Wörter und Sätze gliedert. LilyPond
662 hat einen Lexer, der Zeichen erkennt (Zahlen, Zeichenketten, Scheme-Elemente,
663 Tonhöhen usw.) und einen Parser, der die Syntax versteht, @ruser{LilyPond grammar}.
664 Wenn dann eine bestimmte Syntaxregel als zuständig erkannt wurde, werden die
665 damit verknüpften Aktionen ausgeführt.
667 Die Rautenzeichenmethode (@code{#}), mit der Scheme eingebettet werden kann,
668 passt sehr gut in dieses System. Wenn der Lexer ein Rautenzeichen sieht, ruft
669 er den Scheme-reader auf, um den ganzen Scheme-Ausdruck zu lesen (das kann eine
670 Variable, ein Ausdruck in Klammern oder verschiedene andere Sachen sein). Nachdem
671 der Scheme-Ausdruck gelesen wurde, wird er als Wert eines @code{SCM_TOKEN} in der
672 Grammatik gespeichert. Wenn der Parser weiß, wie er diesen Wert benutzen kann,
673 ruft er Guile auf, um den Scheme-Ausdruck auszuwerten. Weil der Parser normalerweise
674 dem Lexer etwas voraus sein muss, ist die Trennung von Lesen und Auswerten zwischen
675 Lexer und Parser genau das richtige, um die Auswertung von LilyPond- und
676 Scheme-Ausdrücken synchron zu halten. Aus diesem Grund sollte das Rautenzeichen
677 zum Einbinden von Scheme immer benutzt werden, wenn es möglich ist.
679 Eine andere Möglichkeit, Scheme aufzurufen, ist die Benutzung des Dollarzeichens
680 (@code{$}) anstelle der Raute. In diesem Fall wertet LilyPond den Code sofort
681 aus, nachdem der Lexer ihn gelesen hat. Dabei wird der resultierende
682 Scheme-Ausdruckstyp geprüft und eine Tokentyp dafür ausgesucht (einer von mehreren
683 @code{xxx_IDENTIFIER} in der Syntax). Wenn der Wert des Ausdrucks gültig ist
684 (der Guilde-Wert für @code{*unspecified*}), dann wird nichts an den Parser
687 Das ist auch der gleiche Mechanismus, nach dem LilyPond funktioniert, wenn man eine Variable oder musikalische Funktion mit ihrer Bezeichnung ausruft, wie
688 in @code{\Bezeichnung}, mit dem einzigen Unterschied, dass ihre Bezeichnung durch den
689 LilyPond-Lexer bestimmt wird, ohne den Scheme-reader einzubeziehen, und also
690 nur Variablen akzeptiert werden, die im aktuellen LilyPond-Modus gültig sind.
692 Die direkte Auswirkung von @code{$} kann zu Überraschungen führen, siehe
693 @ref{Eingabe-Variablen und Scheme}. Es bietet sich daher an, @code{#} immer
694 zu benützen, wenn der Parser es unterstützt. Innerhalb von musikalischen
695 Ausdrücken werden Ausdrücke, die mit @code{#} erstellt werden, @emph{tatsächlich}
696 als Noten interpretiert. Sie werden jedoch @emph{nicht} vor der Benutzung
697 kopiert. Wenn Sie Teil einer Struktur sind, die noch einmal benutzt werden
698 soll, muss man eventuell @code{ly:music-deep-copy} explizit einsetzen.
703 Es gibt auch die Operatoren @code{$@@} und @code{#@@}, die eine @qq{listentrennende}
704 Funktion aufweisen, indem sie alle Elemente einer Liste in den umgebenden
707 Jetzt wollen wir uns tatsächlichen Scheme-Code anschauen. Scheme-Prozeduren
708 können in LilyPond-Eingabedateien definiert werden:
711 #(define (average a b c) (/ (+ a b c) 3))
714 LilyPond-Kommentare (@code{%} oder @code{%@{ %@}}) können innerhalb
715 von Scheme-Code nicht benutzt werden, nicht einmal in einer LilyPond-Eingabedatei,
716 weil der Guile-Interpreter und nicht der LilyPond-Parser den Scheme-Ausdruck
717 liest. Kommentare in Guile Scheme werden wie folgt notiert:
720 ; Einzeiliges Kommentar
723 Guile-Stil Blockkommentar (nicht schachtelbar)
724 Diese Kommentare werden von Scheme-Programmierern
725 selten benutzt und nie im Quellcode
730 Für den Rest dieses Abschnitts soll angenommen werden, dass die Daten in
731 einer LilyPond-Eingabedatei notiert werden sollen, sodass immer@tie{}@code{#}
732 vor die Scheme-Ausdrücke gestellt wird.
734 Alle Scheme-Ausdrücke auf oberster Ebene in einer LilyPond-Eingabedatei
735 können in einen einzigen Scheme-Ausdruck zusammengefasst werden mit
745 @node LilyPond-Variablen
746 @subsection LilyPond-Variablen
747 @translationof LilyPond variables
749 LilyPond-Variablen werden intern als Scheme-Variablen gespeichert. Darum
763 Das bedeutet, dass Scheme-Ausdrücke auf LilyPond-Variablen zugreifen können.
764 Man könnte also schreiben:
767 Vierundzwanzig = #(* 2 Zwoelf)
771 was zur Folge hätte, dass die Zahl 24 in der LilyPond (und Scheme-)Variablen
772 @code{Vierundzwanzig} gespeichert wird.
774 Üblicherweise greift man auf LilyPond-Variablen zu, indem man ihnen einen
775 Backslash voranstellt. Siehe auch @ref{LilyPond Scheme-Syntax}, also etwa
776 @code{\Vierundzwanzig}. Weil dadurch eine Kopie des Wertes für die meisten
777 von LilyPonds internen Typen erstellt wird (insbesondere musikalische Funktionen),
778 erstellen musikalische Funktionen normalerweise Kopien von Material, das sie
779 verändern. Aus diesem Grund sollten musikalische Funktionen, die mit @code{#}
780 aufgerufen werden, kein Material enthalten, dass entweder von Grund auf neu
781 erstellt wird oder explizit kopiert wird, sondern besser direkt auf das relevante
785 @node Eingabe-Variablen und Scheme
786 @subsection Eingabe-Variablen und Scheme
787 @translationof Input variables and Scheme
789 Das Eingabeformat unterstützt die Notation von Variablen: Im folgenden
790 Beispiel wird ein musikalischer Ausdruck einer Variablen mit der
791 Bezeichnung @code{traLaLa} zugewiesen:
794 traLaLa = @{ c'4 d'4 @}
797 Variablen haben beschränkte Geltungsbereiche: im unten stehenden Beispiel
798 enthält auch die @code{\layout}-Umgebung eine @code{traLaLa}-Variable,
799 die sich aber von der @code{traLaLa}-Variable auf oberster Ebene unterscheidet:
802 traLaLa = @{ c'4 d'4 @}
803 \layout @{ traLaLa = 1.0 @}
806 Jede Eingabedatei ist solch ein Gültigkeitsbereich, und alle
807 @code{\header}-, @code{\midi}- und @code{\layout}-Umgebungen
808 sind Gültigkeitsbereiche, die in diesen obersten Gültigkeitsbereich
811 Sowohl Variablen als auch Gültigkeitsbereiche sind im Guile Modulsystem
812 eingebaut. Ein anonymes Scheme-Modul wird jedem Gültigkeitsbereich
813 angehängt. Eine Zuweisen in der Form von
816 traLaLa = @{ c'4 d'4 @}
820 wird intern in die Scheme-Definition
823 (define traLaLa @var{Scheme-Wert von `@code{... }'})
829 Das bedeutet, dass LilyPond-Variablen und Scheme-Variablen frei gemischt
830 werden können. Im folgenden Beispiel wird ein Notenfragment in der
831 Variable @code{traLaLa} gespeichert und mit Scheme dupliziert. Das
832 Resultat wird in eine @code{\score}-Umgebung mit einer weiteren
833 Variable @code{twice} importiert:
836 traLaLa = { c'4 d'4 }
838 #(define newLa (map ly:music-deep-copy
839 (list traLaLa traLaLa)))
841 (make-sequential-music newLa))
846 Das ist ein interessantes Beispiel. Die Zuweisung findet erst statt,
847 nachdem der Parser sichergestellt hat, dass nichts folgt, das Ähnlichkeit
848 mit @code{\addlyrics} hat, sodass er prüfen muss, was als nächstes kommt.
849 Er liest @code{#} und den darauf folgenden Scheme-Ausdruck, @emph{ohne} ihn
850 auszuwerten, so dass er weiterlesen und erst @emph{danach}
851 wird der Scheme-Code ohne Probleme ausführen kann.
854 @node Scheme in LilyPond importieren
855 @subsection Scheme in LilyPond importieren
856 @translationof Importing Scheme in LilyPond
861 Das Beispiel zeigt, wie man musikalische Ausdrücke aus der Eingabe in den
862 Scheme-Auswerter @qq{exportieren} kann. Es geht auch andersherum. Indem
863 man Scheme-Werte nach @code{$} schreibt, wird ein
864 Scheme-Wert interpretiert, als ob er in LilyPond-Syntax eingeben wäre.
865 Anstatt @code{\twice} zu definieren, könne man also auch schreiben:
869 $(make-sequential-music newLa)
872 Mann kann @code{$} zusammen mit einem Scheme-Ausdruck überall benutzen,
873 wo auch @code{\@var{Bezeichnung}} gültig wäre, nachdem der Scheme-Ausdruck
874 einmal einer Variable @var{Bezeichnung} zugewiesen worden ist. Der Austausch
875 geschieht im Lexer, sodass LilyPond den Unterschied gar nicht merkt.
877 Ein negativer Effekt ist aber das Timing. Wenn man @code{$} anstelle von
878 @code{#} für die Definition von @code{newLa} im obigen Beispiel eingesetzt
879 hätte, würde der folgende Scheme-Ausdruck fehlschlagen, weil @code{traLaLa}
880 noch nicht definiert worden wäre. Zu einer Erklärung dieses Timingproblems
881 siehe @ref{LilyPond Scheme-Syntax}.
886 Eine weitere Bequemlichkeit können die @qq{listentrennenden} Operatoren
887 @code{$@@} und @code{#@@} bieten, indem sie die Elemente einer Liste
888 in den umgebenden Kontext einfügen. Wenn man sie einsetzt, hätte der
889 letzte Teil des Beispiels auch so geschrieben werden können:
896 Hier wird jedes Element der Liste, welche in @code{newLa} gespeichert ist,
897 der Reihenfolge nach genommen und in die Liste eingefügt, als ob man
901 @{ #(first newLa) #(second newLa) @}
904 In allen diesen Formen findet die Auswertung des Scheme-Codes statt,
905 während die Eingabe noch gelesen wird, entweder im Lexer oder im Parser.
906 Wenn man es später ausgeführt haben möchte, muss man
907 @ref{Leere Scheme-Funktionen} benutzen oder es in einem Makro speichern:
911 (ly:set-option 'point-and-click #f))
920 Scheme- und LilyPond-Variablen können nicht gemischt werden, wenn man die
921 @option{--safe}-Option benutzt.
924 @node Objekteigenschaften
925 @subsection Objekteigenschaften
926 @translationof Object properties
928 Objekteigenschaften werden in LilyPond in Form von Alisten-Ketten
929 gespeichert, also als Listen von Alisten. Eigenschaften werden
930 geändert, indem man Werte an den Anfang der Eigenschaftsliste
931 hinzufügt. Eigenschaften werden gelesen, indem Werte aus der
932 Aliste gelesen werden.
934 Ein neuer Wert für eine Eigenschaft kann gesetzt werden, indem man
935 der Alist einen Wert mit Schlüssel und dem Wert zuweist. Die
936 LilyPond-Syntax hierfür ist:
939 \override Stem #'thickness = #2.6
942 Diese Anweisung verändert die Erscheinung der Notenhälse. Der Alist-Eintrag
943 @code{'(thickness . 2.6)} wird zu der Eigenschaftsliste eines
944 @code{Stem}-(Hals-)Objektes hinzugefügt.
945 @code{thickness} wird relativ zu den Notenlinien errechnet, in diesem
946 Fall sind die Hälse also 2,6 mal so dick wie die Notenlinien. Dadurch
947 werden Hälse fast zweimal so dick dargestellt, wie sie normalerweise sind.
948 Um zwischen Variablen zu unterscheiden, die in den Quelldateien direkt
949 definiert werden (wie @code{Vierundzwanzig} weiter oben), und zwischen denen,
950 die für interne Objekte zuständig sind, werden hier die ersteren
951 @qq{Variablen} genannt, die letzteren dagegen @qq{Eigenschaften}.
952 Das Hals-Objekt hat also eine @code{thickness}-Eigenschaft, während
953 @code{Vierundzwanzig} eine Variable ist.
955 @cindex Eigenschaften versus Bezeichner
956 @cindex Bezeichner versus Eigenschaften
959 @node Zusammengesetzte LilyPond-Variablen
960 @subsection Zusammengesetzte LilyPond-Variablen
961 @translationof LilyPond compound variables
963 @subheading Abstände (offset)
965 Zweidimensionale Abstände (X- und Y-Koordinaten) werden
966 als @emph{pairs} (Paare) gespeichert. Der @code{car}-Wert des
967 Abstands ist die X-Koordinate und der @code{cdr}-Wert die
971 \override TextScript #'extra-offset = #'(1 . 2)
974 Hierdurch wird das Paar @code{(1 . 2)} mit der Eigenschaft @code{extra-offset}
975 des TextScript-Objektes verknüpft. Diese Zahlen werden in
976 Systembreiten gemessen, so dass der Befehl das Objekt eine Systembreite
977 nach rechts verschiebt und zwei Breiten nach oben.
979 Prozeduren, um mit Abständen zu arbeiten, finden sich in @file{scm/lily-library.scm}.
981 @subheading Brüche (fractions)
983 Brüche, wie sie LilyPond benutzt, werden wiederum als Paare gespeichert,
984 dieses Mal als unbezeichnete ganze Zahlen. Während Scheme rationale Zahlen
985 als einen negativen Typ darstellen kann, sind musikalische gesehen
986 @samp{2/4} und @samp{1/2} nicht das selbe, sodass man zwischen beiden unterscheiden
987 können muss. Ähnlich gibt es auch keine negativen Brüche in LilyPonds Sinn.
988 Somit bedeutet @code{2/4} in LilyPond @code{(2 . 4)} in Scheme, und @code{#2/4} in
989 LilyPond bedeutet @code{1/2} in Scheme.
991 @subheading Bereiche (extend)
993 Paare werden auch benutzt, um Intervalle zu speichern, die einen Zahlenbereich
994 vom Minimum (dem @code{car}) bis zum Maximum (dem @code{cdr}) darstellen.
995 Intervalle werden benutzt, um die X- und Y-Ausdehnung von druckbaren
996 Objekten zu speichern. Bei X-Ausdehnungen ist @code{car} die linke
997 X-Koordinate und @code{cdr} die rechte X-Koordinate. Für Y-Ausdehnungen
998 ist @code{car} die untere Koordinate und @code{cdr} die obere Koordinate.
1000 Prozeduren, um mit Intervallen zu arbeiten, finden sich in
1001 @file{scm/lily-library.scm}. Diese Prozeduren sollten benutzt, wenn es möglich
1002 ist, um den Code konsistent zu halten.
1004 @subheading Eigenschafts-Alisten (property alist)
1006 Eine Eigenschafts-Aliste ist eine LilyPond-Datenstruktur, die eine Aliste
1007 darstellt, deren Schlüssel Eigenschaften sind und deren Werte
1008 Scheme-Ausdrücke sind, die den erwünschen Wert der Eigenschaft ausgeben.
1010 LilyPond-Eigenschaften sind Scheme-Symbole, wie etwa @code{'thickness}
1013 @subheading Alisten-Ketten (alist chains)
1015 Eine Alisten-Kette ist eine Liste, die Eigenschafts-Alisten enthält.
1017 Die Menge aller Eigenschaften, die sich auf einen Grob auswirken, wird
1018 typischerweise in einer Alisten-Kette gespeichert. Um den Wert einer
1019 bestimmten Eigenschaft zu finden, die ein Grob haben soll, wird jede
1020 Liste in der Kette nach einander durchsucht, wobei nach einem Eintrag
1021 geschaut wird, der den Eigenschaftsschlüssel enthält. Der erste
1022 gefundene Alisten-Eintrag wird benutzt und dessen Wert ist der
1023 Wert der Eigenschaft.
1025 Die Scheme-Prozedur @code{chain-assoc-get} wird normalerweise benutzt,
1026 um Grob-Eigenschaftenwerte zu erhalten.
1029 @node Interne musikalische Repräsentation
1030 @subsection Interne musikalische Repräsentation
1031 @translationof Internal music representation
1033 Intern werden Noten als Scheme-Liste dargestellt. Die Liste enthält
1034 verschiedene Elemente, die die Druckausgabe beeinflussen. Parsen
1035 nennt man den Prozess, der die Noten aus der LilyPond-Repräsentation
1036 in die interne Scheme-Repräsentation überführt.
1038 Wenn ein musikalischer Ausdruck geparst wird, wird er in eine Gruppe
1039 von Scheme-Musikobjekten konvertiert. Die definierende Eigenschaft
1040 eines Musikobjektes ist, dass es Zeit einnimmt. Die Zeit, die
1041 ein Objekt braucht, wird Dauer (engl. @emph{duration}) genannt.
1042 Dauern werden in rationalen Zahlen ausgedrückt, die die Länge des
1043 Musikobjekts in Ganzen Noten angeben.
1045 Ein Musikobjekt hat drei Typen:
1049 Musikbezeichnung (music name): Jeder Musikausdruck hat eine Bezeichnung. Eine
1050 Note beispielsweise erzeugt ein @rinternals{NoteEvent} und @code{\simultaneous}
1051 produziert @rinternals{SimultaneousMusic}. Eine Liste aller möglichen
1052 Ausdrücke findet sich in der Referenz der Interna, unter
1053 @rinternals{Music expressions}.
1056 Typ (type) oder Schnittstelle (interface): Jede Musikbezeichnung hat mehrere
1057 Typen oder Schnittstellen, beispielsweise eine Note ist ein Ereignis (@code{event}),
1058 aber auch ein Notenereignis (@code{note-event}), ein rhythmisches Ereignis
1059 (@code{rhythmic-event}) und ein Melodieereignis (@code{melodic-event}).
1060 Alle Musikklassen sind in der Referenz der Interna aufgelistet, unter
1061 @rinternals{Music classes}.
1064 C++-Objekt: Jedes Musikobjekt ist durch ein Objekt der C++-Klasse @code{Music}
1068 Die eigentliche Information eines musikalischen Ausdrucks wird in Eigenschaften
1069 gespeichert. Ein @rinternals{NoteEvent} beispielsweise hat die Eigenschaften
1070 Tonhöhe (@code{pitch}) und Dauer (@code{duration}), die die Dauer und die
1071 Tonhöhe der Note speichern. Eine Liste aller möglichen Eigenschaften findet
1072 sich in der Referenz der Interna, unter
1073 @rinternals{Music properties}.
1075 Ein zusammengesetzter musikalischer Ausdruck ist ein Musikobjekt, das andere
1076 Musikobjekte als Eigenschaften enthält. Eine Liste an Objekten kann in der
1077 @code{elements}-Eigenschaft eines Musikobjekts bzw. ein einziges
1078 Ableger-Musikelement in der @code{element}-Eigenschaft gespeichert werden.
1079 @rinternals{SequentialMusic} beispielsweise hat sein einziges Argument in
1080 @code{element}. Der Körper einer Wiederholung wird in der @code{element}-Eigenschaft
1081 von @rinternals{RepeatedMusic} gespeichert, und die alternativen Endungen
1085 @node Komplizierte Funktionen erstellen
1086 @section Komplizierte Funktionen erstellen
1087 @translationof Building complicated functions
1089 Dieser Abschnitt zeigt, wie man Information zusammensucht,
1090 um komplizierte musikalische Funktionen zu erstellen.
1093 * Musikalische Funktionen darstellen::
1094 * Eigenschaften von Musikobjekten::
1095 * Verdoppelung einer Note mit Bindebögen (Beispiel)::
1096 * Artikulationszeichen zu Noten hinzufügen (Beispiel)::
1100 @node Musikalische Funktionen darstellen
1101 @subsection Musikalische Funktionen darstellen
1102 @translationof Displaying music expressions
1104 @cindex interne Speicherung
1105 @cindex Musikausdrücke anzeigen
1106 @cindex Anzeigen von Musikausdrücken
1108 @funindex displayMusic
1109 @funindex \displayMusic
1111 Wenn man eine musikalische Funktion erstellt, ist es oft
1112 hilfreich sich anzuschauen, wie musikalische Funktionen
1113 intern gespeichert werden. Das kann mit der Funktion
1114 @code{\displayMusic} erreicht werden:
1118 \displayMusic @{ c'4\f @}
1133 'AbsoluteDynamicEvent
1137 (ly:make-duration 2 0 1 1)
1139 (ly:make-pitch 0 0 0))))
1142 Normalerweise gibt LilyPond diese Ausgabe auf der Konsole mit
1143 allen anderen Nachrichten aus. Um die wichtigen Nachrichten
1144 in einer Datei zu speichern, kann die Ausgabe in eine Datei
1148 lilypond file.ly >display.txt
1151 Mit LilyPond- und Scheme-Magie kann man LilyPond anweisen, genau
1152 diese Ausgabe an eine eigene Datei zu senden:
1156 #(with-output-to-file "display.txt"
1157 (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
1161 Mit etwas Umformatierung ist die gleiche Information sehr viel
1165 (make-music 'SequentialMusic
1167 (make-music 'NoteEvent
1168 'articulations (list
1169 (make-music 'AbsoluteDynamicEvent
1172 'duration (ly:make-duration 2 0 1 1)
1173 'pitch (ly:make-pitch 0 0 0))))
1176 Eine musikalische @code{@{ ... @}}-Sequenz hat die Bezeichnung
1177 @code{SequentialMusic} und ihre inneren Ausdrücke werden als
1178 Liste in seiner @code{'elements}-Eigenschaft gespeichert. Eine
1179 Note ist als als ein @code{EventChord}-Objekt dargestellt (welches Dauer und
1180 Tonhöhe speichert) und zusätzliche Information enthält (in
1181 diesem Fall ein @code{AbsoluteDynamicEvent} mit einer
1182 @code{"f"}-Text-Eigenschaft).
1186 @code{\displayMusic} gibt die Noten aus, die dargestellt werden, sodass
1187 sie sowohl angezeigt als auch ausgewertet werden. Um die Auswertung zu
1188 vermeiden, kann @code{\void} vor @code{\displayMusic} geschrieben werden.
1191 @node Eigenschaften von Musikobjekten
1192 @subsection Eigenschaften von Musikobjekten
1193 @translationof Music properties
1195 TODO -- make sure we delineate between @emph{music} properties,
1196 @emph{context} properties, and @emph{layout} properties. These
1197 are potentially confusing.
1199 Schauen wir uns ein Beispiel an:
1203 \displayMusic \someNote
1208 (ly:make-duration 2 0 1 1)
1210 (ly:make-pitch 0 0 0))
1213 Das @code{NoteEvent}-Objekt ist die Repräsentation von @code{someNote}.
1214 Einfach. Wie fügt man denn ein c' in einen Akkorde ein?
1218 \displayMusic \someNote
1226 (ly:make-duration 2 0 1 1)
1228 (ly:make-pitch 0 0 0))))
1231 Jetzt ist das @code{NoteEvent}-Objekt das erste Objekt der
1232 @code{'elements}-Eigenschaft von @code{someNote}.
1234 Die @code{display-scheme-music}-Funktion ist die Funktion, die von
1235 @code{\displayMusic} eingesetzt wird, um die Scheme-Repräsentation
1236 eines musikalischen Ausdrucks anzuzeigen.
1239 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1244 (ly:make-duration 2 0 1 1)
1246 (ly:make-pitch 0 0 0))
1249 Danach wird die Tonhöhe der Note von der @code{'pitch}-Eigenschaft
1250 des @code{NoteEvent}-Objektes gelesen:
1253 #(display-scheme-music
1254 (ly:music-property (first (ly:music-property someNote 'elements))
1257 (ly:make-pitch 0 0 0)
1260 Die Tonhöhe einer Note kann geändert werden, indem man diese
1261 @code{'pitch}-Eigenschaft umdefiniert:
1263 @funindex \displayLilyMusic
1264 @funindex displayLilyMusic
1267 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1269 (ly:make-pitch 0 1 0)) ;; Die Tonhöhen auf d' verändern.
1270 \displayLilyMusic \someNote
1276 @node Verdoppelung einer Note mit Bindebögen (Beispiel)
1277 @subsection Verdoppelung einer Note mit Bindebögen (Beispiel)
1278 @translationof Doubling a note with slurs (example)
1280 In diesem Abschnitt soll gezeigt, werden, wie man eine
1281 Funktion erstellt, die eine Eingabe wie @code{a}
1282 nach @code{@{ a( a) @}} umdefiniert. Dazu wird zuerst die
1283 interne Repräsentation der Musik betrachtet, die
1284 das Endergebnis darstellt:
1287 \displayMusic@{ a'( a') @}
1300 (ly:make-duration 2 0 1 1)
1302 (ly:make-pitch 0 5 0))
1311 (ly:make-duration 2 0 1 1)
1313 (ly:make-pitch 0 5 0))))
1316 Eine schlechte Nachricht ist, dass die
1317 @code{SlurEvent}-Ausdrücke @qq{innerhalb}
1318 der Noten (in ihrer @code{articulations}-Eigenschaft) hinzugefügt werden müssen.
1320 Jetzt folgt eine Betrachtung der Eingabe:
1328 (ly:make-duration 2 0 1 1)
1330 (ly:make-pitch 0 5 0))))
1333 In der gewünschten Funktion muss also dieser Ausdruck
1334 kopiert werden (sodass zwei Noten vorhanden sind, die
1335 eine Sequenz bilden), dann müssen @code{SlurEvent}
1336 zu der @code{'articulations}-Eigenschaft jeder Noten hinzugefügt
1337 werden, und schließlich muss eine @code{SequentialMusic}
1338 mit den beiden @code{EventChords} erstellt werden. Um zu
1339 einer Eigenschaft etwas hinzuzufügen, ist es nützlich zu wissen, dass
1340 eine nicht gesetzte Eigenschaft als @code{'()} gelesen wird, sodass
1341 keine speziellen Überprüfungen nötig sind, bevor ein anderes
1342 Element vor die @code{articulations}-Eigenschaft gesetzt wird.
1345 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1346 "Return: @{ note ( note ) @}.
1347 `note' is supposed to be a single note."
1348 (let ((note2 (ly:music-deep-copy note)))
1349 (set! (ly:music-property note 'articulations)
1350 (cons (make-music 'SlurEvent 'span-direction -1)
1351 (ly:music-property note 'articulations)))
1352 (set! (ly:music-property note2 'articulations)
1353 (cons (make-music 'SlurEvent 'span-direction 1)
1354 (ly:music-property note2 'articulations)))
1355 (make-music 'SequentialMusic 'elements (list note note2))))
1359 @node Artikulationszeichen zu Noten hinzufügen (Beispiel)
1360 @subsection Artikulationszeichen zu Noten hinzufügen (Beispiel)
1361 @translationof Adding articulation to notes (example)
1363 Am einfachsten können Artikulationszeichen zu Noten
1364 hinzugefügt werden, indem man zwei musikalische Funktionen
1365 in einen Kontext einfügt, wie erklärt in
1366 @ruser{Kontexte erstellen}. Hier soll jetzt eine musikalische
1367 Funktion entwickelt werden, die das vornimmt. Daraus ergibt sich
1368 der zusätzliche Vorteil, dass diese musikalische Funktion eingesetzt
1369 werden kann, um eine Artikulation (wie etwa eine Fingersatzanweisung)
1370 einer einzigen Note innerhalb eines Akkordes hinzugefügt werden
1371 kann, was nicht möglich ist, wenn einfach unabhängige Noten ein einem
1372 Kontext miteinander verschmolzen werden.
1374 Eine @code{$variable} innerhalb von @code{#@{...#@}} ist das
1375 gleiche wie die normale Befehlsform @code{\variable} in
1376 üblicher LilyPond-Notation. Es ist bekannt dass
1383 in LilyPond nicht funktioniert. Das Problem könnte vermieden
1384 werden, indem das Artikulationszeichen an einen leeren Akkord
1388 @{ << \music <> -. -> >> @}
1392 aber in diesem Beispiel soll gezeigt werden, wie man das in
1393 Scheme vornimmt. Zunächst wird die Eingabe und die gewünschte
1403 (ly:make-duration 2 0 1 1)
1405 (ly:make-pitch -1 0 0))))
1407 % gewünschte Ausgabe
1418 (ly:make-duration 2 0 1 1)
1420 (ly:make-pitch -1 0 0))
1429 (ly:make-duration 2 0 1 1)
1431 (ly:make-pitch -1 0 0))))
1434 Dabei ist zu sehen, dass eine Note (@code{c4}) als @code{NoteEvent}-Ausdruck
1435 repräsentiert ist. Um eine Akzent-Artikulation hinzuzufügen, muss
1436 ein @code{ArticulationEvent}-Ausdruck zu der Elementeigenschaft @code{articulations}
1437 des @code{NoteEvent}-Ausdrucks hinzugefügt werden.
1439 Um diese Funktion zu bauen, wird folgendermaßen begonnen:
1442 (define (add-accent note-event)
1443 "Add an accent ArticulationEvent to the articulations of `note-event',
1444 which is supposed to be a NoteEvent expression."
1445 (set! (ly:music-property note-event 'articulations)
1446 (cons (make-music 'ArticulationEvent
1447 'articulation-type "accent")
1448 (ly:music-property note-event 'articulations)))
1452 Die erste Zeile definiert eine Funktion in Scheme: Die Bezeichnung
1453 der Funktion ist @code{add-accent} und sie hat eine Variable
1454 mit der Bezeichnung @code{note-event}. In Scheme geht der Typ
1455 einer Variable oft direkt aus der Bezeichnung hervor (das ist auch
1456 eine gute Methode für andere Programmiersprachen).
1463 ist eine (englische) Beschreibung, was diese Funktion tut. Sie ist
1464 nicht unbedingt notwendig, aber genauso wie klare Variablen-Bezeichnungen
1465 ist auch das eine gute Methode.
1467 Es kann seltsam scheinen, warum das Notenereignis direkt verändert wird,
1468 anstatt mit einer Kopie zu arbeiten (@code{ly:music-deep-copy} kann dafür
1469 benützt werden). Der Grund ist eine stille Übereinkunft: musikalische
1470 Funktionen dürfen ihre Argumente verändern: sie werden entweder von
1471 Grund auf erstellt (wie Eingabe des Benutzers) oder sind schon kopiert
1472 (etwa Verweis auf eine Variable mit @samp{\Bezeichnung} oder Noten aus
1473 einem Scheme-Ausdruck @samp{$(@dots{})} sind Kopien). Weil es uneffizient
1474 wäre, unnötige Kopien zu erstellen, wird der Wiedergabewert einer musikalischen
1475 Funktion @emph{nicht} kopiert. Um sich also an die Übereinkunft zu halten,
1476 dürfen Argumente nicht mehr als einmal benützt werden, und sie wiederzugeben
1477 zählt als eine Benutzung.
1479 In einem früheren Beispiel wurden Noten konstruiert, indem ein musikalisches
1480 Argument wiederholt wurde. In diesem Fall muss wenigstens eine Wiederholung
1481 eine Kopie ihres Arguments sein. Wenn es keine Kopie ist, können seltsame
1482 Dinge passieren. Wenn man beispielsweise @code{\relative} oder @code{\transpose}
1483 auf die resultierenden Noten anwendet, die die gleichen Elemente mehrmals
1484 enthalten, werden die Elemente mehrmals der @code{\relative}-Veränderung
1485 oder Transposition unterworfen. Wenn man sie einer musikalischen Variable
1486 zuweist, wird dieser Fluch aufgehoben, denn der Verweis auf @samp{\Bezeichnung}
1487 erstellt wiederum eine Kopie, die nicht die Identität der wiederholten
1490 Während die Funktion oben keine musikalische Funktion ist, wird sie
1491 normalerweise inmitten musikalischer Funktionen eingesetzt. Darum
1492 ist es sinnvoll, der gleichen Übereinkunft zu folgen, die für musikalische
1493 Funktionen gelten: Die Eingabe kann verändert worden sein, um die
1494 Ausgabe zu produzieren, und der den Aufruf erstellt, ist verantwortlich
1495 für die Erstellung von Kopien, wenn er immernoch die unveränderten
1496 Argumente benötigt. Wenn man sich LilyPonds eigene Funktionen wie etwa
1497 @code{music-map} anschaut, sieht man, dass sie denselben Prinzipien folgen.
1499 Aber wo waren wir? Jetzt gibt es ein @code{note-event}, das verändert
1500 werden kann, nicht unter Einsatz von @code{ly:music-deep-copy} sondern
1501 aufgrund einer langen Erklärung. Der Akzent wird zu seiner
1502 @code{'articulations}-Liste hinzugefügt:
1505 (set! place neuer-Wert)
1508 Was in diesem Fall @qq{gesetzt} werden soll (@qq{place}) ist die
1509 @q{'articulations}-Eigenschaft des @code{note-event}-Ausdrucks.
1512 (ly:music-property note-event 'articulations)
1515 @code{ly:music-property} ist die Funktion, mit der musikalische
1516 Eigenschaften erreicht werden können (die @code{'articulations},
1517 @code{'duration}, @code{'pitch} usw., die in der Ausgabe von
1518 @code{\displayMusic} weiter oben angezeigt werden). Der neue
1519 Wert ist, was ehemals die @code{'articulations}-Eigenschaft war, mit einem
1520 zusätzlichen Element: dem @code{ArticulationEvent}-Ausdruck,
1521 der aus der Ausgabe von @code{\displayMusic} kopiert werden kann:
1524 (cons (make-music 'ArticulationEvent
1525 'articulation-type "accent")
1526 (ly:music-property result-event-chord 'articulations))
1529 @code{cons} wird benutzt, um ein Element vorne an eine Liste hinzuzufügen,
1530 ohne dass die originale Liste verändert wird. Das ist es, was die
1531 Funktion tun soll: die gleiche Liste wie vorher, aber mit dem neuen
1532 @code{ArticulationEvent}-Ausdruck. Die Reihenfolge innerhalb
1533 der Elementeeigenschaft ist hier nicht relevant.
1535 Wenn schließlich die Akzent-Artikulation zu der entsprechenden
1536 @code{elements}-Eigenschaft hinzugefügt ist, kann
1537 @code{note-event} ausgegeben werden, darum die letzte Zeile
1540 Jetzt wird die @code{add-accent}-Funktion in eine musikalische
1541 Funktion umgewandelt (hierzu gehört etwas syntaktischer Zuckerguß und
1542 eine Deklaration des Typs ihres einzigen @qq{wirklichen} Arguments:
1545 addAccent = #(define-music-function (parser location note-event)
1547 "Add an accent ArticulationEvent to the articulations of `note-event',
1548 which is supposed to be a NoteEvent expression."
1549 (set! (ly:music-property note-event 'articulations)
1550 (cons (make-music 'ArticulationEvent
1551 'articulation-type "accent")
1552 (ly:music-property note-event 'articulations)))
1556 Eine Überprüfung, dass die Funktion richtig arbeitet, geschieht
1560 \displayMusic \addAccent c4
1567 * Optimierungen mit Scheme::
1570 @c node Optimierungen mit Scheme
1571 @c appendixsec Optimierungen mit Scheme
1572 @c translationof Tweaking with Scheme
1574 Wir haben gesehen wie LilyPond-Eingabe massiv beeinflusst
1575 werden kann, indem Befehle wie etwa
1576 @code{\override TextScript #'extra-offset = ( 1 . -1)}
1577 benutzt werden. Aber es wurde gezeigt, dass Scheme noch
1578 mächtiger ist. Eine bessere Erklärung findet sich in der@ref{Scheme-Übung} und in
1579 @ruser{Schnittstellen für Programmierer}.
1581 Scheme kann auch in einfachen @code{\override}-Befehlen
1584 TODO Find a simple example
1585 @c This isn't a valid example with skylining
1586 @c It works fine without padText -td
1589 @lilypond[quote,verbatim,ragged-right]
1590 padText = #(define-music-function (parser location padding) (number?)
1592 \once \override TextScript #'padding = #padding
1596 c4^"piu mosso" b a b
1598 c4^"piu mosso" d e f
1600 c4^"piu mosso" fis a g
1605 Es kann auch benutzt werden, um Befehle zu erstellen:
1607 @c Check this is a valid example with skylining
1608 @c It is - 'padding still works
1610 @lilypond[quote,verbatim,ragged-right]
1611 tempoPadded = #(define-music-function (parser location padding tempotext)
1614 \once \override Score.MetronomeMark #'padding = #padding
1615 \tempo \markup { \bold #tempotext }
1619 \tempo \markup { "Low tempo" }
1621 \tempoPadded #4.0 "High tempo"
1626 Sogar ganze Musikausdrücke können eingefügt werden:
1628 @lilypond[quote,verbatim,ragged-right]
1629 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1636 \pattern {d16 dis} { ais16-> b\p }