Wikifunctions:Wie man Implementierungen erstellt

This page is a translated version of the page Wikifunctions:How to create implementations and the translation is 100% complete.

Diese Seite bietet eine detailliertere Anleitung dafür, wie man Implementierungen erstellt und geht über den Überblick auf Wikifunctions:Introduction hinaus.

Arten von Implementierungen

In Wikifunctions kann eine Implementierung zwei Hauptformen annehmen: Code oder Komposition. Eine Code-Implementierung drückt die Logik der Funktion direkt in einer der verfügbaren Programmiersprachen aus (derzeit Python3 oder JavaScript). Sie ist besonders nützlich, wenn sich das Verhalten der Funktion nicht ohne Weiteres aus bestehenden Wikifunktionen ableiten lässt oder wenn eine präzise Kontrolle über die Datenverarbeitung erforderlich ist.

Eine Kompositions-Implementierung definiert die Funktion hingegen vollständig durch die Kombination bestehender Funktionen, ohne dass Code geschrieben werden muss. Kompositionen sind leichter verständlich, wiederverwendbar und lassen sich automatisch in andere Sprachen übersetzen. Sie setzen jedoch voraus, dass geeignete Bausteine bereits vorhanden sind und sind oft weniger leistungsfähig. Prüfe daher zunächst, ob dein Ziel durch Komposition erreicht werden kann. Ist dies nicht möglich oder spielen Leistung oder feingranulare Logik eine Rolle, wähle stattdessen eine Code-Implementierung.

Es gibt eine dritte Implementierungsart: integrierte Implementierungen. Diese werden vom Systemcode ausgeführt und können nicht bearbeitet werden. Höchstwahrscheinlich verfügen alle vordefinierten Funktionen über eine integrierte Implementierung. In solchen Fällen wird beim Öffnen der Implementierungsseite die Meldung "Dies ist eine integrierte Implementierung in der Kernsoftware und ist hier nicht sichtbar." angezeigt.

Praxis der testgetriebenen Entwicklung

Testgetriebene Entwicklung oder TDD ist eine Methode zur Softwareentwicklung, bei der Tests geschrieben werden, bevor der eigentliche Code geschrieben wird. Tests dienen dazu, die Funktionsweise einer Funktion anhand von Beispielen und deren Funktionsweise zu verstehen.

In Wikifunctions bietet das Schreiben von Tests als erste Tätigkeit erhebliche Vorteile. Wenn du an einer Implementierung arbeitest, kannst du deinen Code anhand der vorhandenen Tests ausführen, um sicherzustellen, dass er sich wie erwartet verhält. Dadurch lassen sich Fehler frühzeitig erkennen, noch bevor du deine Implementierung veröffentlichst. Tests sind außerdem ein effektives Mittel, um die benötigte Funktion zu beschreiben. Durch das Schreiben von Tests kommunizierst du klar das erwartete Verhalten und die Community kann bei der Implementierung helfen oder alternative Implementierungen erstellen.

Stell dir vor, du möchtest eine Funktion implementieren, die zwei Zeichenketten mit einem Leerzeichen dazwischen verknüpft. Ein einfacher Test dafür könnte so aussehen:

join_with_space( "Hello", "world" ) => "Hello world"

Sobald du das grundlegende Verhalten definiert hast, ist es wichtig, auch an Randfälle zu denken — Situationen, in denen die Eingaben so beschaffen sind, dass ein spezielles Verhalten erforderlich sein könnte.

Was passiert beispielsweise, wenn deine erste Zeichenkette mit einem Leerzeichen endet oder deine zweite mit einem Leerzeichen beginnt? Soll die Funktion alle vorhandenen Leerzeichen beibehalten und ein weiteres hinzufügen oder ein sauber formatiertes Ergebnis mit nur einem Leerzeichen zwischen den Wörtern zurückgeben? Je nach deinen Anforderungen solltest du einen Test für einen solchen Fall erstellen. Ein Test für diesen Sonderfall könnte beispielsweise einer der folgenden sein — aber nicht beide!:

join_with_space( "Hello   ",  "  world") => "Hello world"

oder ...

join_with_space( "Hello   ",  "  world") => "Hello      world"

Stell sicher, dass deine Tests alle möglichen Sonderfälle abdecken, und sobald du diese hast, stell sicher, dass sie alle mit der Funktion verbunden sind, indem du sie auswählst und auf "Verbinden" klickst.

Code-Implementierungen

Beim Erstellen einer Implementierung mit Code richtet die Wikifunctions-Benutzeroberfläche einen Code-Editor ein, in dem die ausgewählte Sprache für Syntaxhervorhebung und -validierung aktiviert ist. Sobald die zu implementierende Funktion und die Programmiersprache ausgewählt sind, wird dieser Editor mit der korrekten Funktionsvorlage konfiguriert: Entferne oder bearbeite sie nicht! Platziere deinen Code innerhalb dieser Funktionssignatur. Falls du Hilfsfunktionen benötigst, kannst du diese einfach in deiner Hauptfunktionsdeklaration deklarieren.

Verwendung von Eingabetypen in deinem Code

Die Wikifunctions-Typen String (Z6) und Boolean (Z40) können in JavaScript und Python3 wie native Typen verwendet werden. Beispielsweise lässt sich eine Zeichenkette verketten oder ein boolescher Wert direkt in einem logischen Ausdruck verwenden. Um andere Typen in deinen Code-Implementierungen zu verwenden, musst du den jeweiligen Typ genauer untersuchen, herausfinden, ob eine Umwandlung in ein natives Äquivalent existiert, und ihn entsprechend behandeln.

Nehmen wir beispielsweise an, wir möchten Python-Code schreiben, der eine Eingabe vom Typ Gregorian calendar date (Z20420) verarbeitet. Auf der Seite für diesen Typ sehen wir uns die "Typumwandler in Code" an und suchen nach einem Python-Umwandler. Der Umwandler Python converter from Gregorian calendar date (Z20424) wird auf unsere Datumseingabe angewendet, bevor unser Code ausgeführt wird. Unter "nativer Typ" sehen wir, dass unsere Eingabe ein Python-Dictionary ist, und in der Implementierung können wir die zu erwartenden Schlüssel sehen:

return {
    'K1': year,
    'K2': month,
    'K3': day
}

