NAME

Langertha::Holmgang::Excerpt - Excerpts from a suite's statute texts under quellen/, set into messages

VERSION

version 0.001

SYNOPSIS

# a part of a message in a case of format 2 (cases/<case>.yaml):
#   content:
#     - "The statute:\n\n"
#     - auszug: { datei: quellen/probe-act.txt, von: "§ 3", bis: "§ 5" }
#     - "\n\nAnd the contract: ..."

my $excerpt = Langertha::Holmgang::Excerpt->new;

my $text = $excerpt->text( { datei => 'quellen/probe-act.txt', von => '§ 3', bis => '§ 5' },
  'cases/c1.yaml: messages[0].content[1].auszug', $suite_dir );

my $parts = $excerpt->expand( $content, 'cases/c1.yaml: messages[0].content', $suite_dir );

my $src = $excerpt->source( $suite_dir, 'quellen/probe-act.txt', $field );
# { head => { Titel => …, Stand => … }, body => …, norms => [ { label, title, start, end }, … ], path, sha256 }

DESCRIPTION

Long statute texts live as plain-text fixtures under quellen/ of a suite, not in the case. A case names only the range: a message part { auszug => { datei, von, bis } } (von, bis: the label of the first and the last provision, such as § 305 or Artikel 28). The loader sets the text in before the shape checks and lint ("case" in Langertha::Holmgang::Structure); its SHA-256 goes into the suite's digest as a generated text does (Langertha::Holmgang::Loader). Nothing is read at run time. Ported from cai-platform CAI::Platform::Eval::Auszug (origin/main); the text set in is the same, byte for byte.

The fixture (UTF-8): head lines Key: value (Titel, Stand, Quelle, Lizenz …), a line ---, then blocks separated by an empty line. A block whose first line starts with § N or Artikel N is a provision; any other block is a heading (book, part, title, chapter) and belongs to the provision after it. A provision holds no empty line.

The text set in starts with the fixture's Titel (else the file name), the range and the Stand (when given), then the blocks from the first to the last provision named -- with the headings in front of the first.

Confinement as for images (k27): datei is quellen/<name>.txt (lower-case letters, digits, dashes), and its real path, links resolved, lies inside the suite directory's real path; it must be a plain file.

source

my $src = $excerpt->source( $suite_dir, 'quellen/probe-act.txt', $field );

Checks and reads one fixture of a suite and returns head (the head lines as a hash), body (the text after ---), norms (per provision its label, title -- the first line --, start: where its block begins, headings in front of it included, and end: where it ends, as positions in body), path (the real path) and sha256 (of the bytes). A fixture that does not hold is refused with $field. The parse is kept per SHA-256 of the bytes, so a changed file is read anew.

text

my $t = $excerpt->text( { datei => 'quellen/x.txt', von => '§ 1', bis => '§ 9' }, $field, $suite_dir );

The excerpt as text (above). Refuses with $field (…auszug) and below: an unknown key, datei (path, missing, outside, not a plain file, a fixture that does not parse), von/bis (no label, not in the file), bis before von. The lines Auszug: … bis … and Stand: … are written as cai-platform writes them, so the model sees the same text.

expand

my $content = $excerpt->expand( $content, 'cases/c1.yaml: messages[0].content', $suite_dir );

A message content with every part { auszug => { … } } replaced by its text; a single such hash becomes a list of one part. Other parts (text, generate) stay as they are -- "resolve" in Langertha::Holmgang::Haystack joins them afterwards. Returns a new list; the content passed in is not changed.

files

my @files = $excerpt->files($content);   # ( 'quellen/probe-act.txt', … )

The datei of each excerpt in a message content, unchecked, in order -- what the YAML export of a DSL suite copies.

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.