Wrapper fuer ReceiveMsg() ueberarbeitet
1) Rueckgabewerte in Containern entfallen
Diese muessten ein (tief) geschachteltes Mapping sein, was vermutlich
niemand mehr auswertet.
2) Alternativen nur versuchen, solange der Fehler von ReceiveMsg()
MSG_SENSE_BLOCK ist - alle anderen Fehler sind sehr wahrscheinlich
"permanent" fuer die Dauer des Aufrufs.
3) Rueckgabewert in Livings geaendert
Der Rueckgabe ist jetzt der Rueckgabewert von ReceiveMsg() fuer die
zuletzt versuchte Meldung. Dies ermoeglicht die Feststellung, dass eine
Meldung zugestellt wurde (wenn auch nicht welche), was das ist, was
die meisten Aufrufer interessieren duerfte. Gleichzeitig ist der Wert
jetzt einfacher auszuwerten.
4) Manpages umstrukturiert und -formuliert
5) ReceiveSay() nur noch Spezialfall von ReceiveMultiSense()
Change-Id: Id9dbe227236f07b577be2626c99a13ff89fd7997
diff --git a/doc/sphinx/lfun/ReceiveSay.rst b/doc/sphinx/lfun/ReceiveSay.rst
index 33ceee1..386aa7e 100644
--- a/doc/sphinx/lfun/ReceiveSay.rst
+++ b/doc/sphinx/lfun/ReceiveSay.rst
@@ -4,9 +4,9 @@
FUNKTION
--------
- public int* ReceiveSay(string msg, string prefix = 0,
+ public void ReceiveSay(string msg, string prefix = previous_object().Name(WER, 1) + " sagt: ",
struct msg_s sense_blocked =
- ({(<msg_s>
+ ({(<wave_s>
msg: "@WER1 bewegt die Lippen, Du hoerst jedoch nichts.",
type: MT_LOOK)}))
@@ -15,56 +15,44 @@
/std/living/comm.c
/std/room/comm.c
- /sys/living/comm.h
-
+
ARGUMENTE
---------
string msg
- Die auszugebende Meldung. Sie wird vor der Ausgabe an
- :doc:`../sefun/replace_personal` uebergeben, als erstes Objekt wird das aufrufende
- Objekt uebergeben, als zweites this_player(), sofern vorhanden. msg wird
- automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden
- dabei beibehalten.
+ Die auszugebende Meldung.
string prefix
- prefix wird als prefix an :doc:`ReceiveMsg` weitergegeben. Eine
- Ersetzung mittels :doc:`replace_personal` findet nicht statt.
- Wird kein Wert uebergeben, wird
- previous_object().Name(WER, 1) + " sagt: " verwendet. Hierzu muss Name()
- am aufrufenden Objekt definiert sein und etwas sinnvolles zurueckgeben.
- struct msg_s sense_blocked
- Ersatzmeldungen fuer taube Spieler. enthaelt Structs vom Typ msg_s.
- Dieser ist in /std/living/comm_structs.c definiert und enthaelt die
- Eintraege string msg, int type, string prefix.
- Das Array wird von vorne nach hinten
- abgearbeitet, bis eine Nachricht zugestellt werden konnte oder das Ende
- erreicht ist. Auch hier findet fuer msg eine Ersetzung mittels
- :doc:`../sefun/replace_personal` statt, fuer prefix nicht.
+ prefix wird als prefix an :doc:`ReceiveMsg` weitergegeben. Wird kein Wert uebergeben, wird ``previous_object().Name(WER, 1) + " sagt: "`` verwendet.
+ struct wave_s \*alt
+ Ersatzmeldungen, falls das Lebewesen die Meldung aufgrund eines blockierten Sinns nicht wahrnehmen kann. Details siehe unten.
BESCHREIBUNG
------------
- Sendet msg per :doc:`ReceiveMsg` mit den ueblichen Argumenten von
- "sage" an den Empfaenger. D.h.: MT_LISTEN, MA_SAY, Name(WER, 1) + " sagt: ". Hierzu
- muss das aufrufende Objekt :doc:`name` definiert haben und dort
- etwas sinnvolles zurueckgeben. Falls ein anderer prefix gewaehlt wurde,
- wird dieser statt Name(WER, 1) " sagt: " verwendet.
+ Sendet msg per :doc:`ReceiveMsg` mit den ueblichen Argumenten von "sage" an den Empfaenger, d.h.: ``MT_LISTEN``, ``MA_SAY``, ``Name(WER, 1) + " sagt: "``.
+ Hierzu muss das aufrufende Objekt :doc:`Name` definiert haben und dort etwas sinnvolles zurueckgeben. Falls ein anderer Praefix gewaehlt wurde, wird dieser statt ``Name(WER, 1) " sagt: "`` verwendet.
+
+ <msg> wird vor der Ausgabe an :doc:`../sefun/replace_personal` uebergeben, als erstes Objekt wird das aufrufende Objekt uebergeben, als zweites this_player(), sofern vorhanden. msg wird automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden dabei beibehalten.
+
+ Falls der Empfaenger eine Nachricht aufgrund eines blockierten Sinns nicht empfangen kann (und **nur** dann), wird versucht, alternative Nachrichten aus dem Array <alt> zuzustellen. Dieses Array enthaelt structs vom Typ wave_s. Das Array wird von vorne nach hinten abgearbeitet, bis eine Nachricht erfolgreich zugestellt werden konnte, das Ende erreicht ist oder eine Nachricht *aus anderen Gruenden* als einem blockierten Sinn abgelehnt wurde. Der Grund fuer letzteres ist, dass andere Fehler von ReceiveMsg() (fast) immer auch bei allen (weiteren) Alternativen auftreten werden.
+ wave_s ist in /secure/simul_efun/comm.c definiert und enthaelt die Eintraege string msg, int type, string prefix. In <alt> ist der Default fuer wave_s.prefix 0!
+ Auch hier findet fuer wave_s.msg eine Ersetzung mittels :doc:`../sefun/replace_personal` statt, fuer wave_s.prefix nicht.
RUECKGABEWERT
-------------
- Ein Integer-Array mit folgenden Werten:
+in Lebewesen
+^^^^^^^^^^^^
+ Der Rueckgabe ist der Rueckgabewert von ReceiveMsg() fuer die zuletzt versuchte Meldung.
- 0
- Der Rueckgabewert von :doc:`../lfun/ReceiveMsg`.
- 1
- Information, welche Meldung zugestellt wurde. -1 steht fuer msg, ein wert
- >= 0 fuer die jeweilige Position in sense_blocked.
+ Wenn dies einen Erfolg (MSG_DELIVERED, MSG_BUFFERED) darstellt, wurde irgendeine Meldung erfolgreich zugestellt.
+ Falls es MSG_SENSE_BLOCK ist, sind alle versuchten Sinne blockiert und keine Nachricht wurde zugestellt.
+ Ist es ein anderer Fehler ist, wurde keine Nachricht zugestellt (und ggf. nicht alle aus <alt> versucht).
- Raeume definieren standardmaessig ebenfalls ein ReceiveSay(), welches in
- jedem Objekt im Raum ReceiveSay() mit den uebergebenen Argumenten aufruft.
- In diesem Fall ist der Rueckgabe der kleinste von allen gerufenen
- ReceiveSay() zurueckgelieferte Wert.
+in Containern/Raeumen
+^^^^^^^^^^^^^^^^^^^^^
+
+ Die Funktion hat keinen Rueckgabewert. Der Grund hierfuer ist, dass dieser ein ggf. tief verschachteltes Mapping waere, was keiner mehr prueft.
BEISPIEL
--------
@@ -77,16 +65,16 @@
"Das hast Du prima gemacht, @WER2!",
Name(WER, 1) + " lobt Dich: ",
({
- (<message_>
+ (<wave_s>
msg: "@WER1 nickt Dir laechelnd zu.",
type: MT_LOOK),
- (<msg_s>
+ (<wave_s>
msg: "Jemand klopft Dir lobend auf die Schulter.",
type: MT_FEEL)}));
SIEHE AUCH
----------
- :doc:`ReceiveMsg`, :doc:`../sefun/replace_personal`, :doc:`name`
+ :doc:`ReceiveMsg`, :doc:`../sefun/replace_personal`, :doc:`Name`
-Letzte Aenderung: 07.10.2021, Bugfix
+Letzte Aenderung: 21.09.2022, Zesstra