Wenn ein Typ keinen Umwandler besitzt, musst du direkt über seine Schlüssel auf seine Bestandteile zugreifen. Nehmen wir beispielsweise an, deine Funktion Z30000 hat einen Eingabeparameter Z30000K1 vom Typ Monolingual text (Z11). Dieser Typ besitzt zwei Schlüssel: Z11K1 für die Sprache (selbst ein Objekt vom Typ Natural language (Z60)) und Z11K2 für den Zeichenketten-Wert. Das Sprachobjekt hat wiederum einen Schlüssel Z60K1 für den Sprachcode. Um also eine Zeichenkette mit dem Sprachcode und dem Text zu erhalten, kannst du folgendes schreiben:

function Z30000( Z30000K1 ) {
	// z. B. "de: beliebiger Text"
	return Z30000K1.Z11K1.Z60K1 + ": " + Z30000K1.Z11K2;
}

Für eine Kurzübersicht der verfügbaren Typumwandlungen besuche die Tabelle der Standard-Typumwandlungen.

Rückgabe der richtigen Ausgaben

Ähnlich wie bei der Behandlung von Eingaben müssen auch Ausgaben dem in der Funktionsdefinition angegebenen Typ entsprechen. Einige können wie native Typen behandelt werden; daher wird jede Zeichenketten-Ausgabe in ein Wikifunctions-Objekt String (Z6) und jeder von deiner Implementierung zurückgegebene native boolesche Wert in ein Wikifunctions-Objekt Boolean (Z40) umgewandelt.

Typen mit "Typumwandlern aus Code" wenden die entsprechende Funktion auf die Ausgabe an, um den benötigten Typ zu erzeugen. Am Beispiel von Gregorian calendar date (Z20420) transformiert Python converter to Gregorian calendar date (Z20443) die Ausgabe deiner Implementierung – ein Dictionary mit den Schlüsseln K1, K2 und K3 – in die korrekte ZObjekt-Darstellung.

Für Typen, die keine Umwandler aus Code haben, kannst du die Ausgabeobjekte sorgfältig erstellen und zurückgeben. Stell dir beispielsweise vor, unsere Funktion Z30000 nimmt zwei Zeichenketten als Eingaben entgegen: Sprachcode und Text, und soll ein Objekt Monolingual text (Z11) zurückgeben. In Python kannst du dies mit dem Konstruktor ZObject erreichen:

def Z30000(Z30000K1, Z30000K2):
    lang_object = ZObject(
        {"Z1K1": "Z9", "Z9K1": "Z60"},
        Z60K1 = Z30000K1
    )
    return ZObject(
        {"Z1K1": "Z9", "Z9K1": "Z11"},
        Z11K1 = lang_object,
        Z11K2 = Z30000K2
    )

Oder in JavaScript:

function Z30000( Z30000K1, Z30000K2 ) {
  const langObject = new ZObject(
    new Map( [ [ "Z60K1", Z30000K1 ] ] ),
    { "Z1K1": "Z9", "Z9K1": "Z60" }
  );

  const monolingualKeys = new Map( [
    [ "Z11K1", langObject ],
    [ "Z11K2", Z30000K2 ]
  ] );
  return new ZObject(
    monolingualKeys,
    { "Z1K1": "Z9", "Z9K1": "Z11" }
  );
}

Du kannst mehr über die Klasse ZObject und andere nützliche Konstruktoren auf Wikifunctions:Execution_targets#Custom_and_non-built-in_type_conversion erfahren.

Tracked in Phabricator:
Task T392750

Stand Mai 2026 kann der Versuch, eine Liste von Listen zurückzugeben, fehlschlagen; daher ist es nicht möglich, solche Funktionen in Code zu implementieren.

Code in Python

In diesem Abschnitt geben wir ein konkretes Beispiel, wie man eine Implementierung in Form von Code in Python erstellt. Angenommen, wir möchten eine Implementierung für eine Funktion erstellen, die zwei Eingabezeichenketten durch Einfügen eines Leerzeichens dazwischen kombiniert und das Ergebnis zurückgibt. Nehmen wir an, die ZID dieser Funktion ist Z30000.

Die Implementierung wird über die ZID der Funktion definiert. Das gilt auch für die Argumente der Funktion. Im Fall der Funktion Z30000 mit ihren beiden Argumenten sollte die Funktionsvorlage also so aussehen:

def Z30000(Z30000K1, Z30000K2):

Wie bereits erwähnt, wissen wir, dass die Argumente (Z30000K1 und Z30000K2) Zeichenketten sind, daher können wir sie genauso behandeln wie native Zeichenketten in Python. Die Funktion sollte außerdem eine Zeichenkette zurückgeben. In unserem Beispiel geben wir einfach die beiden Argumente, getrennt durch ein Leerzeichen, aneinandergereiht zurück:

def Z30000(Z30000K1, Z30000K2):
    return Z30000K1 + " " + Z30000K2

Da es sich um Python handelt, vergesse nicht, diese Zeile einzurücken.

Wenn du unserem Rat gefolgt bist, TDD anzuwenden, verfügst du bereits über eine Reihe von Tests, von denen du weißt, dass sie funktionieren sollten. In diesem Fall kannst du während der Entwicklung deiner Implementierung auf den kreisförmigen Pfeil im Testbereich klicken und überprüfen, ob deine Implementierung alle Tests besteht.

Denke daran, dass die Laufzeit keinen Status hat. Gehe nicht von Werten für globale oder statische Variablen aus. Wenn du weitere Fragen dazu hast, was du in Python tun kannst und was nicht, frage auf Wikifunctions:Python implementations.

Code in JavaScript

In diesem Abschnitt geben wir ein konkretes Beispiel, wie man eine Implementierung in Form von Code in JavaScript erstellt. Angenommen, wir möchten eine Implementierung für eine Funktion erstellen, die zwei Eingabezeichenketten durch Einfügen eines Leerzeichens dazwischen kombiniert und das Ergebnis zurückgibt. Nehmen wir an, die ZID dieser Funktion ist Z30000.

Die Implementierung wird über die ZID der Funktion definiert. Das gilt auch für die Argumente der Funktion. Im Fall der Funktion Z30000 mit ihren beiden Argumenten sollte die Funktionsvorlage also so aussehen:

function Z30000( Z30000K1, Z30000K2 ) {

}

