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.