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/continue as nodes. { … } groups and subshells ( … ) (own variables and own directory), also with a pipe or redirection after them. Functions (name() { … }, function name { … }) as node func; for (( )) is not modelled: the node gap.

  • "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 that shell_words reads 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.