Wir wissen, dass die Argumente (Z30000K1 und Z30000K2) Zeichenketten sind, daher können wir sie in JavaScript wie native Zeichenketten behandeln. Die Funktion soll außerdem eine Zeichenkette zurückgeben. Um die Funktion zu vervollständigen, kannst du eine Zeile hinzufügen, die die Eingabezeichenketten verkettet, etwa so:

function Z30000( Z30000K1, Z30000K2 ) {
  return Z30000K1 + " " + Z30000K2;
}

Wenn du Tests wie im Abschnitt TDD oben empfohlen hast, klicke auf den kreisförmigen Pfeil im Testbereich und prüfe, ob deine Implementierung alle Tests besteht.

Denke daran, dass die Laufzeit keinen Status hat. Gehe nicht von Werten für globale oder statische Variablen aus. Wenn du weitere Fragen dazu hast, was du in JavaScript tun kannst und was nicht, frage auf Wikifunctions:JavaScript implementations.

Kompositionen

Im diesem Abschnitt geben wir ein konkretes Beispiel, wie man eine Implementierung in Form einer Komposition erstellt. Angenommen, wir möchten eine Implementierung für eine Funktion erstellen, die zwei Eingabezeichenketten durch Einfügen eines Leerzeichens dazwischen kombiniert und das Ergebnis zurückgibt. Nehmen wir an, die ZID dieser Funktion ist Z30000.

Normalerweise ist es sinnvoll, zunächst darüber nachzudenken, wie man vorhandene Funktionen kombinieren kann, um die gewünschte Ausgabe zu erzielen. Manchmal mag dies trivial sein und du kannst einfach mit dem Zusammenstellen und Funktionen fortfahren, aber in vielen Fällen lohnt es sich, die gewünschte Komposition zu notieren.

Beispielsweise könnten wir für die angegebene Funktion die vorhandene Funktion join two strings (Z10000) verwenden. Diese Funktion nimmt zwei Zeichenketten und erstellt daraus eine Zeichenkette. Aber wir müssen dazwischen ein Leerzeichen einfügen. Wir verbinden also zunächst ein Leerzeichen mit dem Ende der ersten Zeichenkette und verbinden dann die zweite Zeichenfolge mit dem Ergebnis dieser ersten Verbindung. Unsere Komposition könnte also so notiert werden:

join_strings( join_strings( Z30000K1, " " ), Z30000K2 )

Es gibt mehrere Möglichkeiten, eine Komposition zu schreiben: Beachte, dass dasselbe auch auf folgende Weise erreicht werden kann:

join_strings( Z30000K1, join_strings( " ", Z30000K2 ) )

Eine alternative Implementierung könnte auch die vorhandene Funktion join two strings with separator (Z15175) verwenden, sodass deine Komposition wie folgt aussehen könnte:

join_with_separator( Z30000K1, Z30000K2, " " )

Wie du siehst, gibt es mehrere Möglichkeiten, dies zu erreichen. Nimm dir also Zeit und erkunde die vorhandenen Funktionen, die im Wikifunctions:Catalogue verfügbar sind.

Versuchen wir, das zweite Beispiel zu erstellen, join_strings(Z30000K1, join_strings(" ", Z30000K2)).

Um dies zu erstellen:

Um eine Implementierung hinzuzufügen, klicke auf der Funktionsseite in der Tabelle "Implementierungen" auf die Schaltfläche "+".
Stelle sicher, dass die Option "Komposition" unter "Implementierung" ausgewählt ist.
Klicke auf das Symbol "›" oder auf den Link "Funktion auswählen", um die Funktionsdetails anzuzeigen.
Suche unter "Funktion" nach dem Namen der äußersten Funktion, die du verwenden möchtest, in diesem Beispiel "verbinde Zeichenketten". Wähle anschließend die gewünschte Funktion aus der Dropdown-Liste aus.
Du siehst zwei neue Felder, eines für jedes der Argumente, die für die ausgewählte Funktion benötigt werden.
Als erstes Argument möchten wir den ersten Eingabewert für unsere Funktion auswählen:
1. Klicke neben "erste Zeichenkette" auf die Schaltfläche "…" und wähle "Argumentreferenz" aus.
2. Unter "Schlüssel-ID" kannst du nun die erste Zeichenkette deiner Funktion aus dem Dropdown-Menü auswählen, das alle verfügbaren Eingaben enthält.
Für das zweite Argument möchten wir das Ergebnis eines weiteren Aufrufs von "verbinde Zeichenketten" verwenden:
1. Klicke neben "zweite Zeichenkette" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus.
2. Suche unter "Funktion" nach der Funktion, die du aufrufen möchtest und wähle sie aus, nämlich "verbinde Zeichenketten".
3. Konfiguriere die "erste Zeichenkette" für diesen inneren Funktionsaufruf, indem du einfach ein Leerzeichen in das Textfeld eingibst, und konfiguriere die "zweite Zeichenkette" wie in Schritt 6: Ändere sie mit der Schaltfläche "…" in "Argumentreferenz" und wähle dann das zweite Argument in der Dropdown-Liste aus.

Deine Komposition ist nun fertig!

Du kannst die Details mithilfe der Pfeiltasten ein- und ausblenden, um dir einen Überblick zu verschaffen. Falls du bereits Tests wie im Abschnitt TDD oben empfohlen implementiert hast, klicke im Testbereich auf den kreisförmigen Pfeil und prüfe, ob deine Implementierung die Tests besteht. Sobald deine Komposition die Tests bestanden hat, kannst du sie veröffentlichen.

Eine Wikifunctions-Kompositionsimplementierung in ihrer erweiterten Ansicht

Eine Wikifunctions-Kompositionsimplementierung in ihrer reduzierten Ansicht

Fehlerbehandlung auf Wikifunctions

Als Ersteller einer Wikifunctions-Funktion möchtest du möglicherweise den Benutzer warnen, der deine Funktion aufruft, wenn im Code ein Fehler auftritt oder seine Eingaben bestimmte Kriterien nicht erfüllen. Wenn deine Funktion beispielsweise eine Zeichenkette mit einem Namen erwartet, solltest du prüfen, ob der Name nicht leer ist, und gegebenenfalls eine verständliche Fehlermeldung anzeigen.

