Manpages aus Driver aktualisiert.
Hierbei handelt es sich um Manpages, welche vom MG
modifiziert wurden.
Die Bemerkungen und Beispiele wurden ausgelagert in
separate Manpages, um zukuenftige Aktualisierungen
aus dem Driver zu erleichtern.
Change-Id: I5a6248cd65a8cd841831617a92aa1ee191dbf661
diff --git a/doc/efun/add_action b/doc/efun/add_action
index 8b0f778..19813d2 100644
--- a/doc/efun/add_action
+++ b/doc/efun/add_action
@@ -1,97 +1,72 @@
-add_action(E)
-FUNKTION:
- void add_action(string fun, string cmd)
- void add_action(string fun, string cmd, int flag)
+SYNOPSIS
+ #include <commands.h>
-ARGUMENTE:
- fun
- gerufene Methode
- cmd
- ausloesendes Verb
- flag
- Flag fuer unscharfe Interpretation
+ 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:
- Generell: Das Verhalten dieser efun wird durch AddCmd aus
- /std/thing/commands.c komfortabler widergespiegelt.
- Darauf sollte man zurueckgreifen.
+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.
- Legt fuer "cmd" (ein Kommandoverb) eine im entsprechenden Objekt
- zu rufende Methode fest.
+ 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?")
- Diese Methode bekommt die Argumente als String uebergeben und
- muss 0 (fuer einen Fehler) oder 1 (fuer Erfolg) zurueckgeben.
+ 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.
- Der Parser durchsucht bei einer Spielereingabe die Liste der
- eingetragenen Kommandos nach passenden Kommandos und ruft die
- zugehoerigen Methoden in den Objekten bis eine der Methoden
- 1 zurueckgibt oder die Liste durchlaufen wurde. In dem Fall
- kommt die Fehlermeldung (notify_fail()) zum Einsatz.
+ 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.
- Mit Werten != 0 fuer "flag" legt man eine unscharfe Auswertung
- fest, im Beispiel: Die Methode "action_fun" bei einem
- add_action("action_fun", "hops", 1);
- wird sowohl beim Kommando "hops" als auch bei Kommandos wie
- "hopse", "hopseblub", ... gerufen werden.
- Dieses Flag sollte vorsichtig verwendet werden.
+ 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.
- Es gibt drei moegliche Verhaltensweise, die per "flag" eingeschaltet
- werden koennen:
- 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.
+ Die Kommandos lassen sich auch manuell entfernen. Die Efun dazu lautet
+ remove_actions().
- 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 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_IMM_ARGS (3) ist, werden alle Zeichen nach dem Verb
- als Argument uebergeben, nicht aber von query_verb() beruecksichtigt.
+ 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.
-BEMERKUNGEN:
- (1) add_action() sollte immer innerhalb von init() benutzt werden
- (2) das definierende Objekt muss im inventory des Spielers oder
- environment() des kommandogebenden Lebewesens sein
- (3) im init() spaeter eingetragene Kommandos oder spaeter hinzu-
- kommende Objekte werden bei der Kommandoauswertung VOR den
- alten beruecksichtigt
- (Daher bewegt sich das Xtool der Magier regelmaessing neu in
- das Inventory, um immer "erstes" Objekt zu sein.)
+ Wenn -<flag> eine negative Zahl ist, muss das vom Spieler eingegebene
+ Kommando nur mit den ersten <flag> Zeichen von cmd uebereinstimmen.
-BEISPIELE:
- // ein Kommando in einem Schirm
- void init() {
- ::init();
- add_action("action_oeffne", "oeffne");
- }
+ 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/).
- int action_oeffne(string str) {
- if(stringp(str) && id(str)) // Argument da und bin ich gemeint?
- write("Du oeffnest den Schirm.\n");
- say(break_string(this_player()->Name(WER)+" oeffnet einen Schirm.",78));
- return 1;
- }
- notify_fail("Was willst Du oeffnen?\n");
- return 0;
- }
+BEISPIELE
+ add_action("geh_rein", "betrete");
- // frueher beliebt um Spieler lahmzulegen, da es _alle_ Kommandos
- // triggert -> siehe heute jedoch dafuer eher P_DISABLE_COMMANDS
- // Achtung: siehe Implikation von (3)
- add_action("action_nothing", "",1 );
- ...
- int action_nothing(string str) {
- write("Dir sind die Haende gebunden.\n");
- return 1;
- }
+ Wenn der Spieler "betrete" eintippt, wird die Funktion geh_rein()
+ aufgerufen.
- Beispiele fuer die Verwendung des Argumentes "flag":
- add_action("disfunc", "disconnect", AA_NOSPACE);
+ 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.
@@ -99,14 +74,15 @@
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);
+ 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 |
|-------------------|--------------|----------------------------|
@@ -132,18 +108,10 @@
| "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:
- remove_action(E), init(E), enable_commands(E)
- Fehlermeldung: notify_fail(E), _notify_fail(E)
- Argumentstring: query_verb(E), _unparsed_args(L)
- obsolet: add_verb(E), add_xverb(E)
- alternativ: AddAction(L), AddCmd(L)
- P_DISABLE_COMMANDS
-
-24. Maerz 2004 Gloinson@MG
+SIEHE AUCH
+ query_verb(E), query_command(E), add_verb(E), add_xverb(E), init(A)