cat posts/atlantis-pbem-neu-geschrieben-10-die-befehle.md
Atlantis PbeM neu geschrieben (Teil 10): Die Befehle – ein Parser mit 61 Fällen und zwei Lesarten
Jeder Spielerbefehl von MOVE bis CAST läuft durch 2.808 Zeilen gewachsenen C++-Code, der dieselbe Zeile auf zwei Arten liest. Teil 10 portiert den Parser lesbarer, vergleicht Prüfer und Zug mit der Referenz – und stößt dabei auf einen echten Nullzeiger-Absturz.
Nach Teil 9 kann der Python-Port einen Spielstand laden und speichern. Was er noch nicht kann: verstehen, was die Spieler wollen.
In Atlantis PbeM schickt jede Fraktion pro Zug eine Textdatei mit Befehlen. Ein Ausschnitt aus einem echten Zug des Referenz-Snapshots, ohne Kommentarzeilen, die Kopfzeile der Vorlage und die zweite gebildete Einheit:
# reference/snapshot-tests/turns/turn_3/orders.3
#atlantis 3
unit 152
@work
unit 140
name unit "King"
form 1
name unit "Ranchers"
claim 790
buy 10 PLAI
study RANC
turn
@produce LIVE
endturn
end
claim 100
study forc
#end
#atlantis eröffnet die Befehle einer Fraktion, unit wählt eine Einheit aus. Danach
folgt normalerweise ein Befehl pro Zeile.
form und end beschreiben eine neu gebildete Einheit innerhalb der Befehle ihrer
Muttereinheit. turn und endturn merken Befehle für einen späteren Zug vor. Ein @
kennzeichnet einen wiederholten Befehl. claim holt Silber aus der Fraktionskasse,
study lernt eine Fertigkeit. Die Einrückung ist nur für Menschen da.
Schritt 9 der Roadmap portiert diesen Parser. Das Done-Kriterium:
Alle Befehlsdateien der Referenz werden mit denselben angenommenen Befehlen und denselben Fehlern gelesen.
Die interessante Frage ist dabei nicht, wie man heute einen Parser schreiben würde.
Sondern: Wie weit darf man 25 Jahre gewachsenen Parsercode aufräumen, wenn sich sein Verhalten nicht ändern soll?
Ein Parser mit zwei Lesarten
parseorders.cpp hat 2.808 Zeilen.
Der grobe Aufbau ist überraschend einfach. Game::ParseOrders läuft über die Zeilen
einer Befehlsdatei und behandelt die Strukturwörter selbst:
#atlantis, #end, unit, form, end, turn und endturn.
Alles andere geht an Game::ProcessOrder.
Dort wartet ein zweiter switch:
// reference/parseorders.cpp
void Game::ProcessOrder(int order, Unit *unit, parser::string_parser& parser, orders_check *checker, bool repeating)
{
switch(order) {
case O_ADDRESS:
ProcessAddressOrder(unit, parser, checker);
break;
case O_ADVANCE:
ProcessAdvanceOrder(unit, parser, checker);
break;
// ... 59 weitere Fälle
61 Fälle, jeweils mit einer Process*Order-Funktion.
Fast jede davon bekommt dieselben drei Dinge: die aktuelle Einheit, den Parser für die
Zeile und einen checker.
Und genau dieser checker macht den Code interessanter, als der Aufbau vermuten lässt.
Atlantis PbeM besitzt einen Befehlsprüfer. Spieler können ihre Datei vor dem Stichtag an
das Kommando check schicken und bekommen sie zurück: die gelesenen Zeilen, dazwischen
Fehlermeldungen und am Ende die Anzahl der Fehler.
Dafür wird derselbe Parser ein zweites Mal benutzt.
Im echten Zug schreibt er Befehle auf Einheiten und Fraktionen. Beim Check läuft er mit
einem checker und einer Dummy-Einheit.
Zum Beispiel bei BEHIND:
// reference/parseorders.cpp
void Game::ProcessBehindOrder(Unit *u, parser::string_parser& parser, orders_check *checker)
{
/* This is an instant order */
auto val = parser.get_token().get_bool();
if (!val) {
parse_error(checker, u, 0, "BEHIND: Invalid value.");
return;
}
if (checker) return;
u->SetFlag(FLAG_BEHIND, val.value());
}
Bis
if (checker) return;
wird geprüft, ob der Befehl syntaktisch gültig ist.
Danach folgt die Wirkung im Spiel.
parse_error schreibt je nach Modus entweder in die Prüfdatei oder in den Fehlerbericht
der Einheit beziehungsweise Fraktion.
Dadurch liest derselbe Code dieselbe Befehlszeile auf zwei Arten.
Und diese beiden Lesarten sind nicht immer identisch.
Warum der Parser nicht in „prüfen“ und „ausführen“ zerlegt wurde
Aus heutiger Sicht liegt ein Refactoring nahe: Erst einen sauberen Parser bauen, der einen validierten Befehl erzeugt, danach eine zweite Schicht, die ihn ausführt.
Das wäre wahrscheinlich schöner.
Für diesen Port wäre es riskant.
Denn die Reihenfolge der Prüfungen gehört zum beobachtbaren Verhalten. Hat eine Zeile zwei Fehler, entscheidet der bestehende Kontrollfluss, welcher davon zuerst gemeldet wird. Manche Prüfungen laufen nur im Check-Modus, andere erst im echten Spiel. Teilweise verbraucht der Prüfer sogar andere Tokens als der Zug.
Diese Unterschiede landen direkt in einer Datei, die Spieler seit Jahren sehen.
Deshalb bleibt die grundsätzliche Struktur erhalten.
Lesbarer wird der Python-Code an weniger gefährlichen Stellen: Die switch-Fälle werden
zu match, die Funktionen heißen einheitlich process_<befehl>_order, Gruppen stehen
beieinander und Docstrings nennen die jeweilige C++-Funktion.
Auch Sentinel-Werte bekommen Namen:
# src/atlantis_ng/core/game/order_handlers.py
# GIVE and TAKE amounts that are not a number: the whole unit, all of the item.
GIVE_UNIT = -1
GIVE_ALL = -2
Ein C++-Zeiger, der entweder nullptr oder eine UnitId enthalten kann, wird in Python
zu UnitId | None.
So verschwinden Teile der mechanischen C++-Komplexität, ohne die Reihenfolge der eigentlichen Parserlogik neu zu erfinden.
order_handlers.py und parse_orders.py kommen zusammen auf 2.329 Zeilen statt der
2.808 Zeilen von parseorders.cpp.
Keiner der 61 Fälle fehlt.
Zusammenlegen nur mit Beweis
Ein paar Funktionen konnten trotzdem wirklich zusammengelegt werden.
ProcessBehindOrder, ProcessNoaidOrder, ProcessHoldOrder,
ProcessAutoTaxOrder und ProcessShareOrder folgen demselben Muster. Sie unterscheiden
sich nur im Wort der Fehlermeldung und im gesetzten Flag.
Im Port gibt es dafür eine Funktion:
# src/atlantis_ng/core/game/order_handlers.py
def process_flag_order(
unit: Unit, parser: StringParser, checker: OrdersCheck | None, word: str, flag: UnitFlag
) -> None:
"""The five flag orders: ``ProcessBehindOrder``, ``NoaidOrder``, ``HoldOrder``, ``AutoTaxOrder``, ``ShareOrder``.
One function for the five flag orders that differ only in the word and the flag; NOCROSS
comes here too, after its own check in :func:`process_nocross_order`.
"""
value = parser.get_token().get_bool()
if value is None:
parse_error(checker, unit, None, f"{word}: Invalid value.")
return
if checker is not None:
return
unit.set_flag(flag, int(value))
NOCROSS benutzt sie nach seiner zusätzlichen Prüfung ebenfalls.
Andere Zusammenlegungen entstanden für MOVE und ADVANCE, WEAPON und ARMOR sowie
für drei sehr ähnliche Parser der Trugbild-Beschwörungen.
Die Regel dafür war bewusst eng:
Zusammengelegt wird nur Code, dessen Unterschiede sich vollständig als Parameter ausdrücken lassen.
Ob das wirklich der Fall ist, wurde nicht nach Gefühl entschieden, sondern mit einem
diff der C++-Funktionsrümpfe geprüft.
Bei den Trugbildern gehörte beispielsweise auch eine abweichende Meldung zu diesen Parametern.
Eine weitere Frage musste ebenfalls geklärt werden: Könnte ein anderes Regelwerk einen dieser Parser austauschen und damit die Zusammenlegung später im Weg stehen?
Nein. Die Regelwerke bringen eigene Dateien wie extra.cpp, world.cpp, rules.cpp
und monsters.cpp mit. parseorders.cpp gehört zur gemeinsamen Engine.
Der Parser ist also für alle Regelwerke derselbe.
Das Orakel muss beide Seiten sehen
Bei 61 Befehlen reicht ein Test pro Funktion kaum aus.
Die Modellsonde aus Teil 7 bekam deshalb einen weiteren Modus:
model_probe orders scenario N
Als Ausgangspunkt dient der Zustand von Zug 13 des Referenz-Snapshots: eine Spielerfraktion mit sechs Einheiten in drei Regionen, darunter ein Magier.
Die Sonde führt zunächst PreProcessTurn und ReadPlayers aus – also genau den Anfang
von Game::RunGame.
Anschließend liest sie dieselbe Befehlsdatei zweimal.
Einmal mit Checker als Fraktion 0, wie das Kommando check.
Und einmal als orders.3 der Spielerfraktion durch Game::ReadOrders, so wie es im
echten Zug passiert.
Aufgezeichnet werden die Prüfdatei, Fehler und Ereignisse der Spielerfraktionen und alle
Felder einer Einheit, in denen ein Befehl landen kann: monthorders, giveorders,
castorders, turnorders und die übrigen Order-Slots.
Die Szenarien selbst sind handgeschriebene Befehlsdateien im C++-Probe-Code:
// tools/reference/model_probe.cpp
{"flags", "",
"#atlantis 3\nunit 140\nbehind 1\nnoaid on\nhold true\nautotax yes\nshare 1\nnocross 1\nbehind x\nnoaid\n"
"hold 2\nautotax\nshare no\nnocross off\nspoils walk\nspoils bogus\nspoils\nspoils none\nspoils all\nspoils ride\n"
// … weitere Zeilen bis #end
Jedes Szenario zielt auf eine Gruppe von Befehlen: gültige Werte, ungültige Werte, fehlende Argumente und Grenzfälle.
Über players_append kann die Sonde zusätzlich Zeilen an players.in hängen. So bekommt
eine Einheit vor dem Parsen beispielsweise Waffen, wenn ein Szenario weapon swor lbow
prüfen soll.
Die erste Runde bestand aus 21 Szenarien.
Der Python-Port reproduzierte alle 21 beim ersten Vergleichslauf, einschließlich der Prüfdateien.
Der einzige rote Test in diesem Lauf war eine falsche Erwartung im Python-Test:
faction war 2 trade 2 verbraucht vier Fraktionspunkte. standard erlaubt fünf.
Dinge, die erst im Dump auffielen
ParseOrders war vorher gelesen worden.
Trotzdem wurden einige Details erst sichtbar, als die Sonde den Zustand danach aufzeichnete.
Ein fehlgeschlagenes form wählt beispielsweise nicht einfach weiterhin die bisherige
Einheit aus.
form ohne Alias, form 0 oder form x lässt überhaupt keine Einheit ausgewählt.
ProcessFormOrder liefert nullptr, und der Aufrufer übernimmt genau diesen Wert als
aktuelle Einheit.
Jeder folgende Befehl meldet deshalb:
Order given without a unit selected.
bis wieder eine gültige unit-Zeile kommt.
Auch #atlantis ohne Passwort verhält sich überraschend. Der Prüfer erzeugt jedes Mal
zwei Meldungen:
Warning: No password on #atlantis line.
If this is your first turn, ignore this error.
Damit endet auch eine ansonsten perfekte Datei ohne Passwort mit Fehlern.
Und:
declare -1 ally
setzt tatsächlich die Standardhaltung der Fraktion. get_number liefert -1, und genau
dieser Wert bedeutet intern „Default“.
Nichts davon ist besonders kompliziert.
Aber es sind genau die Kleinigkeiten, die bei einem „sauberen“ Neuparser leicht verschwinden.
Der Prüfer rückt rückwärts ein
Noch sichtbarer ist eine Eigenheit der Prüfdatei.
Ein verschachtelter Block kann dort so aussehen:
unit 140
turn
behind 1
form 5
work
end
endturn
Man würde erwarten, dass turn und form die Einrückung erhöhen und end und
endturn sie wieder verringern.
Die Referenz macht es genau andersherum:
// reference/parseorders.cpp
if (checker) {
if (code == O_ENDTURN || code == O_ENDFORM)
checker->check_file << indent::incr;
checker->check_file << prefix << order.original() << "\n";
if (code == O_TURN || code == O_FORM)
checker->check_file << indent::decr;
}
Vor einem schließenden Wort läuft incr.
Nach einem öffnenden Wort läuft decr.
Zusätzlich entfernt indent::clear bei unit und #end den Einrückungspuffer des
Streams vollständig. Ein decr ohne installierten Puffer hat nichts mehr, das es
verringern könnte.
Ohne Puffer geht Text direkt in den Stream und damit auch an den Zeilenumbrüchen des
IndentWriter vorbei.
Der Python-Port bildet deshalb selbst diesen kleinen Stream-Zustand nach:
# src/atlantis_ng/core/game/order_handlers.py
class CheckOutput:
"""The checker's output stream: raw, or through the indenting buffer once a manipulator installs it.
...
"""
...
def incr(self) -> None:
"""``os << indent::incr``: two more columns; installs a buffer indented by two."""
if self._buffer is None:
self._buffer = IndentWriter(indent=2)
else:
self._buffer.incr()
def decr(self) -> None:
"""``os << indent::decr``: two columns less; nothing without a buffer."""
if self._buffer is not None:
self._buffer.decr()
Die seltsame Einrückung ist damit keine zufällige Testausgabe mehr. Ein Fixture hält sie fest, und der Kommentar daneben erklärt, warum sie so aussieht.
Ein echter Absturz in der Referenz
Eine Stelle fiel schon beim Lesen auf.
ProcessTeachOrder sammelt die Schüler eines TEACH-Befehls.
Sind keine angegeben, folgt dieser Fehlerpfad:
// reference/parseorders.cpp
if (!students) {
parse_error(checker, u, 0, "TEACH: No students given.");
// If we weren't adding to an existing order, delete the new order
if (order && u->monthorders->type != O_TEACH) delete order;
return;
}
Das Problem ist:
u->monthorders->type
Nach einer frischen unit-Zeile hat ClearOrders die Monatsbefehle entfernt.
u->monthorders ist also nullptr.
teach ohne Schüler als erster Monatsbefehl dereferenziert diesen Nullzeiger.
Das sieht im Code nach einem Absturz aus.
Aber bei so etwas reicht Lesen nicht.
Also lief die echte Referenz-Binärdatei im Docker-Image mit dem Spielstand von Zug 13 und dieser Datei:
#atlantis 3
unit 140
teach
#end
Die Ausgabe endete bei:
Reading the Orders File...
Exit-Code 139, unter Linux der typische Rückgabecode nach SIGSEGV.
Der Nullzeiger war damit keine Vermutung mehr.
Dem Code nach besitzt auch der Checker denselben Fehler, weil seine Dummy-Einheit an dieser Stelle ebenfalls keinen Monatsbefehl hat. Das wurde nicht noch einmal absichtlich zum Absturz gebracht; der bestätigte Turn-Pfad reicht für die Entscheidung.
Was portiert man von einem Segmentation Fault?
Nicht den Segmentation Fault.
Der Python-Port meldet:
TEACH: No students given.
und beendet die Verarbeitung dieses Befehls.
Das ist dieselbe Meldung, die die Referenz bereits ausgibt, bevor sie in der problematischen Konstellation abstürzt. Hat die Einheit schon einen anderen Monatsbefehl, erreicht die Referenz diesen Pfad auch ohne Crash.
Die Abweichung steht in der Portierungskarte, analog zu SkillStarvation aus einem
früheren Teil.
Eine eigene Architekturentscheidung war dafür nicht nötig. Die Referenz liefert hier kein sinnvoll fortsetzbares Verhalten, das erhalten werden könnte.
Für die Sonde entsteht daraus allerdings eine praktische Einschränkung: Ein Szenario
darf teach ohne Schüler nicht als ersten Monatsbefehl einer Einheit an die C++-Referenz
schicken.
Wenn dieser Fehlerfall getestet werden soll, bekommt die Einheit vorher beispielsweise
ein study.
Die zweite Hälfte: Bewegung, Handel und Zauber
Der zweite Pull Request brachte die verbliebenen 23 Befehle aus parseorders.cpp:
Bewegung, Segeln, Bauen, Produktion, Studium, Lehre, Handel, Geben, Transport, Angriff,
Diebstahl und die übrigen großen Order-Typen.
Einer davon ist CAST.
Sein Fall steht zwar in ProcessOrder, aber ProcessCastOrder selbst und die einzelnen
Zauberparser liegen in spells.cpp. Elf Parser lesen die Argumente der jeweiligen
Zauber: manche nichts weiter, andere eine Region, eine Einheit oder eine Liste von Zielen.
Nur diese Parse-Hälfte von spells.cpp gehört in diesen Schritt.
Das eigentliche Wirken der Zauber kommt später mit der Zugabwicklung.
Im Port steckt der Parserteil deshalb in core/spells.py.
Elf zusätzliche Szenarien erhöhten die Zahl auf 32.
Und dabei zeigte sich ein Problem mit dem Orakel selbst.
Endzustände vergessen die vorherigen Befehle
Die Sonde schreibt nach dem Parsen den Zustand der Order-Slots einer Einheit.
Das bedeutet:
Zwanzig build-Zeilen auf derselben Einheit ergeben nicht zwanzig sichtbare
Endzustände.
Wenn jeder neue Befehl denselben Slot ersetzt, steht im Dump am Ende nur der letzte.
Die erste Fassung der neuen Szenarien hatte genau dieses Problem. Viele interessante Befehle kamen irgendwo in der Mitte vor, aber die Einheit endete auf einem uninteressanten späteren Zustand.
Der Dump bewies dadurch fast nichts über den eigentlichen Testfall.
Die Szenarien wurden deshalb umgebaut.
Statt eine Einheit mit möglichst vielen Befehlen zu füllen, verteilen sich die interessanten Endzustände auf sechs Einheiten. Der letzte Befehl jeder Einheit ist bewusst derjenige, dessen Felder im JSON erscheinen sollen.
cast-spells endet dadurch beispielsweise mit einem Regionszauber, einem Teleport,
Bird Lore, Unsichtbarkeit samt Zielliste und einer Beschwörung.
cast-gates hält mehrere Formen von Gate Lore und Portal Lore sichtbar.
Beide Fassungen der Szenarien liefen gegen den Python-Port direkt grün.
Die zusätzliche Arbeit steckte nicht in einer Reparatur des Ports, sondern darin, das Orakel aussagekräftig zu machen.
Ungültiger Gegenstand? Trotzdem gekauft
Einige Ergebnisse der zweiten Runde sind gute Beispiele dafür, warum man den Parser nicht „vernünftiger“ machen sollte.
Dieser Befehl:
buy 5 bogus
ist kein Fehler.
Der Prüfer verlangt an dieser Stelle nur, dass überhaupt ein Wort als Gegenstand vorhanden ist. Ob es einen Gegenstand mit dieser Abkürzung gibt, prüft er nicht.
Der Zug speichert dadurch eine Kauforder für Item -1.
Kommt danach
buy 3 bogus
wird sie sogar mit der ersten zusammengelegt.
Ergebnis: eine Bestellung über acht Stück von keinem gültigen Item.
Ähnlich speziell sind Klassenangaben bei GIVE.
give 156 all item
speichert als Item den Wert -230, also -NITEMS für standard.
give 156 all unfinished ship
landet bei -524288, dem negierten Kategorie-Bit für Schiffe.
Diese negativen Werte sind Teil des bestehenden internen Protokolls zwischen Parser und späterer Zuglogik.
Sie durch hübschere Python-Enums zu ersetzen wäre möglich.
Aber nur dann, wenn später wirklich jede Stelle, die diese Werte erwartet, mitumgebaut wird.
Für diesen Port bleiben sie zunächst erhalten.
Der Prüfer versteht BUILD HELP anders als der Zug
Noch interessanter ist:
build help 140
Der echte Zug kann diesen Befehl lesen.
Der Checker nicht.
Seine Ausgabe:
*** Error: BUILD: Unknown keyword '140'. ***
build help 140 complete
Die Ursache verteilt sich auf zwei Funktionen.
ProcessBuildHelp kehrt im Check-Modus zurück, bevor es die Einheitennummer aus dem
Parser verbraucht.
Zurück in ProcessBuildOrder steht deshalb 140 immer noch als nächstes Wort bereit.
Dort wird es als weiteres Keyword interpretiert.
Und 140 ist weder complete noch ein anderes bekanntes Keyword.
Jede Funktion für sich sieht beim Lesen plausibel aus. Erst zusammengenommen entsteht der Fehler.
Der Port reproduziert ihn.
Nicht weil er sinnvoll ist, sondern weil die Prüfdatei für diesen Schritt das Orakel ist.
Wenn dieser Bug später behoben werden soll, dann bewusst – und mit derselben Verhaltensänderung in Referenz und Port.
Nicht jeder Zauber ist mit standard erreichbar
Die 32 Szenarien decken viel ab, aber nicht alles.
Transmutation und einige untote Trugbilder sind in standard deaktiviert.
parse_skill filtert deaktivierte Fertigkeiten bereits heraus. Ein Befehl wie
cast trns mith
endet deshalb bei:
CAST: Invalid skill.
Der Parser der Transmutation wird mit diesem Regelwerk gar nicht erreicht.
Diese Funktionen sind trotzdem portiert, aber an dieser Stelle nur durch Lesen des C++-Codes abgesichert.
Das ist eine bekannte Testlücke und steht so in der Portierungskarte.
Ein grüner Test soll nicht so tun, als hätte er Code geprüft, den sein Regelwerk überhaupt nicht erreichen kann.
Jetzt kommen die echten Befehlsdateien
Handgeschriebene Szenarien testen die Fälle, die man vorher kennt.
Das Done-Kriterium verlangt mehr.
Im Referenz-Submodul liegen die Befehlsdateien von 14 Zügen, turn_0 bis turn_13.
Es sind die Langformat-Vorlagen, die die Referenz für den Spieler geschrieben und die
der Spieler anschließend ausgefüllt hat.
Die Sonde bekam dafür:
orders turn N
Der Ablauf ist derselbe wie bei den künstlichen Szenarien, diesmal aber jeweils mit dem
Spielstand, der Spielerdatei und orders.3 des echten Snapshot-Zugs.
Alle 14 laufen im Python-Port mit demselben Ergebnis durch.
Der Checker offenbart dabei eine weitere Kuriosität.
Jede Prüfdatei ab Zug 1 beginnt mit:
*** Error: Orders is not a valid order. ***
Orders Template (Long Format):
Die Langformat-Vorlage der Referenz enthält als erste Textzeile:
Orders Template (Long Format):
Und der eigene Checker der Referenz hält diese von der Referenz erzeugte Zeile für einen unbekannten Befehl.
Dazu kommen die zwei Warnungen wegen des fehlenden Passworts.
Die Snapshot-Dateien ab Zug 1 haben damit jeweils mindestens drei Checker-Fehler. Zug 10 besitzt
einen vierten, echten: Ein study überschreibt dort einen anderen Monatsbefehl.
Auch das ist kein Grund, den Python-Checker freundlicher zu machen.
Gleiches Input, gleiche Prüfdatei.
Wieder uninitialisierter Speicher
Zug 0 bringt noch einen anderen Fall ans Licht.
Er enthält noch keine eigentlichen Spielerbefehle, aber seine players.in legt
Fraktion 3 neu an.
Die Sonde zeichnete für diese frisch erzeugte Fraktion auf:
numshows = 170930995
numshows zählt SHOW-Befehle einer Fraktion.
Der Konstruktor der C++-Klasse initialisiert das Feld nicht. DefaultOrders setzt es
erst zu Beginn des nächsten Zuges auf 0.
Bis dahin enthält es irgendeinen Wert aus dem Speicher.
Das ist derselbe Typ Problem wie gm_alias aus Teil 9.
Die Zahl 170930995 ist kein Teil der Spielregeln und kein stabiler Referenzwert.
Der Python-Port initialisiert numshows deshalb mit 0.
Die Sonde zeichnet für eine Fraktion, die im aktuellen Zug neu angelegt wurde, an dieser Stelle bewusst keinen Vergleichswert auf. Der Test lässt genau dieses Feld aus und erklärt im Kommentar, warum.
Speichermüll wird nicht zur Spezifikation, nur weil er in JSON auftaucht.
Die offene Order:-Zeile aus Teil 9
Mit dem neuen Parser kann auch eine Lücke aus dem vorherigen Schritt geschlossen werden.
players.in darf eine Zeile enthalten, mit der der Spielleiter einer Einheit direkt
einen Befehl gibt:
Order: ...
In Teil 9 endete dieser Pfad noch mit NotImplementedError.
Jetzt läuft er durch denselben Order-Parser.
Ein zusätzliches Szenario hält dabei eine kleine Nebenwirkung fest: Kommt später in der
normalen Befehlsdatei eine unit-Zeile für dieselbe Einheit, ruft sie ClearOrders auf.
Der vom Spielleiter gesetzte Befehl wird dabei ebenfalls entfernt.
ClearOrders kennt seine Herkunft nicht.
Damit steigt die Zahl der handgeschriebenen Szenarien auf 33.
Der Checker kommt ins Harness
Die Sonde erzeugt Fixtures.
Das Vergleichs-Harness aus Teil 3 soll dagegen beide Engines direkt gegeneinander ausführen.
Dafür bekam es ein neues Kommando:
uv run tools/compare/cli.py check reference/snapshot-tests/turns/turn_*/orders.3
Jede Datei läuft einmal durch standard check im Docker-Container und einmal durch den
Python-Port.
Die beiden Prüfdateien werden Byte für Byte verglichen.
Bei einer Abweichung gibt das Harness einen Unified Diff aus.
Für die 14 Snapshot-Dateien lautet das Ergebnis durchgehend:
reference\snapshot-tests\turns\turn_0\orders.3: equal
reference\snapshot-tests\turns\turn_1\orders.3: equal
...
reference\snapshot-tests\turns\turn_9\orders.3: equal
Der komplette Lauf braucht ungefähr neun Sekunden.
Auf Python-Seite ist der eigentliche Checker nur eine Funktion über Text und einen Stream:
# src/atlantis_ng/core/game/turn.py
def do_orders_check(game: Game, orders: str, check_file: TextIO) -> None:
"""``Game::do_orders_check``: the ``check`` subcommand's work, a syntax check of one orders file.
The reference's ``DummyGame`` sets nothing up: ``game`` carries the tables, no world. The
check goes to ``check_file`` as the reference writes it.
"""
checker = OrdersCheck(game)
parse_orders(game, 0, orders, checker)
check_file.write(checker.check_file.getvalue())
DummyGame der Referenz ist tatsächlich fast nichts: eine leere Funktion mit dem
Kommentar, dass für den Syntaxcheck kein Spielzustand nötig ist.
Im Python-Port übernimmt ein normales Game mit Tabellen, aber ohne erzeugte Welt,
diese Rolle.
Das Done-Kriterium ist damit auf zwei Ebenen erfüllt.
Die Sonde prüft die 14 echten Befehlsdateien über ReadOrders und vergleicht danach die
Order-Slots der Einheiten.
Das Harness lässt dieselben Dateien durch check beider Engines laufen und verlangt
identische Prüfdateien.
Noch einmal die Werkzeugfalle
Auch dieser Schritt hatte einen Fehler, der nichts mit Parsern zu tun hatte.
Ein Python-Edit über ein Bash-Heredoc verwandelte erneut ein \n innerhalb des
einzubettenden Python-Texts in einen echten Zeilenumbruch.
Das Ergebnis war diesmal schlicht ein Syntaxfehler.
Die Falle war aus vorherigen Schritten bekannt.
Und genau das ist der interessante Teil: Bekannt bedeutet nicht automatisch vermieden.
Seit diesem Schritt gehen solche Edit-Skripte deshalb nur noch über das Schreibwerkzeug des Agenten und nicht mehr durch eine Shell-Schicht, die ihre eigenen Escape-Regeln mitbringt.
Eine konkrete Prozessregel ist zuverlässiger als die Erinnerung daran, beim nächsten Mal vorsichtiger zu sein.
Was der Schritt gebracht hat
Schritt 9 endet nach vier Pull Requests.
Neu im Port sind unter anderem:
core/game/order_handlers.py mit 1.788 Zeilen,
core/game/parse_orders.py mit 541,
core/spells.py mit 442 und
core/game/turn.py mit 97 Zeilen.
Dazu kommen die benötigten Ergänzungen in units.py und players.py.
Insgesamt sind unter src/ 2.935 Zeilen hinzugekommen.
Die Modellsonde wuchs um 544 auf 3.234 Zeilen C++. orders-probe.json enthält die
33 handgeschriebenen Szenarien und ist 398.496 Bytes groß. Die 14 Snapshot-Züge belegen
weitere 152.238 Bytes in orders-turns.json.
513 schnelle Tests laufen in ungefähr 24 Sekunden. 29 weitere laufen gegen die Referenz.
Die Portierungsabdeckung steigt von 35,6 auf 40,4 Prozent.
parseorders.cpp ist damit vollständig portiert. spells.cpp bleibt in progress:
Seine Parserhälfte ist da, das eigentliche Wirken der Zauber kommt erst mit der
Zugabwicklung.
Eine neue Entscheidungsakte war für diesen Schritt nicht nötig.
Die Unterschiede der Python-Schnittstelle stehen in der Portierungskarte: Text und
Streams statt fest verdrahteter Dateinamen, einige nachweislich identische Funktionen
zusammengelegt, numshows definiert mit 0 statt uninitialisiert und der TEACH-Crash
durch die Fehlermeldung ersetzt, die die Referenz unmittelbar vor dem Absturz bereits
erzeugt.
Der BUILD HELP-Bug des Checkers dagegen bleibt erhalten.
Er ist definiertes, beobachtbares Verhalten.
Stolperfallen
- Die Reihenfolge der Prüfungen gehört zur Spezifikation. Die vielen
if (checker) return;laden dazu ein, Validierung und Ausführung sauber zu trennen. Welche Meldung bei mehreren Fehlern erscheint, hängt aber genau an diesem Ablauf. - Zusammenlegen nur mit Beleg. Ähnliche Funktionen wurden erst nach einem
diffihrer C++-Rümpfe zusammengeführt. Eine zusätzliche Meldung wird zum Parameter und nicht stillschweigend vereinheitlicht. - Der Prüfer ist ein eigener Verhaltenspfad.
build help 140funktioniert im Zug und scheitert im Checker. Ein Orakel, das nur eine Seite aufzeichnet, übersieht solche Unterschiede. - Ein Dump des Endzustands zeigt nicht die ganze Geschichte. Wird derselbe Order-Slot mehrfach überschrieben, bleibt nur der letzte Zustand sichtbar. Testdaten müssen so gebaut sein, dass der interessante Befehl am Ende noch zu sehen ist.
- Ein vermuteter Crash ist noch kein bestätigter Crash. Erst der Lauf der
Referenz-Binärdatei mit Exit-Code 139 machte den Nullzeiger in
ProcessTeachOrderzu einem gemessenen Referenzproblem. - Das Regelwerk bestimmt, welche Parser erreichbar sind. Eine deaktivierte Fertigkeit
scheitert bereits in
parse_skill. Dahinterliegende Zauberparser können mitstandarddeshalb nicht dynamisch getestet werden. - Uninitialisierter Speicher ist keine Spezifikation.
gm_aliasin Teil 9 undnumshowshier liefern zufällige Werte, die ein Port gerade nicht konservieren sollte. - Werkzeugfallen brauchen Prozessregeln. Ein bekanntes Heredoc-Problem trat erneut auf. Seitdem geht dieser Typ Edit nicht mehr durch die Shell.
Der Stand nach Teil 10
Der Python-Port versteht jetzt die Befehlsdateien von Atlantis PbeM.
Alle 61 Fälle aus parseorders.cpp und die Parse-Hälfte von spells.cpp sind portiert.
Geprüft wird das mit 33 handgeschriebenen Szenarien und den 14 Befehlsdateien der Referenz-Snapshots. Dieselben Dateien laufen sowohl durch den echten Turn-Pfad als auch durch den Checker. Das Harness vergleicht dessen Prüfdateien zusätzlich direkt mit der C++-Engine.
Die bekannten Unterschiede sind klein und ausdrücklich dokumentiert: ein
Nullzeiger-Absturz wird zu der bereits vorher ausgegebenen Fehlermeldung,
uninitialisierter Speicher bekommt einen definierten Wert. Beobachtbares Parserverhalten
wie der BUILD HELP-Fehler bleibt dagegen bestehen.
Damit ist parseorders.cpp ported.
Was noch fehlt, ist nicht mehr das Verstehen der Befehle, sondern ihre Wirkung.
MOVE liegt jetzt als Bewegungsorder auf der Einheit. BUY als Kauforder. CAST als
Zauber mit seinen Parametern.
Noch bewegt sich dadurch niemand, niemand kauft etwas und kein Zauber wird gewirkt.
Vor der Zugabwicklung kommt allerdings noch ein anderer großer sichtbarer Teil der Engine.
Teil 11 nimmt sich die Berichte vor: report.3 und template.3, die Dateien, die ein
Spieler nach jedem Zug erhält.
Ausgabe ist bei einem Legacy-System oft die beste Spezifikation, die man bekommen kann.
Weiterlesen
- Atlantis PbeM neu geschrieben (Teil 9)
– die Spielerdatei, deren
Order:-Zeile hier fertig wird, und der erste Fall von uninitialisiertem Speicher. - Atlantis PbeM neu geschrieben (Teil 7) – die Modellsonde, die hier zum Orakel für den Parser wird.
- Atlantis PbeM neu geschrieben (Teil 3) – das Harness, das jetzt die Prüfdateien beider Engines vergleicht.
- Einen Parser von Hand schreiben (Recursive Descent) – wie ein Parser aussieht, den man frei entwerfen darf; der Kontrast zu einem, den man kompatibel nachbauen muss.
- Agent im Loop (Teil 4): Refactoring unter Testschutz – dasselbe Prinzip an einem kleineren Beispiel: erst das Netz, dann der Umbau.
Sources: parseorders.cpp,
spells.cpp,
game.cpp
und indenter.hpp
des Forks,
Python match,
signal(7).
Tastenkürzel
- j k
- nach unten / oben scrollen
- n p
- nächster / vorheriger Abschnitt
- g G
- Anfang / Ende des Artikels
- t
- Gliederung zeigen
- ?
- diese Hilfe zeigen
- Esc
- schließen
0 Kommentare
Noch keine Kommentare. Sei der/die Erste!
Anmelden um einen Kommentar zu hinterlassen.