Hierfür kannst du Wikifunctions.Error() in deinen Code-Implementierungen oder die Funktion Throw Error (Z851) in deinen Kompositionen verwenden.

In diesem Abschnitt erfährst du:

Wie man Fehler sowohl aus Code- als auch aus Kompositions-Implementierungen auslöst,
wie man Tests für Fehlerfälle schreibt, und
wie man Fehler abfängt und behandelt, die von Funktionen ausgelöst werden, die man in seinen Kompositionen verwendet.

Fehler aus Code-Implementierungen auslösen

Sowohl beim Schreiben von JavaScript- als auch von Python-Code kannst du Wikifunctions.Error() nutzen, um die Ausführung mit einem gewünschten Fehler zu beenden.

Wikifunctions.Error() hat zwei Parameter:

Fehlertyp: Eine Zeichenkette, die die ZID des Fehlertyps enthält, den du zurückgeben möchtest.
Fehlerargumente: Eine Liste von Zeichenkettenargumenten zur Erstellung des Fehlers.

Gehen wir sie der Reihe nach durch:

Fehlertyp

Ein Fehlertyp ist ein Objekt, das eine Art von Fehler beschreibt, der im System auftreten kann. Es gibt eine Reihe vordefinierter Fehlertypen, du kannst aber auch eigene Fehlertypen erstellen, die besser zu deinem Anwendungsfall passen. Bei der Verwendung von Fehlern empfiehlt es sich, die verfügbaren Fehlertypen zu durchsuchen, die sich in dieser Liste finden.

Falls keine passenden Fehler für deinen Fall vorhanden sind, erstelle einen neuen Fehler, indem du zur Erstellungsseite gehst und im Typauswahlfeld "Fehlertyp" auswählst. Lege anschließend die erforderlichen Felder fest:

Bezeichnung – Dies ist der Haupttitel des Fehlers, der eine kurze, aber aussagekräftige Meldung enthalten sollte. Lege die Fehlerbezeichnung im rechten Feld mit dem Titel "Info" fest.

Schlüssel – Schlüssel enthalten zusätzliche Informationen zur Fehlerursache. Wenn beispielsweise eine Eingabe das falsche Format aufwies, möchtest du den Benutzer möglicherweise über den eingegebenen Inhalt informieren, wenn der Fehler auftritt. Um sie in deinen Implementierungen zu verwenden, müssen Schlüssel vom Zeichenketten sein. Um einen Schlüssel zu erstellen, klicke auf das Symbol "[+]" unterhalb von "Schlüssel", wähle unter "Werttyp" die Option "Zeichenkette" aus und füge eine aussagekräftige Bezeichnung hinzu, beispielsweise "tatsächlich Eingabe". Sobald du alle erforderlichen Schlüssel erstellt hast, kannst du deinen Fehlertyp veröffentlichen und die ID des neu erstellten Objekts speichern.

Fehlerargumente

Fehlerargumente entsprechen den Schlüsseln des Fehlertyps und sollten zusätzliche Informationen zum Verständnis des Fehlers liefern. Fehlerargumente sollten immer Zeichenketten sein.

Verwendung von Wikifunctions.Error()

Angenommen, du möchtest einen Fehler auslösen, wenn entweder deine erste oder deine zweite Eingabe leer ist. Du hast den Fehlertyp bereits erstellt und ihm wurde die ZID Z30005 zugewiesen. Dein Fehlertyp hat zwei Zeichenketten-Schlüssel:

Eingabeschlüssel: Enthält den Schlüssel der fehlerhaften Eingabe
Eingabewert: Enthält den aktuellen Wert der fehlerhaften Eingabe

Um einen Fehler in deiner JavaScript-Implementierung auszulösen, solltest du etwa Folgendes tun:

function Z30000( Z30000K1, Z30000K2 ) {
  if ( trim( Z30000K1 ) === '' ) {
    // Wenn die erste Eingabe leer ist, löse Fehler Z30005 aus
    // mit zwei Zeichenketten-Argumenten: [ erster Eingabe-Schlüssel, erster Eingabe-Wert ]
    Wikifunctions.Error( 'Z30005', [ "Z30000K1", Z30000K1 ] )
  }
  if ( trim( Z30000K2 ) === '' ) {
    // Wenn die zweite Eingabe leer ist, löse Fehler Z30005 aus
    // mit zwei Zeichenketten-Argumenten: [ zweiter Eingabe-Schlüssel, zweiter Eingabe-Wert ]
    Wikifunctions.Error( 'Z30005', [ "Z30000K2", Z30000K2 ] )
  }
  return Z30000K1 + " " + Z30000K2;
}

Um einen Fehler in deiner Python-Implementierung auszulösen, solltest du etwa Folgendes tun:

def Z30000(Z30000K1, Z30000K2):
    if Z30000K1.strip() == "":
        # Wenn die erste Eingabe leer ist, löse Fehler Z30005 aus
        # mit zwei Zeichenketten-Argumenten: [ erster Eingabe-Schlüssel, erster Eingabe-Wert ]
        Wikifunctions.Error("Z30005", ["Z30000K1", Z30000K1])

    if Z30000K2.strip() == "":
        # Wenn die zweite Eingabe leer ist, löse Fehler Z30005 aus
        # mit zwei Zeichenketten-Argumenten: [ erster Eingabe-Schlüssel, erster Eingabe-Wert ]
        Wikifunctions.Error("Z30005", ["Z30000K2", Z30000K2])

    return Z30000K1 + " " + Z30000K2

Denke daran, dass der Aufruf von Wikifunctions.Error() die Ausführung beendet!

Fehler aus Kompositionen auslösen

Wenn du eine Kompositionsimplementierung erstellst, kannst du einen Fehler auslösen, indem du die Spezialfunktion Throw Error (Z851) aufrufst.

Funktion Fehler auslösen (Z851)

Die Funktion Throw Error (Z851) ähnelt der Methode Wikifunctions.Error() und benötigt zwei Argumente:

Fehlertyp – Ein Verweis auf den Fehlertyp, den du auslösen möchtest
Fehlerparameter – Eine Liste mit den Argumenten zur Erstellung deines Fehlers, die ebenfalls Zeichenketten sein sollten.

Verwendung von Fehler auslösen

