NAME
Langertha::Holmgang::Shell - The bash grammar of the simulators — words, items, heredocs, blocks, expansion, test
VERSION
version 0.001
SYNOPSIS
use Langertha::Holmgang::Shell ();
my @items = Langertha::Holmgang::Shell::split_items($text);
my $nodes = Langertha::Holmgang::Shell::parse(\@items); # or the bash message as text
my $raw = Langertha::Holmgang::Shell::expand( $raw, $env, $cmdsub );
my ( $ok, $err ) = Langertha::Holmgang::Shell::test_expr( \@args, $fileinfo );
DESCRIPTION
The parts of a bash that the Linux simulator needs not per command but for a whole command line or script. Execution happens in the simulator (Langertha::Holmgang::Sim::Linux); this module only splits and computes. Also "shell_words" (the words of a command line) and "split_chain" (items at &&, ||, ; for the observations of the world).
"split_items": items at
;,;;,&&,||,&and line ends (not inside quotes,$( ),${ },[[ ]]), comments, line continuation, heredocs (<<EOF,<<-EOF,<<'EOF') and here-strings (<<< word)."parse":
if/elif/else/fi,for … in,while/until(also… | while read),case … esac,break/continueas nodes.{ … }groups and subshells( … )(own variables and own directory), also with a pipe or redirection after them. Functions (name() { … },function name { … }) as nodefunc;for (( ))is not modelled: the nodegap."expand": variables (
$v,${v},${#v},${v:-w},${v#p}/${v##p}/${v%p}/${v%%p},${v:o:l},${v/p/r},${v^^}/${v,,}),$?,$$,$#,$1…, arithmetic$(( )), command substitution$( )and` `(through a callback),$'…'. The result is again a command line: substituted values are quoted so thatshell_wordsreads them as words the way bash does (unquoted with word splitting, otherwise as one word)."test_expr":
test/[ ]/[[ ]]with file, string and number comparisons,!,-a/-o,&&/||, parentheses, patterns with==in[[ ]],=~.
split_items
my @items = split_items($text);
# ( { raw => 'cd /x', op => ';' }, { raw => 'cat > f', op => '&&', heredoc => "…\n", expand_doc => 1 }, … )
op is the separator before the item (; at the start), sep the one after it (;; separates the branches of case). An unclosed quote dies with the bash message.
top_pipe
my ( $left, $right ) = top_pipe($raw); # last pipe at the top level, else ()
parse
my $nodes = parse(\@items); # [ { type => 'cmd'|'if'|'for'|'while'|'case'|'gap', op => …, … } ]
On a syntax error returns the bash message (text instead of a list).
expand
my $raw = expand( $raw, $env, $cmdsub );
$env: { vars => {…}, rc => 0, args => [ … ], defaults => {…} }; $cmdsub: sub { my ($text) = @_; return $output }. Dies with "gap: …\n" for what is not modelled (e.g. ${!v}, i++).
glob_re
my $re = glob_re('www-*.tar.gz'); # regex without anchors; $greedy for ${v//p/r}
arith
my $n = arith( 'i + 1', $env, $cmdsub ); # integers like bash
test_expr
my ( $status, $err ) = test_expr( \@args, $fileinfo, $dbl ); # 0 true, 1 false, 2 error
$fileinfo: sub { my ($path) = @_; return undef | { kind => 'f'|'d'|'l', size => n, mode => 0644, mtime => epoch } }. $dbl ([[ ]]): pattern right of ==/!=, =~, &&/||, </> without a backslash.
shell_words
my @w = shell_words(q{nft add rule ip nat postrouting oifname "eth0" masquerade});
Splits a command line into words like a POSIX shell (single and double quotes, backslash). Operators (|, >, >>, &&, ||, ;) become words of their own, as a hash { op => '|' }. An unclosed quote is an error (die with the shell message).
split_chain
my @chain = split_chain('systemctl restart a && journalctl -u a | tail -n 3');
# ( [ ';', 'systemctl restart a' ], [ '&&', 'journalctl -u a | tail -n 3' ] )
Splits a command line roughly at &&, ||, ; and line ends outside quotes: per item the separator before it and the text. For the observations of the world, which check item by item; the simulator itself uses "split_items".
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.