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 with simulator: run_command: the first entry whose match (a regular expression per argument; named captures become arguments) and when (expectations on the state) fit answers with its rendered output, pipe filters behind a | applied. error: true makes the call fail. An observation never changes the state. On a linux device 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 like ssh. A simulator that fails in Perl never hands its error text (with a host file path) to the model: a die answers Fehler: 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 as simulator error: … — for the report, never for the model.
3. Handlers of a tool without simulator: the first whose match and when fit applies its apply list (set, push, insert, delete, remove, move) to a copy of the state and renders its output (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.