Angenommen, du möchtest deine Komposition so ändern, dass sie zuerst prüft, ob die Argumente nicht leer sind, und einen Fehler ausgibt, wenn sie ein leeres Argument findet. Wenn dann keines der Argumente leer ist, wird die ursprüngliche Komposition ausgeführt, die wie folgt aussieht:

join_with_separator( Z30000K1, Z30000K2, " " )

Dazu musst du bedingte Pfade erstellen, für die du die Funktion If (Z802) verwenden kannst. Stell es dir folgendermaßen vor:

Wenn das erste Argument leer ist, soll ein Fehler für das erste Argument ausgelöst werden
Andernfalls wird mit der Überprüfung des zweiten Arguments fortgefahren
Wenn das zweite Argument leer ist, soll ein Fehler für das zweite Argument ausgelöst werden
Andernfalls wird der Erfolgspfad verfolgt und die verbundenen Zeichenketten mit dem Leerzeichen als Trennzeichen zurückgegeben

Oder in funktionalem Pseudocode:

if (
    is_empty_string( Z30000K1 ),
    throw_error( Z30005, [ "Z30000K1", Z30000K1 ] ),
    if(
        is_empty_string( Z30000K2 ),
        throw_error( Z30005, [ "Z30000K2", Z30000K2 ] ),
        join_with_separator( Z30000K1, Z30000K2, " " )
    )
)

Lass uns das Schritt für Schritt erstellen:

Um eine Implementierung hinzuzufügen, klicke auf der Funktionsseite in der Tabelle "Implementierungen" auf die Schaltfläche "+".
Stelle sicher, dass die Option "Komposition" unter "Implementierung" ausgewählt ist.
Klicke auf das Symbol "›" oder auf den Link "Funktion auswählen", um die Funktionsdetails anzuzeigen.
Suche unter "Funktion" nach der äußersten Funktion, die du verwenden möchtest, in diesem Fall "wenn", und wähle sie aus.
Überprüfe die Gültigkeit des ersten Arguments:
1. Klicke neben "Bedingung" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der Funktion "ist leere Zeichenkette" und wähle sie aus
3. Klicke neben "Eingabe" auf die Schaltfläche "…" und wähle "Argumentreferenz" aus
4. Wähle unter "Schlüssel-ID" die erste Eingabe aus (z. B. "erste Zeichenkette")
5. Du kannst den Funktionsaufruf der "Bedingung" nun bei Bedarf ausblenden, indem du auf den Pfeil nach unten neben "Bedingung" klickst. Es sollte dann etwa Folgendes angezeigt werden: "f(x) ist leere Zeichenkette ( → erste Zeichenkette )"
Fehler auslösen, wenn die Bedingung wahr ist:
1. Klicke neben "dann" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der Funktion "Fehler auslösen" und wähle sie aus
3. Suche unter "Fehlertyp" nach deinem Fehlertyp (du kannst die Fehler-ID direkt eingeben, wenn du sie kennst, z. B. Z30005) und wähle ihn aus
4. Füge unter "Fehlerparameter" zwei Elemente hinzu, indem du auf die Schaltfläche "+" klickst
5. Lege für "Objekt 1" (fehlerhafter Argumentschlüssel) den Typ auf "Zeichenkette" fest und trage die Argumentkennung ein (z. B. "erste Eingabe" oder "Z30000K1")
6. Klicke für "Objekt 2" (fehlerhafter Argumentwert) auf die "…" neben "Objekt 2" und wähle "Argumentreferenz" aus
7. Wähle unter "Schlüssel-ID" die erste Eingabe aus (z. B. "erste Zeichenkette")
8. Du kannst den Funktionsaufruf "dann" nun bei Bedarf ausblenden, indem du auf den Pfeil nach unten neben "dann" klickst. Es sollte dann etwa Folgendes angezeigt werden: "f(x) Fehler auslösen ( ungültiges Format, typisierte Liste ( Objekt, "erste Eingabe", → erste Zeichenkette ) )"
Prüfe das zweite Argument, wenn das erste korrekt war:
1. Klicke neben "sonst" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der Funktion "wenn" und wähle sie aus
3. Richte eine "Bedingung" ein, um die Gültigkeit des zweiten Arguments zu überprüfen, indem du das gleiche Verfahren wie in Schritt 5 beschrieben anwendest.
4. Richte "dann" so ein, dass beim zweiten Argument ein Fehler ausgelöst wird, indem du das gleiche Verfahren wie in Schritt 6 beschrieben anwendest.
Richte schließlich den Erfolgspfad ein:
1. Klicke neben dem verschachtelten "sonst" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der gewünschten Funktion, in diesem Fall "vereinige zwei Zeichenketten mit Trennzeichen", und wähle sie aus
3. Klicke neben "erste Zeichenkette" auf die Schaltfläche "…" und setze sie auf "Argumentreferenz", wähle anschließend "erste Zeichenkette" aus
4. Klicke neben "zweite Zeichenkette" auf die Schaltfläche "…" und setze sie auf "Argumentreferenz", wähle anschließend "zweite Zeichenkette" aus
5. Füge unter "Trennzeichen" ein Leerzeichen in das Textfeld ein

Der resultierende Funktionsaufruf sollte folgendermaßen aussehen:

Wikifunctions-Komposition mit der Funktion Fehler auslösen

Wikifunctions-Komposition mit der Funktion Fehler auslösen in ihrer reduzierten Ansicht

Fehlerbehandlung in Kompositionen

Es ist zwar nützlich, Funktionen das Auslösen erwarteter Fehler zu ermöglichen, aber es ist entscheidend, Fehler in den eigenen Kompositionen behandeln zu können, um diese Funktionen sicher verwenden zu können.

Angenommen, du möchtest eine neue Funktion "vollständiger Name einer Person" erstellen – wir bezeichnen sie mit der ZID Z30010. Diese Funktion soll den vollständigen Namen einer Person anhand ihres Vor- und Nachnamens zurückgeben. Ist jedoch eines der beiden Felder leer, soll sie stattdessen den Text "Unbekannt" zurückgeben.

