Proc::ShellSubset::Large: the large shell subset (2026-11-01)

Status: parser written and tested (2026-11-01, as ShellSubsetLarge.pm of the old Project, 258 lines; now lib/Proc/ShellSubset/Large.pm). Its patch to Proc::ShellSubset (section 7) was applied by the posix_spawn session on 2026-11-01, which also made its executor run these trees (now lib/Proc/ShellSpawn.pm and lib/Proc/ShellSpawn/Large.pm; ../pspawn-extensions.md). Update of the evening: for NAME without in (section 3), applied by the posix_spawn session the same evening (section 7). Update of 2026-11-02: here-documents inside "$( … )", and command with no arguments. Decisions: the checklist page "Shell Large Subset" (item IDs A1, F3, … below) and your message of 2026-11-01: implement it as an addition to lib/Proc/ShellSubset.pm, which is asked first; the module is named lib/Proc/ShellSubset/Large.pm. Where the page offered alternatives and you had not chosen, I took the page's recommendation (A3: A, A4: A, F6 -x: A). Rule names such as V3, B3, E1 are those of doc/parsers/shell-subset-spec.md, which this document amends. Sections 1 to 5 are kept in line with the code, the later decisions named where they apply (rule E: large-subset-logical.md); sections 7 and 8 are history.

1. How it works

