NAME

Langertha::Holmgang::Expectation - The expectations on a value, shared by rules, when conditions and check.expect

VERSION

version 0.001

SYNOPSIS

use Langertha::Holmgang::Expectation qw( condition element_match );

my ( $ok, $why ) = condition( $state, { path => 'gw-a.routes', any => { dst => '^default$' } } );
my ( $ok, $why ) = condition( $state, { path => [ 'h', 'files', '/etc/x' ], regex => '^listen' }, \%args );

DESCRIPTION

A format 2 expectation is a hash of matcher keys (exists, absent, equals, in, regex, contains, excludes, length, any, none, before) on one value; all that are named must hold. Rules of kind state, the when conditions of handlers and observations, the expect of a check rule and the field patterns of any/none/where all go through here. Keys that are not matchers (path, title, state …) are ignored, so a rule hash can be handed in as written.

tolerance (k49) qualifies equals: with equals: 42, tolerance: 0.5 the value must be a number no further than 0.5 from 42, bounds included — for values read off an image. It is no expectation of its own; the shape check (Langertha::Holmgang::Structure) refuses it without a numeric equals. The comparison allows for binary rounding (|41.8 - 42| <= 0.2 holds).

Paths are dotted text or a list of segments (for keys with dots); {name} in a segment is replaced by the argument name. Lists are addressed by index from 0.

Plain functions, imported on request. The simulators call "condition" and the World and the Grader call all of them; nothing here knows a simulator.

path

my @seg = path( 'gw-a.routes', \%args );
my @seg = path( [ 'gw-a', 'peers', '{peer}' ], \%args );

A path as a list of segments, {name} in each segment replaced by the argument. Dies on an empty path.

get

my ( $found, $value ) = get( $state, @segments );

The value at a path. A file that stands in the state as bare text has that text as its content, so [host, files, /path, content] fits both forms of a file entry.

flat

An argument as text for a pattern: lists joined with commas, booleans as true/false, other references as canonical JSON.

interp_text

interp_text( 'peer {key|lc}', \%args );

Replaces {name} and {name|filter} in a text by the flattened argument.

filter_value

filter_value( '10.0.0.1/32, 10.2.0.0/24', 'split' );   # [ '10.0.0.1/32', '10.2.0.0/24' ]

The argument filters of format 2: split (comma and white space into a list), int (the first integer), lc. Dies on an unknown filter, with the world's generic refusal and nothing of the filter, file or line: the text can reach the model as a tool result. Lint refuses such a case at load time (Langertha::Holmgang::Lint), so this only guards a case that bypassed it.

same_scalar

True when two plain values are the same: numbers numerically, text exactly, booleans against 1/0 and true/false.

near

near( $value, $want, $tolerance );

True when $value is a finite number (or numeric text) no further than $tolerance from $want, bounds included, allowing for binary rounding (a relative 1e-9). A boolean, a reference or other text is not near anything.

element_match

element_match( $element, $pattern, \%args );

Does a list element fit? $pattern is a regular expression (for a text element) or a hash field → pattern (text = regular expression, hash = expectations as in "check_value"). {name} in patterns is replaced literally (\Q…\E).

condition

my ( $ok, $why ) = condition( $state, { path => 'gw-a.routes', any => {…} }, \%args );

Checks the expectations of $spec on the value at $spec->{path}. Returns true or false and a short reason.

check_value

my ( $ok, $why ) = check_value( $found, $value, \%expectations, \%args );

The expectations on a value already looked up. A file entry with attributes ({ content, mode, … }, as after cp) counts with its content against equals, in and regex.

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.