Du könntest eine Komposition erstellen, indem du unsere Beispielfunktion "verbinde zwei Zeichenketten mit Leerzeichen" oder Z30000 verwendest, um den Namen zu generieren. Wenn eine der Eingaben leer ist, weißt du, dass Z30000 einen Fehler vom Typ Z30005 auslöst. Mithilfe der Funktion Try-Catch Function (Z850) als Wrapper kannst du die Verbindungsoperation ausführen und einen möglichen Fehler abfangen, indem du einfach "Unbekannt" zurückgibst, wenn er auftritt.

Try-Catch-Funktion (Z850)

Die Funktion Try-Catch Function (Z850) ist eine integrierte Funktion mit der ZID Z850 und benötigt drei Argumente:

Funktionsaufruf – Der erste Funktionsaufruf, der ausgeführt werden soll. Wenn kein Fehler auftritt, ist die Antwort das Ergebnis dieses Funktionsaufrufs.
Fehlertyp – Ein Fehlertyp, der abgefangen werden soll, falls er während der Ausführung des ersten Funktionsaufrufs auftritt.
Fehlerhandler – Ein Funktionsaufruf, der ausgeführt wird, falls der oben genannte Fehler während der Ausführung des ursprünglichen Funktionsaufrufs auftritt. In diesem Fall wird das Ergebnis der Fehlerbehandlung zurückgegeben.

Verwendung der Try-Catch-Funktion

Sobald wir alle Funktionen für unsere Komposition haben, können wir sie folgendermaßen gestalten:

try_catch(
    join_with_space( Z30010K1, Z30010K2 ),
    Z30005,
    echo( "Unknown" )
)

Das bedeutet:

Die Funktion "verbinde zwei Zeichenketten mit Leerzeichen" wird mit den beiden Eingaben ausprobiert und wenn alles erfolgreich verläuft, wird das Ergebnis dieser Funktion zurückgegeben
Wenn eine der Eingaben leer ist, löst "verbinde zwei Zeichenketten mit Leerzeichen" einen Fehler vom Typ Z30005 aus
Unsere Try-Catch Function (Z850) erkennt dann diesen Fehler und führt die Funktion Echo (Z801) aus, die "Unbekannt" zurückgibt

Lass uns das Schritt für Schritt erstellen:

Um eine Implementierung hinzuzufügen, klicke auf der Funktionsseite in der Tabelle "Implementierungen" auf die Schaltfläche "+".
Stelle sicher, dass die Option "Komposition" unter "Implementierung" ausgewählt ist.
Klicke auf das Symbol "›" oder auf den Link "Funktion auswählen", um die Funktionsdetails anzuzeigen.
Suche unter "Funktion" nach der äußersten Funktion, die du verwenden möchtest, in diesem Fall "Try-Catch-Funktion", und wähle sie aus.
Richte den Hauptfunktionsaufruf ein:
1. Klicke unterhalb des Feldes, in dem die "Try-Catch-Funktion" ausgewählt ist, neben dem Schlüssel "Funktionsaufruf" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der Funktion "verbinde zwei Zeichenketten mit Leerzeichen" und wähle sie aus
3. Klicke neben "erste Zeichenkette" auf die Schaltfläche "…" und wähle "Argumentreferenz" aus, wähle anschließend das Argument "erster Name" aus der Dropdown-Liste aus.
4. Klicke neben "zweite Zeichenkette" auf die Schaltfläche "…" und wähle "Argumentreferenz" aus, wähle anschließend das Argument "zweiter Name" aus der Dropdown-Liste aus.
Wähle den abzufangenden Fehler aus:
1. Suche unter "Fehlertyp" nach "ungültige Zeichenkette" und wähle es aus – du kannst direkt nach der ZID Z30005 suchen
Richte den Funktionsaufruf für den Fehlerhandler ein:
1. Klicke neben "Fehlerhandler" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
2. Suche unter "Funktion" nach der Funktion "Echo" und wähle sie aus
3. Suche unter "Eingabe" und "Typ" den Typ "Zeichenkette" und wähle ihn aus
4. Gib nun unter "Eingabe" im Textfeld "Unbekannt" ein

Die resultierende Funktion sollte folgendermaßen aussehen:

Wikifunctions-Komposition mit der Try-Catch-Funktion in ihrer erweiterten Ansicht

Wikifunctions-Komposition mit der Try-Catch-Funktion in ihrer reduzierten Ansicht

Testen deiner Fehlerfälle

Wie bereits im Abschnitt über die Anwendung von TDD erläutert, ist es wichtig, nicht nur die häufigsten Ausführungspfade, sondern auch mögliche Randfälle zu testen. Ebenso wichtig ist es, das Fehlerverhalten zu prüfen. In diesem Abschnitt stellen wir dir die notwendigen Werkzeuge vor, um zu testen, ob deine Funktion bei bestimmten Eingaben fehlschlägt und ob die Fehlermeldung den Erwartungen entspricht.

Dazu benötigst du zwei weitere Systemfunktionen:

ist Fehlertyp (Z852)

Die Funktion Is error type (Z852) ist eine integrierte Funktion mit der ZID Z852 und benötigt zwei Argumente:

Fehler – Ein Error (Z5)-Objekt, das bei einem fehlgeschlagenen Aufruf ausgelöst werden kann. Eine Fehlerinstanz hat einen Typ und einen Wert.
Fehlertyp – Ein Verweis auf einen Error type (Z50), der mit dem als erstes Argument übergebenen Fehlertyp verglichen wird. Ist dies der Fall, gibt die Funktion wahr zurück.

Fehler erhalten, ausgelöst durch Funktionsaufruf (Z853)

Die Funktion Get error thrown by function call (Z853) ist eine integrierte Funktion mit der ZID Z853 und benötigt ein Argument:

Funktionsaufruf – Ein Funktionsaufruf, der entweder einen erfolgreichen Wert beliebigen Typs zurückgibt oder einen Fehler auslöst.

Diese Funktion gibt ein Typed pair (Z882) zurück, wobei an erster Stelle ein Boolean (Z40) und an zweiter Stelle ein Object (Z1) steht:

Wenn der Funktionsaufruf erfolgreich ist und somit keinen Fehler auslöst, enthält das zurückgegebene Paar an erster Stelle falsch und an zweiter Stelle leer.
Wenn der Funktionsaufruf einen Fehler auslöst, enthält das zurückgegebene Paar an erster Stelle wahr und an zweiter Stelle den abgefangenen Fehler.

Um diese Funktion in deinen Kompositionen zu verwenden, musst du möglicherweise die zusätzlichen Funktionen verwenden:

