NAME
Langertha::Holmgang::World - The simulated world of a case — state, tool dispatch, handlers, end-state diff
VERSION
version 0.001
SYNOPSIS
my $world = Langertha::Holmgang::World->new(
state => $case->initial_state,
tools => $suite->tools,
observe => $case->observe,
);
my ( $output, $args, $ok, $gap ) = $world->call( run_command => '{"host":"gw-a","command":"ip route"}' );
$world->state; # after all calls
my @diff = Langertha::Holmgang::World->diff( $case->initial_state, $world->state );
DESCRIPTION
A case describes a small world: a state (nested data: devices with their files and services, or plain entries for handler worlds) and the suite's tools. A call goes through, in this order:
- 1. Observations of the case (
observe), for a tool withsimulator: run_command: the first entry whosematch(a regular expression per argument; named captures become arguments) andwhen(expectations on the state) fit answers with its renderedoutput, pipe filters behind a|applied.error: truemakes the call fail. An observation never changes the state. On alinuxdevice a command chain (a && b; c) is answered link by link: an observation for its link, the simulator for the others, with&&,||and$?following the exit status. - 2. The simulator of the device type (
run_command,write_file, or the tool of an answer world), through Langertha::Holmgang::Simulators. An unknown host answers likessh. A simulator that fails in Perl never hands its error text (with a host file path) to the model: a die answersFehler: interner Fehler beim Ausführen des Aufrufs.and leaves the state unchanged; a Perl error line in its output that names a source file of the running process (a die the simulator caught) is replaced by that same text, the rest of the output and the state stay — a simulated line of the same shape with any other path is output and passes unchanged. Either way the call fails, and the original text goes into the gap of the simulation assimulator error: …— for the report, never for the model. - 3. Handlers of a tool without simulator: the first whose
matchandwhenfit applies itsapplylist (set,push,insert,delete,remove,move) to a copy of the state and renders itsoutput(Langertha::Holmgang::Template) after the change. A failed change leaves the state untouched.
A when of an observation or a handler that cannot be evaluated (an unknown filter in its path, which lint refuses at load time) does not hold: the entry does not fit, and the call never dies.
Tools, handlers and observations are read as format 2 writes them. In paths, values and where patterns {name} stands for the argument name; a value that is exactly {name} takes the argument as it is (list, number), {name|split} splits text at commas and white space, {name|int} makes an integer, {name|lc} lower case.
Everything is deterministic: the same calls give the same state and outputs. The texts the model gets for a refused call (Fehler: …) are German, as the suites expect them.
state
The current state. The constructor takes a deep copy, so the case stays untouched; do not change the returned hash (copy it with "clone").
tools
The suite's tools as format 2 writes them (name, description, parameters, and simulator or handlers).
observe
The case's observations (match, when, output, error).
simulators
The simulator registry (Langertha::Holmgang::Simulators); a fresh one by default.
clone
my $copy = Langertha::Holmgang::World->clone($data);
A deep copy through canonical JSON (a state must be storable as JSON).
offer
The tools as they are offered to the model: name, description, parameters — nothing else.
call
my ( $output, $args, $ok, $gap ) = $world->call( $name, $arguments );
Runs one tool call. $arguments is the JSON text the model sent, or a hash already. Returns the text for the tool message, the decoded arguments (empty hash when unreadable), whether the call succeeded and, for a simulator, the gap of the simulation it hit (undef without). An unknown tool, arguments that are no JSON object or do not fit the schema, and a call no handler takes answer with a text starting Fehler: and leave the state unchanged.
value
my $v = $world->value( $template, \%args );
Puts arguments into a value: a text that is exactly {name} (with optional filter) becomes the argument itself, else {name} is replaced inside the text; hashes and lists recursively.
diff
my @diff = Langertha::Holmgang::World->diff( $before, $after );
# ( { path => [ 'gw-a', 'routes' ], before => […], after => […] }, … )
What changed: hashes key by key, lists of the same length holding hashes or lists entry by entry (index in the path), other lists and values as a whole. before or after is missing when the path did not exist then. Keys starting with _ are a simulator's bookkeeping and never compared. Sorted by path.
path_text
Langertha::Holmgang::World->path_text( [ 'gw-a', 'peers', 'Qm4.=' ] ); # gw-a.peers["Qm4.="]
A path for display; segments with a dot, white space, quote or bracket (or empty ones) in brackets as JSON text.
covered
Langertha::Holmgang::World->covered( \@segments, \@allowed_paths );
True when an allowed path (a list of segments; * fits any one segment) is a prefix of the path or equal to it. A * inside a segment fits any characters but / (/etc/x.service.d/*.conf).
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.