Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/add_action b/doc/efun/add_action
index 19813d2..000bf54 100644
--- a/doc/efun/add_action
+++ b/doc/efun/add_action
@@ -1,117 +1,122 @@
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 */
+ void add_action(string|closure fun, string cmd)
+ void add_action(string|closure fun, string cmd, int flag)
-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.
+DESCRIPTION
+ Set up a local function fun to be called when user input
+ matches the command cmd. Functions called by a user command
+ will get the arguments as a string. It must then return 0 if
+ it was the wrong command, otherwise 1.
- 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?")
+ If it was the wrong command, the parser will continue
+ searching for another command, until one returns 1 or give an
+ error message to the user.
- 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.
+ For example, there can be a wand and a rod. Both of these
+ objects define as command "wave". One of them will be randomly
+ called first, and it must look at the argument, and match
+ against "wand" or "rod" respectively.
- 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.
+ The function associated to a command will be called with a
+ string as argument which stands for the given words behind the
+ typed command. The verb entered can be retrieved using the
+ query_verb() efun and is always the first word in the input
+ line up to the first space.
- 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.
+ Always have add_action() called only from an init() routine.
+ The object defining these commands must be present to the
+ user, either being the user, being carried by the user,
+ being the room around the user, or being an object in the
+ same room as the user. If the player leaves this vicinity of the
+ object, the actions are automatically removed.
- Die Kommandos lassen sich auch manuell entfernen. Die Efun dazu lautet
- remove_actions().
+ Actions can also be removed on demand with the remove_actions() efun.
- 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.
+ If argument <flag> is AA_SHORT (1), then the arguments may
+ follow the verb without separating space. Any arguments after
+ the first space are passed as argument string.
- 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.
+ If argument <flag> is AA_NOSPACE (2), then again the arguments
+ may follow the verb without separating space. In contrast to
+ AA_SHORT, all characters following the verb are passed as
+ the argument string. However, note that the characters immediately
+ following the given verb are passed as argument AND as result
+ of query_verb().
- Wenn <flag> AA_IMM_ARGS (3) ist, werden alle Zeichen nach dem Verb
- als Argument uebergeben, nicht aber von query_verb() beruecksichtigt.
+ If argument <flag> is AA_IMM_ARGS (3), then again the arguments
+ may follow the verb without separating space. All characters following
+ the given verb are passed as argument, and only as argument.
- Wenn -<flag> eine negative Zahl ist, muss das vom Spieler eingegebene
- Kommando nur mit den ersten <flag> Zeichen von cmd uebereinstimmen.
+ If argument <flag> is negative, the verb given by the player
+ has to match only the leading -<flag> characters of the verb <cmd>.
- 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/).
+ Never use one of the functions 'create' 'reset' 'init' 'exit'
+ 'heart_beat' etc as the first argument to add_action(). In
+ general, a function with a name defined in /doc/applied should
+ have the behaviour defined there.
-BEISPIELE
- add_action("geh_rein", "betrete");
- Wenn der Spieler "betrete" eintippt, wird die Funktion geh_rein()
- aufgerufen.
+EXAMPLES
+ add_action("GoInside", "enter");
- add_action("disfunc", "disconnect", AA_NOSPACE);
+ When typing "enter" the function GoInside() will be invoked.
- 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("DisFunc", "dis", AA_SHORT);
- add_action("fun", "cmd");
- add_action("fun", "scmd", AA_SHORT);
- add_action("fun", "ncmd", AA_NOSPACE);
- add_action("fun", "icmd", AA_IMM_ARGS);
+ Whenever you type in a command which starts with "dis" the
+ function DisFunc() will be called. To get the real word which
+ was typed in (because until now you only know that it was a
+ command beginning with "dis") you have to call the efun
+ query_verb().
- Die folgende Tabelle zeigt, was die oben aufgefuehrten Kommandos bzw.
- <flag> fuer Werte an query_verb() und als Argumente an die Funktion
- fun uebergeben:
+ add_action("DisFunc", "disconnect", AA_NOSPACE);
- |-------------------|--------------|----------------------------|
- | 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" |
- |-------------------|--------------|----------------------------|
+ The function DisFunc() will be called for all commands which
+ use "disconnect" or a shortened form like "di", "dis" or
+ "discon" as verb. The command 'disconnecting' will _not_
+ be recognized. To get the real word which was typed in
+ you have to call the efun query_verb().
-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)
+ add_action("...", "cmd");
+ add_action("...", "xcmd", AA_SHORT);
+ add_action("...", "scmd", AA_NOSPACE);
+ add_action("...", "icmd", AA_IMM_ARGS);
+
+ When given the following commands, the driver will parse it
+ as described below. 'verb' is what query_verb() would return,
+ 'arg' is what would be passed to the command function.
+
+ "cmd" -> verb "cmd", arg 0
+ "cmd foo bar" -> verb "cmd", arg "foo bar"
+
+ "xcmd" -> verb "xcmd", arg 0
+ "xcmd foo" -> verb "xcmd", arg "foo"
+ "xcmdfoo" -> verb "xcmdfoo", arg 0
+ "xcmd foo bar" -> verb "xcmd", arg "foo bar"
+ "xcmdfoo bar" -> verb "xcmdfoo", arg "bar"
+
+ "scmd" -> verb "scmd", arg 0
+ "scmd foo" -> verb "scmd", arg " foo"
+ "scmdfoo" -> verb "scmdfoo", arg "foo"
+ "scmd foo bar" -> verb "scmd", arg " foo bar"
+ "scmdfoo bar" -> verb "scmdfoo", arg "foo bar"
+
+ "icmd" -> verb "icmd", arg 0
+ "icmd foo" -> verb "icmd", arg " foo"
+ "icmdfoo" -> verb "icmd", arg "foo"
+ "icmd foo bar" -> verb "icmd", arg " foo bar"
+ "icmdfoo bar" -> verb "icmd", arg "foo bar"
+
+
+HISTORY
+ The flag < 0 argument was supported since 3.2@127, but not
+ really implemented before LDMud 3.2.8.
+ LDMud 3.2.9 introduced the AA_IMM_ARGS flag.
+ LDMud 3.3 removed the historical add_action(fun) notation.
+ Since LDMud 3.5 the function can be given as a closure.
+
+SEE ALSO
+ query_verb(E), query_command(E), remove_action(E), init(A)