+@node LilyPond-Codeabschnitte
+@section LilyPond-Codeabschnitte
+@translationof Lilypond code blocks
+
+Codeabschnitte in LilyPond sehen etwa so aus:
+
+@example
+ #@{ @var{Lilypond code} #@}
+@end example
+
+Sie können überall eingesetzt werden, wo man Scheme-Code schreiben
+kann: der Scheme-Einleser wurde geändert, um LilyPond-Codeabschnitte
+zu akzeptieren und kann mit eingebetteten Scheme-Ausdrücken umgehen,
+die mit @code{$} und@w{ }@code{#} beginnen.
+
+Er extrahiert den LilyPond-Codeabschnitt und erstellt einen Aufruf
+zum LilyPond-Parser, welcher während der Prorammausführung zur
+Interpretation des LilyPond-Codeabschnittes aufgerufen wird. Alle
+eingebetteten Scheme-Ausdrücke werden in der lokalen Umgebung des
+LilyPond-Codeabschnittes ausgeführt, sodass man Zugruff auf lokale
+Variablen und Funktionsparameter zu dem Zeitpunkt hat, an dem
+der LilyPond-Codeabschnitt geschrieben wird.
+
+Ein LilyPond-Codeabschnitt kann jeden Inhalt haben, den man auf
+der rechten Seite einer Zuweisung einsetzt. Zusätzlich entspricht
+ein leerer LilyPond-Abschnitt einem gültigen musikalischen Ausdruck,
+und ein LilyPond-Abschnitt, der mehrere musikalische Ereignisse enthält,
+wird in einen sequenziellen musikalischen Ausdruck umgewandelt.
+
+
+@node Scheme-Funktionen
+@section Scheme-Funktionen
+@translationof Scheme functions
+
+@cindex Scheme-Funktionen (LilyPond syntax)
+
+@emph{Scheme-Funktionen} sind Scheme-Prozeduren, die Scheme-Ausdrücke
+aus einer Eingabe erstellen können, die in LilyPond-Syntax geschrieben
+wurde. Sie können in so gut wie allen Fällen aufgerufen werden, in
+denen es erlaubt ist, @code{#} zur Angabe eines Wertes in Scheme-Syntax
+einzusetzen. Während Scheme auch eigene Funktionen besitzt, handelt
+% dieses kapitel von @emph{syntaktischen} Funktionen, Funktionen, die
+Argumente in LilyPond-Syntax annehmen.
+
+@menu
+* Definition von Scheme-Funktionen::
+* Benutzung von Scheme-Funktionen::
+* Leere Scheme-Funktionen::
+@end menu
+
+@node Definition von Scheme-Funktionen
+@subsection Definition von Scheme-Funktionen
+@translationof Scheme function definitions
+
+@funindex define-scheme-function
+
+Die übliche Form zur Definition von Scheme-Funktionen ist:
+
+@example
+function =
+#(define-scheme-function
+ (parser location @var{Arg1} @var{Arg2} @dots{})
+ (@var{Typ1?} @var{Typ2?} @dots{})
+ @var{body})
+@end example
+
+@noindent
+wobei
+
+@multitable @columnfractions .33 .66
+@item @code{parser}
+@tab ganz genau das Wort @code{parser} sein muss, damit LilyPond
+eine Umgebung (@code{#@{}@dots{}@code{#@}}) mit Zugriff
+auf den Parser bekommt.
+
+@item @code{@var{ArgN}}
+@tab @var{n}te Argument
+
+@item @code{@var{TypN?}}
+@tab eine Scheme-@emph{Typenprädikat}, für welches @code{@var{argN}}
+@code{#t} ausgeben muss. Manche dieser Prädikate werden vom Parser
+besonders erkannt, siehe unten. Es gibt auch eine Spezialform
+@code{(@emph{predicate?} @emph{default})}, um optionale Argumente
+anzugeben. Wenn das eigentlich Argument fehlt, während die Funktion
+aufgerufen wird, wird der Standardwert anstelle eingesetzt. Standardwerte
+werden bei ihrer Definition evaluiert (gilt auch für
+LilyPond-Codeabschnitte), so dass man besser einen speziellen Wert
+schreibt, den man einfach erkennen kann, wenn der Wert während der
+Ausführung der Position evaluiert weren soll. Wenn man das Prädikat
+in Klammern setzt, aber kein Standardwert folt, wird @code{#f}
+als Standard eingesetzt. Standardwerte werden weder bei der Definition
+noch bei der Ausführung mit @emph{predicate?} verifiziert, sodass
+man selber verantworlich für funktionsfähige Werte ist. Standardwerte,
+die musikalische Ausdrücke darstellen, werden kopiert und @code{origin}
+auf den Parameter @code{location} gesetzt.
+
+@item @code{@var{body}}
+@tab Eine Folge von Scheme-Formeln, die der Reihe nach ausgewertet
+werden, wobei die letzte als Ausgabewert der Scheme-Funktion eingesetzt
+wird. Sie kann LilyPond-Codeabschnitte enthalten, eingeschlossen mit
+Raute-Klammern (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), wie beschrieben
+in @ref{LilyPond-Codeabschnitte}. Innerhalb von LilyPond-Codeabschnitten
+wird mit @code{#} auf Funktionsargumente (etwa @samp{#Arg1}) verwiesen
+oder ein neuer Scheme-Ausdruck mit Funktionsargumenten begonnen
+(etwa @w{@samp{#(cons Arg1 Arg2)}}). Wo normale Scheme-Ausdrücke mit
+@code{#} nicht funktionieren, kann man auf direkte Scheme-Ausdrücke
+zurückgreifen, die mit @code{$} begonnen werden (etwa @samp{$music}).
+
+Wenn die Funktion eine musikalische Funktion ausgibt, bekommt sie einen
+Wert von @code{origin}. zugewiesen.
+@end multitable
+
+@noindent
+Einige Typenprädikate werden vom Parser besonders behandelt, weil
+er sonst die Argumente nicht zuverlässig erkennen könnte. Im Moment
+handelt es sich um @code{ly:pitch?} und @code{ly:duration?}.
+
+Die Eignung der Argumente für alle anderen Prädikate wird festgestellt,
+indem das Prädikat aufgerufen wird, nachdem LilyPond es schon in einen
+Scheme-Ausdruck umgewandelt hat. Demzufolge kann das Argument in
+Scheme-Syntax angegeben werden, wenn nötig (beginnend mit @code{#} oder
+als Result des Aufrufes einer Scheme-Funktion), aber LilyPond
+konvertiert auch eine Reihe von LilyPond-Strukturen nach Scheme,
+bevor dann tatsächlich die Prädikate überprüft werden. Bei den
+letzteren handelt es sich im Moment um music (Noten), postevents,
+simple strings (einfache Zeichenketten mit oder ohne Anführungszeichen)
+numbers (Zahlen), markup (Beschriftung) und markup lists
+(Beschriftungslisten), score (Partitur), book (Buch), bookpart
+(Buchteil), Kontextdefinitions- und Ausgabedefinitionsumgebungen.
+
+Für einige Arten von Ausdrücken (wie die meisten Noten, die nicht
+in Klammern geschrieben werden) muss LilyPond weiter nach vorne
+schauen als der Ausdruck selber reicht, um das Ende des Ausdrucks
+zu bestimmen. Wenn solche Ausdrücke für optionale Argumente mit
+einbezogen würden, indem ihre Prädikate ausgewählt würden, könnte
+LilyPond nicht mehr zurückgehen, wenn es feststellt, dass der
+Ausdruck nicht zu dem Parameter passt. Darum müssen manche Formen
+von Noten möglicherweise in Klammern eingeschlossen werden, damit
+LilyPond sie akzeptiert. Es gibt auch einige andere Mehrdeutigkeiten,
+die LilyPond durch Testen von Prädikatfunktionen eingrenzt:
+ist etwa @samp{-3} die Anmerkung für einen Fingersatz oder eine
+negative Zahl? Ist @code{"a" 4} im Gesangskontext eine Zeichenkette
+gefolgt von einer Zahl oder ein Gesangstextereignis mit der Dauer
+@code{4}? LilyPond entscheidet, indem es Prädaikate befragt. Das
+heißt, dass man zu durchlässige Prädikate wie @code{scheme?}
+vermeiden sollte, wenn man eine bestimmmte Verwendung beabsichtigt
+und nicht nur eine Funktion für die allgemeine Verwendung schreibt.
+
+Eine Liste der möglichen vordefinierten Typenprädikte findet sich in
+@ruser{Vordefinierte Typenprädikate}.
+
+@seealso
+
+Notationsreferenz
+@ruser{Vordefinierte Typenprädikate}.
+
+Installierte Dateien:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
+
+
+@node Benutzung von Scheme-Funktionen
+@subsection Benutzung von Scheme-Funktionen
+@translationof Scheme function usage
+
+Scheme-Funktionen können überall aufgerufen werden, wo ein
+Scheme-Ausdruck beginnend mit @code{#} geschrieben werden kann.
+Man kann eine Scheme-Funktion aufrufen, indem man ihrer Bezeichnung
+@code{\} voranstellt und Argumente hinten anfügt. Wenn ein optionales
+Argumentenprädikat nicht mit einem Argument übereinstimmt, lässt
+LilyPond dieses und alle folgenden Argumente aus und ersetzt sie
+durch ihre Standardwerte und @qq{speichert} das Argument, das nicht
+gepasst hat, bis zum nächsten zwingenden Argument. Da das gespeicherte
+Argument auch noch irgendwo untergebracht werden muss, werden
+optionale Argumente nicht wirklich als optional angesehen, es sei denn,
+sie werden von einem zwingenden Argument gefolgt.
+
+Es gibt eine Ausnahme: Wenn man @code{\default} anstelle eines optionalen
+Arguments schreibt, wird dieses und alle folgenden Argumente ausgelassen
+und durch ihre Standardwerte ersetzt. Das funktioniert auch, wenn kein
+zwingendes Argument folgt, weil @code{\default} nicht gespeichert werden
+muss. Die Befehle @code{mark} und @code{key} benützten diesen Trick,
+um ihr Standardverhalten zur verfügung zu stellen, wenn sie
+@code{\default} nachgestellt haben.
+
+Abgesehen von Stellen, wo ein Scheme-Wert benötigt ist, gibt es
+wenige Stellen, wo @code{#}-Ausdrücke zwar für ihre (Neben-)Wirkung
+akzeptiert und ausgewertet, aber ansonsten ignoriert werden. Meistens
+handelt es sich dabei um Stellen, wo eine Zuweisung auch in Ordnung
+wäre.
+
+Weil es eine schlechte Idee ist, einen Wert auszugeben, der in einigen
+Kontexten misinterpretiert werden könnte, sollte man Scheme-Funktionen
+nur in den Fällen benutzen, in welchen sie immer einen sinnvollen
+Wert ausgeben, und leere Scheme-Funktionen an anderen stellen
+einsetzen. Siehe auch @pxref{Leere Scheme-Funktionen}.
+
+
+@node Leere Scheme-Funktionen
+@subsection Leere Scheme-Funktionen
+@translationof Void scheme functions
+
+@funindex define-void-function
+@funindex \void
+
+Manchmal wird eine Prozedur ausgeführt, um eine Aktion zu machen und nicht,
+um einen Wert auszugeben. Einige Programmiersprachen (wie C oder Scheme)
+setzen Funktionen für beide Konzepte ein und verwerfen einfach den
+Rückgabewert (normalerweise, indem einem Ausdruck erlaubt wird, als
+Aussage zu funktionieren und das Ergebnis ignoriert wird). Das ist
+klug, aber auch fehleranfällig: die meisten C-Kompilierer haben heutzutage
+Warnungen für verschiedene nicht-@qq{gültige} Ausdrücke, die verworfen
+werden. Viele Funktionen, die eine Aktion ausführen, werden von den
+Scheme-Standards als Funktionen betrachtet, deren Wiedergabewert unspezifiert
+ist. Der Scheme-Interpreter von LilyPond, Guile, hat den eindeutigen
+Wert @code{*unspecified*}, der normalerweise (etwa wenn man @code{set!}
+direkt auf eine Variable anwendet), aber leider nicht konsistent in
+diesen Fällen ausgegeben wird.
+
+Indem man eine LilyPond-Funktion mit @code{define-void-function} definiert,
+geht man sicher, dass dieser Spezialwert (der einzige Wert, der das
+Prädikat @code{void?} erfüllt) wiedergegeben wird.
+
+@example
+noPointAndClick =
+#(define-void-function
+ (parser location)
+ ()
+ (ly:set-option 'point-and-click #f))
+...
+\noPointAndClick % Point and Click deaktivieren
+@end example
+
+Wenn man einen Ausdruck nur wegen seiner Nebeneffekte evaluieren will
+und keinen der möglicherweise ausgegebenen Werte interpretiert haben
+will, kann man dem Ausdruck @code{\void} voranstellen:
+
+@example
+\void #(hashq-set! eine-Tabelle ein-Schlüssel ein-Wert)
+@end example
+
+Auf diese Weise kann man sicher sein, dass LilyPond dem ausgegebenen
+Wert keine Bedeutung zuweist, unabhängig davon, wo er angetroffen wird.
+Das funktioniert auch für musikalische Funktionen wie @code{\displayMusic}.
+
+
projects / lilypond.git / blobdiff