Fehler testen

Angenommen, unsere Zielfunktion "verbinde zwei Zeichenketten mit Leerzeichen" oder Z30000 löst einen Fehler vom Typ Z30005 aus, und wir möchten dieses Verhalten testen. Dazu müssen wir Folgendes tun:

Einen fehlgeschlagenen Funktionsaufruf auslösen
Den Fehler mit der Funktion Get error thrown by function call (Z853) erhalten
Mit Is error type (Z852) prüfen, ob der Fehler den richtigen Typ hat

Tests haben zwei Felder:

Aufruf – Ein Funktionsaufruf, der mit den zu testenden Eingaben eine Ausgabe erzeugt. Dieser Aufruf gibt einen Wert zurück.
Ergebnisprüfung – Ein Funktionsaufruf, der überprüft, ob der vom vorherigen Aufruf zurückgegebene Wert dem erwarteten Wert entspricht. Das erste Argument dieses Funktionsaufrufs wird automatisch mit dem Rückgabewert des ersten Aufrufs belegt.

Für eine Schritt-für-Schritt-Anleitung zum Erstellen von Tests siehe Wikifunctions:Introduction#Create_tests.

In unserem Beispiel können wir es so strukturieren — aber das ist nicht die einzige Möglichkeit!

Der Aufruf, der ein Error (Z5)-Objekt zurückgibt:

error = get_second_element_of_typed_list(
    get_error_thrown_by(
        join_strings_by_whitespace( "", "not empty" )
    )
)

Und die Ergebnisprüfung, die das Error (Z5)-Objekt als erstes Argument verwendet:

is_error_type( error, Z30005 )

Lass uns das Schritt für Schritt tun:

Um einen Test hinzuzufügen, klicke auf der Funktionsseite in der Tabelle "Tests" auf die Schaltfläche "+". Die Felder "Aufruf" und "Ergebnisprüfung" enthalten bereits vordefinierte Funktionen. Um die Fehler zu testen, müssen wir diese jedoch ändern.
Als Erstes richten wir den Aufruf ein:
1. Klicke unter "Aufruf" auf die Schaltfläche "›", um den Funktionsaufruf zu erweitern.
2. Bearbeite das Feld unter "Funktion" und suche die Funktion "erhalte zweites Element eines typisierten Paars" und wähle sie aus
3. Klicke anschließend neben "typisiertes Paar" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
4. Suche unter "Funktion" nach der Funktion "Fehler erhalten, ausgelöst durch Funktionsaufruf" und wähle sie aus
5. Klicke neben "Funktionsaufruf" auf die Schaltfläche "…" und wähle "Funktionsaufruf" aus
6. Suche unter "Funktion" nach der Funktion "verbinde zwei Zeichenketten mit Leerzeichen" (oder nach ZID Z30000) und wähle sie aus
7. Lege nun die Eingaben so fest, dass ein Fehler auftritt: Mindestens eine von ihnen muss leer sein.
8. Du kannst jetzt deinen "Aufruf" durch erneutes Klicken auf den Pfeil nach unten wieder ausblenden, wenn du möchtest!
Als Nächstes richten wir die Ergebnisprüfung ein:
1. Klicke unter "Ergebnisprüfung" auf die Schaltfläche "›", um den Funktionsaufruf zu erweitern.
2. Bearbeite das Feld unter "Funktion" und suche die Funktion "ist Fehlertyp" und wähle sie aus
3. Du wirst nun nur noch aufgefordert, das zweite Argument zu konfigurieren. Suche unter "Fehlertyp" nach deinem Fehlertyp Z30005 und wähle ihn aus.
Und du bist fertig! Du kannst jetzt auf den kreisförmigen Pfeil im Feld "Implementierungen" klicken und solltest grüne Häkchen sehen.

Wenn alles geklappt hat, kannst du deinen Test jetzt speichern. Er sollte folgendermaßen aussehen:

Testen eines Fehlers mit den Funktionen Fehler erhalten und ist Fehlertyp in ihrer erweiterten Ansicht

Testen eines Fehlers mit den Funktionen Fehler erhalten und ist Fehlertyp in ihrer reduzierten Ansicht

Debuggen deiner Implementierungen

Manchmal läuft etwas schief. Eine Funktion verhält sich möglicherweise anders als erwartet oder ein Wert erscheint merkwürdig. Implementierungen können mitunter sehr komplex sein, und da sie in einer Spielwiesen-Umgebung ausgeführt werden, kann die Fehlersuche extrem schwierig erscheinen. Um das Verständnis der Vorgänge innerhalb eines Funktionsaufrufs zu erleichtern, bietet Wikifunctions einige Debugging-Werkzeuge.

Diese Werkzeuge verändern nicht das Ergebnis einer Funktion, sondern fügen den zurückgegebenen Metadaten zusätzliche Informationen hinzu, die du nach dem Ausführen der Funktion einsehen kannst. Du kannst Wikifunctions.Debug() in deinen Code-Implementierungen oder die Funktion Add debug log to function call (Z854) in deinen Kompositionen verwenden.

In diesem Abschnitt erfährst du:

Wie man Debug-Meldungen sowohl aus Code- als auch aus Kompositions-Implementierungen hinzufügt,
Wie man die Metadaten manuell oder über die Benutzeroberfläche untersucht, um diese Protokolle einzusehen.

Debuggen deiner Code-Implementierungen

Beim Schreiben von Code, sowohl in JavaScript als auch in Python3, kannst du Wikifunctions.Debug() verwenden, um eine Meldung zu deinem Debug-Protokoll hinzuzufügen und die Ausführung fortzusetzen.

Wikifunctions.Debug() hat einen Parameter, der üblicherweise als Zeichenkette erwartet wird. Jedes andere als Parameter übergebene Objekt wird jedoch direkt in eine Zeichenkette umgewandelt.

Um zu unseren Code-Implementierungen für unsere Beispielfunktion "verbinde zwei Zeichenketten mit Leerzeichen" Debug-Protokolle hinzuzufügen, können wir dies in JavaScript tun:

