doc/efun/add_action

SYNOPSIS
        #include <commands.h>

        void add_action(string|closure fun, string cmd);
        void add_action(string|closure fun, string cmd, int flag);
        void add_action(string|closure fun);        /* veraltet */

BESCHREIBUNG
        Setzt eine lokale Funktion fun, die aufgerufen wird, wenn der Spieler
        das Kommandos <cmd< eintippt. Der Funktion werden die Argumente des
        vom Spieler eingegebenen Kommandos als string uebergeben. Die
        Funktion muss entweder 1 zurueck geben, wenn das Kommando erfolgreich
        ausgefuehrt werden konnte, sonst 0.

        Wenn das Kommando nicht erfolgreich ausgefuehrt werden konnte, sucht
        der Parser weiter nach einer passenden Funktion, bis eine solche
        1 zurueck liefert. Falls der Parser keine Funktion findet, wird an
        den Spieler eine Fehlermeldung ausgegeben. ("Wie bitte?")

        Wenn add_action() ohne das zweite Argument (string cmd) aufgerufen
        wird, muss dieses mit add_verb() oder add_xverb() angegeben werden.
        DIESE DEKLARATION IST JEDOCH VERALTET UND SOLLTE NICHT VERWENDET
        WERDEN. Sie funktioniert auch nur, wenn USE_DEPRECATED gesetzt ist.

        Die Funktion fun wird mit einem string als Argument aufgerufen, der
        die Worte nach dem Verb in der Inputzeile enthaelt. Das Verb kann
        mit der Efun query_verb() abgefragt werden. Das Verb ist immer das
        erste Wort in der Inputzeile bis zum ersten Leerschlag.

        add_action() muss immer aus einer init() Routine heraus aufgerufen
        werden. Das Objekt, welches das Kommando cmd definiert, muss sich in
        der Umgebung des Spielers befinden; also entweder der Spieler selbst,
        im Inventar des Spielers, der Raum, in dem sich der Spieler befindet
        oder ein Objekt im gleichen Raum wie der Spieler. Wenn der Spieler
        die Umgebung des Objekts verlaesst, werden alle von add_action()
        definierten Kommandos automatisch entfernt.

        Die Kommandos lassen sich auch manuell entfernen. Die Efun dazu lautet
        remove_actions().

        Wenn das Argument <flag> AA_SHORT (d.h. 1) ist, koennen Argumente von
        cmd ohne einen Leerschlag an cmd angehaengt sein. An die Funktion fun
        werden alle Zeichen nach dem ersten Leerschlag als Argument
        uebergeben.

        Wenn <flag> AA_NOSPACE (d.h. 2) ist, koennen die Argumente wiederum
        ohne Leerschlag ans Verb angehaengt sein. Im Unterschied zu AA_SHORT
        werden alle Zeichen nach dem Verb als Argument an die Funktion
        uebergeben. Die Zeichen, welche nicht durch einen Leerschlag vom
        Verb getrennt sind, werden ZUSAETZLICH von query_verb() zurueck
        gegeben.

        Wenn <flag> AA_IMM_ARGS (3) ist, werden alle Zeichen nach dem Verb
        als Argument uebergeben, nicht aber von query_verb() beruecksichtigt.

        Wenn -<flag> eine negative Zahl ist, muss das vom Spieler eingegebene
        Kommando nur mit den ersten <flag> Zeichen von cmd uebereinstimmen.

        Als Name fuer die Funktion fun duerfen keine geschuetzten Namen wie
        zum Beispiel create, init, reset, heart_beat etc. verwendet werden
        (eine vollstaendige Liste findet man unter /doc/applied/).

BEISPIELE
        add_action("geh_rein", "betrete");

        Wenn der Spieler "betrete" eintippt, wird die Funktion geh_rein()
        aufgerufen.

        add_action("disfunc", "disconnect", AA_NOSPACE);

        Die Funktion disfunc() wird aufgerufen, wenn der Spieler "disconnect"
        oder eine Abkuerzung davon (zum Beispiel "di" oder "discon") eingibt.
        Laengere Worte (zum Beispiel "disconnecting") werden NICHT erkannt.
        Um rauszufinden, was der Spieler tatsaechlich eingegeben hat, muss
        query_verb() aufgerufen werden.

        add_action("fun", "cmd");
        add_action("fun", "scmd", AA_SHORT);
        add_action("fun", "ncmd", AA_NOSPACE);
        add_action("fun", "icmd", AA_IMM_ARGS);

        Die folgende Tabelle zeigt, was die oben aufgefuehrten Kommandos bzw.
        <flag> fuer Werte an query_verb() und als Argumente an die Funktion
        fun uebergeben:

        |-------------------|--------------|----------------------------|
        | Eingabe           | query_verb() | Argument der Funktion fun  |
        |-------------------|--------------|----------------------------|
        | "cmd"             | "cmd"        | 0                          |
        | "cmd bla fasel"   | "cmd"        | "bla fasel"                |
        |-------------------|--------------|----------------------------|
        | "scmd"            | "scmd"       | 0                          |
        | "scmd bla"        | "scmd"       | "bla"                      |
        | "scmdbla"         | "scmdbla"    | 0                          |
        | "scmd bla fasel"  | "scmd"       | "bla fasel"                |
        | "scmdbla fasel"   | "scmdbla"    | "fasel"                    |
        |-------------------|--------------|----------------------------|
        | "ncmd"            | "ncmd"       | 0                          |
        | "ncmd bla"        | "ncmd"       | " bla"                     |
        | "ncmdbla"         | "ncmdbla"    | "bla"                      |
        | "ncmd bla fasel"  | "ncmd"       | " bla fasel"               |
        | "ncmdbla fasel"   | "ncmdbla"    | "bla fasel"                |
        |-------------------|--------------|----------------------------|
        | "icmd"            | "icmd"       | 0                          |
        | "icmd bla"        | "icmd"       | " bla"                     |
        | "icmdbla"         | "icmd"       | "bla"                      |
        | "icmd bla fasel"  | "icmd"       | " bla fasel"               |
        | "icmdbla fasel"   | "icmd"       | "bla fasel"                |
        |-------------------|--------------|----------------------------|

GESCHICHTE
        Das Argument <flag> < 0 wird seit 3.2@127 unterstuetzt, aber erst ab
        LDMud 3.2.8 richtig implementiert. LDMud 3.2.9 fuehrte das AA_IMM_ARGS
        Flag ein. Ab LDMud 3.5 kann man Closures als Funktionen uebergeben.

SIEHE AUCH
        query_verb(E), query_command(E), add_verb(E), add_xverb(E), init(A)