notify_fail()
=============

FUNKTION
--------
::

     #include <notify_fail.h>

     varargs void notify_fail(string str, int prio)
     varargs void notify_fail(closure cl, int prio)

ARGUMENTE
---------
::

     str   Meldung die an den Spieler anstatt des 'Wie bitte' ausgegeben
           werden soll
     cl    Closure, die bei Fehlschlag ausgefuehrt werden soll
     prio  Prioritaet dieses Objekts bei diesem Setzen der Meldung

BESCHREIBUNG
------------
::

     Merkt sich den angegebenen str und gibt ihn im Falle einer inkorrekten
     Eingabe des Spielers anstatt eines 'Wie bitte' aus.

     Gedacht ist notify_fail, um dem Spieler eine bessere Hilfestellung
     bei Kommandos / Eingaben zu geben, um ihn u.U. auf die richtige
     Syntax hinzuweisen.

     Wird notify_fail mehrfach (durch verschiedene Objekte o.ae.) auf-
     gerufen, wird der letzte erfolgreiche Aufruf gewertet. Eine Meldung wird
     dann tatsaechlich gesetzt, wenn die Prioritaet dieses Objekts gleich
     gross oder groesser ist als die Prioritaet des Objekts, was das bisher
     gueltige notify_fail() gesetzt hat. Folgende Prioritaeten sind
     vordefiniert und werden automatisch ermittelt:
     NF_NL_OWN    100         // eigenes Objekt (soul) ueberschreibt kaum was
     NF_NL_THING  100000
     NF_NL_ROOM   1000000     // Raeume ueberschreiben sonstigen Krams
     NF_NL_LIVING 10000000    // Lebewesen ueberschreiben auch Raeume
     2 weitere vordefinierte koennen von Magier angegeben werden:
     NF_NL_NONE   -1          // wird von allem ueberschrieben
     NF_NL_MAX    __INT_MAX__ // hoechste Prioritaet, ueberschreibt alles

     Wird eine Closure als Argument gegeben, wird sie im Fehlerfall
     (also erst wenn ein Kommando endgueltig fehlgeschlagen hat)
     ausgefuehrt und hat die Fehlermeldung als Resultat
     zurueckzugeben. Die Closure erhaelt als Argument den
     originalen Befehlsgeber; in der Regel dies ist this_player(),
     was aber vom MODIFY_CMD hook geaendert werden kann.

     notify_fail() erkennt verschachtelte Kommandos (siehe Efun
     command()), und ein notify_fail() in einem Unterkommando
     hat keinen Einfluss auf das uebergeordnete Kommando.

BEMERKUNGEN
-----------
::

     - solange man sich nicht absolut sicher ist, dass ein bestimmtes Objekt
       mit dem Kommando gemeint ist (Identifikation ueber id()), sollte man
       - notify_fail(str); return 0;
       nutzen anstatt mit
       - write(str) return 1;
       die Kommandoauswertung abzubrechen (und anderen Objekten die Chance
       zu nehmen das Kommando zu erfuellen)
     - Kommandos werden uebrigens oft erst vom betretenen Raum, dann von den
       Objekten abgearbeitet (je nachdem wann diese dazukamen)
     - die Prioritaet wird momentan nicht gespeichert, sie ist nur beim Setzen
       relevant. Will spaeter ein anderes Objekt eine Meldung setzen, wird
       fuer das eigene Objekt die Standardprioritaet ermittelt, auch wenn man
       eine andere hier uebergeben hat
     - Die NF_NL_* sind in /sys/notify_fail.h defniert.

BEISPIELE
---------
::

     Ein Raum erwartet die korrekte Eingabe von 'iss suppe':

     int iss_cmd(string str){
       // zu Anfang der Funktion das notify_fail definieren
       notify_fail("Moechtest Du vielleicht von der Suppe essen?\n");

       // Spieler hat nur 'iss' ohne Parameter eingegeben oder einen anderen
       // Parameter angegeben ... Abbruch!
       // Falls kein weiteres Objekt das Kommando erfuellt oder das
       // notify_fail() mit einer eigenen Meldung ueberschreibt, wird obige
       // Meldung an den Spieler ausgegeben.

       if(!str || str!="suppe") return 0;
       // ab hier ist die Eingabe dann wirklich 'suppe' und die Funktion
       // kann beliebig fortgefuehrt werden
       ...
       return   1;

SIEHE AUCH
----------
::

     add_action(E), AddCmd(L), AddAction(L),
     query_verb(E), query_notify_fail(E)

8.Aug 2007 Gloinson