function Z30000( Z30000K1, Z30000K2 ) {
  if ( trim( Z30000K1 ) === '' ) {
    Wikifunctions.Debug( `first input is empty "${ Z30000K1 }"` );
    Wikifunctions.Error( 'Z30005', [ "Z30000K1", Z30000K1 ] )
  }
  if ( trim( Z30000K2 ) === '' ) {
    Wikifunctions.Debug( `second input is empty "${ Z30000K2 }"` );
    Wikifunctions.Error( 'Z30005', [ "Z30000K2", Z30000K2 ] )
  }

  Wikifunctions.Debug( "both inputs are fine" );
  return Z30000K1 + " " + Z30000K2;
}

Und das Gleiche in deiner Python3-Implementierung:

def Z30000(Z30000K1, Z30000K2):
    if Z30000K1.strip() == "":
        Wikifunctions.Debug( 'first input is empty "'+Z30000K1+'"' )
        Wikifunctions.Error("Z30005", ["Z30000K1", Z30000K1])

    if Z30000K2.strip() == "":
        Wikifunctions.Debug( 'second input is empty "'+Z30000K2+'"' )
        Wikifunctions.Error("Z30005", ["Z30000K2", Z30000K2])

    Wikifunctions.Debug( 'both inputs are fine' )
    return Z30000K1 + " " + Z30000K2

Auf diese Weise fügen wir deinen Debug-Protokollen in jedem Fall eine Meldung hinzu:

Schlägt der Funktionsaufruf bei der Überprüfung der ersten oder zweiten Eingabe fehl, ist das Ergebnis der Ausführung ein Fehler, enthält aber einen informativen Protokolleintrag darüber, welcher Zweig den Fehler verursacht hat.
Wenn der Funktionsaufruf erfolgreich ist — weil beide Eingaben gültig sind — gibt der Funktionsaufruf die verbundene Zeichenkette zurück, aber die zurückgegebenen Metadaten enthalten auch ein Debug-Protokoll.

Debuggen deiner Kompositionen

Zur Unterstützung des Debuggens von Kompositionen stellt Wikifunctions die integrierte Funktion Add debug log to function call (Z854) bereit. Mit dieser Funktion kannst du Debug-Meldungen an die Ausführung jedes Funktionsaufrufs anhängen, der die endgültige Ausgabe erzeugt. Die während der Auswertung gesammelten Debug-Protokolle werden als Teil der Ausführungsmetadaten unter dem Schlüssel executorDebugLogs zurückgegeben.

Debug-Protokoll zu Funktionsaufruf hinzufügen (Z854)

Die Funktion Add debug log to function call (Z854) ist eine integrierte Funktion mit der ZID Z854 und benötigt zwei Argumente:

Funktionsaufruf – Jede Komposition, die du ausführen möchtest.
Debug-Protokoll – Eine Zeichenketten-Meldung, die protokolliert wird, wenn der angegebene Funktionsaufruf ausgewertet wird.

Wenn der umschlossene Funktionsaufruf ausgeführt wird, wird die bereitgestellte Meldung zu den Ausführungsprotokollen hinzugefügt. Wird dieser Funktionsaufruf nicht ausgeführt oder ist seine Ausführung nicht Teil der endgültigen Ausgabe, erscheint sein Debug-Protokoll nicht in den Metadaten des Endergebnisses.

Diese integrierte Funktion ist besonders nützlich, wenn du beobachten möchtest:

Welcher Zweig einer Bedingung ausgeführt wurde, oder
Die Reihenfolge der Auswertung in einer Komposition.

Verwendung von Debug-Protokoll zu Funktionsaufruf hinzufügen

Angenommen, du möchtest zu unserer Beispielfunktion "verbinde zwei Zeichenketten mit Leerzeichen" oder Z30000 Debug-Protokolle hinzufügen, sodass für die verschiedenen möglichen Ergebnisse unterschiedliche Meldungen angezeigt werden. Du könntest unsere integrierte Debugging-Funktion wie folgt verwenden:

if (
    is_empty_string( Z30000K1 ),
    add_debug_log( throw_error( Z30005, ... ), 'failed on first input' )
    if(
        is_empty_string( Z30000K2 ),
        add_debug_log( throw_error( Z30005, ... ), 'failed on second input' ),
        add_debug_log(
            join_with_separator( Z30000K1, Z30000K2, " " ),
            'both inputs are ok!'
        )
    )
)

Dies bewirkt Folgendes:

Wird die Funktion mit einer leeren ersten Eingabe aufgerufen, gibt sie eine Fehlermeldung zurück und die Metadaten enthalten einen Eintrag executorDebugLogs mit dem Protokoll-Eintrag "Fehler bei erster Eingabe".
Wird der Aufruf mit einer leeren zweiten Eingabe aufgerufen, schlägt der Aufruf ebenfalls fehl, die protokollierte Meldung lautet jedoch "Fehler bei zweiter Eingabe".
Bei Aufruf mit gültigen Eingaben gibt die Funktion eine erfolgreiche Antwort zurück und zusätzlich enthalten die Metadaten im Schlüssel executorDebugLogs "Beide Eingaben sind in Ordnung".

So würde diese Komposition aussehen:

Implementierung der Komposition mit Debug-Protokoll hinzufügen, um alle möglichen Ausführungspfade zu protokollieren

Zugriff auf Ausführungs-Debug-Protokolle

Unabhängig davon, ob deine Ausführungsprotokolle über Wikifunctions.Debug() oder die integrierte Funktion Add debug log to function call (Z854) hinzugefügt werden, werden sie als Teil der Antwort-Metadaten zurückgegeben. Um die Protokolle zu sehen, klicke nach dem Ausführen deiner Funktion auf die Schaltfläche "Details", die unten im Abschnitt "Ergebnis" erscheint.

Die Fehler- und Debug-Informationen werden oben im Dialogfeld "Details" angezeigt.

Dies ist das Ergebnis, das du sehen würdest, wenn du die Komposition aus unserem vorherigen Beispiel mit gültigen und ungültigen Eingaben ausführst:


Funktions-Metadatendialog für eine erfolgreiche Ausführung: zeigt keine Fehler an, sondern das Protokoll der erfolgreichen Ausführung: "Beide Eingaben sind in Ordnung!"	Funktions-Metadatendialog für eine fehlgeschlagene Ausführung: zeigt die Fehlerinformationen und das zusätzliche Ausführungsprotokoll für den ersten Fehlerzweig an: "Fehler bei erster Eingabe"