Proc::ShellSubset::Large::parse($string, %opt) returns a List or an error hash, exactly like Proc::ShellSubset::parse.

  1. It calls Proc::ShellSubset::parse with the options if while for case read assign param_ops on. If that accepts the string, its tree is the answer. So everything Proc::ShellSubset accepts keeps its tree and its meaning (for example pwd, spec B2: pwd -L, run inside Perl by default since post-0.10, IP1, as the program /bin/pwd -L with PROC_SHELLSPAWN_INPROC=none; so F12's "pwd as a builtin" is dropped).
  2. Only if Proc::ShellSubset rejects the string (other than for U1) does it parse the string again by the large grammar. That grammar is Proc::ShellSubset's own code, run with eight of its subs and two of its tables replaced for the time of the call (local). The replacements are in lib/Proc/ShellSubset/Large.pm. Before that, the here-document bodies are cut out of the string (positions in errors still refer to the original string).

Options: those of Proc::ShellSubset, except brace, which is ignored (brace expansion is bash-only; T1). The check callback and the NUL test see the whole original string.

2. Rules that change

Dropped:

Kept: everything else, in particular V4 for literal exit/return statuses, V7 (no exec -x, no exec of a builtin), V15 (cd forms; cd - now allowed), CDPATH not assignable (HOME may be set and unset since post-0.04; PPID and LINENO may be read, not assigned), and the rejection of every bash-only construct (A3, alternative A).

New, also in Proc::ShellSubset (section 7; bugs of Proc::ShellSubset found on the way):

3. What the large grammar accepts in addition

| Builtin | Accepted | Rejected | |---|---|---| | set (F6) | -e -u -f -C -a and +…, combined (-eu); -o/+o errexit nounset noglob noclobber allexport; operands, -- | no arguments, -x, -v, -n, other letters, -o alone, -o pipefail | | . (F7) | one argument | none or two or more | | eval (F7) | anything | | | trap (F8) | ACTION and one or more of EXIT HUP INT QUIT ABRT FPE PIPE ALRM TERM USR1 USR2 KILL STOP and 0, named in any case or by number (P6); ACTION - or ''; a literal ACTION must itself be accepted by the large grammar (with the caller's options) | fewer than two arguments, -p, a numeric first argument (a signal for sh), ERR DEBUG RETURN, a SIG prefix, other signals | | wait (F8) | no argument, process IDs | %1 | | umask (F12) | no argument, an octal mask, -S (P4), a symbolic mode (g+w,o=rx, since 0.04) | -S with a mask | | command (F12) | no argument (does nothing, status 0); command -v NAME; command [-p] PROGRAM ARGS (-p: P4); command BUILTIN ARGS for the regular builtins we run (cd, read, getopts, umask, wait, jobs, fg, bg, hash, type, ulimit; 3A, post-0.04) | -V, a special builtin or one left to sh after it, a builtin after command -p | | getopts (F12) | OPTSTRING NAME [ARGS] | fewer than two arguments, a NAME that is not an identifier or is shell-set | | unset | [-v\|-f] NAME… | other options, non-identifiers, shell-set names (CDPATH, PPID, LINENO, …; HOME may be unset since post-0.04), NAME[…] | | shift, exit, return | no argument or a number (return: 0–255; exit: up to 9 digits, taken modulo 256, P4) | others | | cd | as before, plus cd - | | | alias (B1) | NAME=VALUE… with literal names and values, as a whole top-level command (not in a compound command, a function, an and-or list, a pipeline or the background); queries alias NAME, listing alias anywhere | a name or value from a value whose first word is a keyword (since post3-0.04 an expansion, or alias in a compound command, a function, an and-or list, a pipeline or the background, is accepted: P1 below) | | unalias (B1) | -a, literal names; as a whole top-level command | others | | jobs (B3) | no arguments, -p, -l, then %N, %%, %+, %- (-p, -l in pipelines and $( ) as bash: rule E, 0.04; the job IDs post-0.04) | other arguments | | times (B3) | no arguments | any argument | | bg, fg, hash, type (B3) | anything; hash with -r or names; type with names | hash, type with other options | | ulimit (B3) | reading one limit: [-H\|-S][-n -s -c -t -v -l -m -d -f] | setting a limit (it would change the Perl process), -a, -u (not in dash) | | history, fc, bind, help, compopt, logout; set -o history (B2) | anything, unless the caller's option interactive is reject | | | set -o vi, set -o emacs (B2) | always (they do nothing in both shells) | | | kill (Q1) | as a program | an argument -SIGNAME, -sig…, or SIGNAME after -s or -l: both shells refuse the SIG prefix | | [, test (P5, R1, rule F) | every form: coreutils' [ decides (by default since 0.10 run inside Perl, Proc::ShellSpawn::Programs after coreutils 9.4, IP1; with PROC_SHELLSPAWN_INPROC=none the program /usr/bin/[), except s1 < s2 and s1 > s2 alone (also after !), which the executor compares itself, by bytes, as both shells (rule F, post3-0.04; POSIX 2024 has them: "collates before/after … in the current locale", the same in the C locale) | other forms with < or > between two operands ([ a \< b -a c ]), unless the caller's option test_lt_gt is set (then the program runs them, and fails) |

Still left to sh (X1): chdir source let declare typeset shopt enable builtin caller dirs pushd popd disown mapfile readarray suspend compgen complete compopt.

4. Tree additions (spec section 8)

Command  = { func => NAME, body => Command }                 # body: a group, subshell or compound command
         | { export => [NAME, Word or undef, ...] } | { readonly => [...] }
         | { local => [NAME, Word, ...] }
         | { exec => 1, redir => [Redir, ...] }               # exec with redirections only
         | { argv => [], redir => [Redir, ...] }               # redirections alone (D2)
         | { set => [...], redir => [Redir, ...] }           # settings with redirections (D2): redirect, then set
         | { argv => [Word, ...], ... }                       # argv->[0] may now be a Word with expansions
Redir    = [ fd, '<<', Word ]                                 # a here-document: the Word is the whole body
Part     = [ '$', N ], [ '"$', N ]                            # N may also be 0-9 (10... when braced), # @ * $
         | [ '${', N, OP, Word ], [ '"${', ... ]              # OP also = := ? :? % %% # ##
         | [ "'", 'text' ]                                    # quoted text in the Word of an unquoted ${N:-w}

5. Rules for the executor at run time

| Status | Meaning | |---|---| | 248 | Something outside the subset showed up only at run time (A4). 248 = 250 − 2: sh's status for a syntax error, moved out of the range that commands commonly use. |

6. Not done

Done since 2026-11-02: the executor runs these trees (lib/Proc/ShellSpawn/Large.pm), and the differences from dash that tools/large-subset-difffuzz.pl found, L1–L5, are fixed (doc/pspawn-known-issues.md); U1, U2, U4 and U5 are in lib/Proc/ShellSubset/Small.pm too.

7. Changes to lib/Proc/ShellSubset.pm (history: the patches of 2026-11-01/02, now in lib/)

The old Project's patches (claude/large-subset-shellsubset.patch and those named below; not shipped: their changes are in lib/Proc/ShellSubset.pm since), made against that module with the P1 fix of 2026-11-01 (claude/pspawn-parser-setting-name.patch).

8. Tests and measurements

The results of this section are of pre-0.01 and 0.01 (labels: ../README.md, last section). Those of 0.03 are in large-subset-state.md as shipped in 0.03, section 3, and large-subset-dialect-features.md, section 8; the test counts of 0.03 are given below in parentheses.