ShellSpawn: extension points, and the large subset (2026-11-01)

Status: EXPERIMENTAL; approved experimentally by the user on 2026-11-02 (00:24): "I (experimentally) endorsed every choice of yours." On 2026-11-01 (16:08) the user decided one thing: handlers in the parse tree are named by sub names, not code references. He left everything else to Claude ("decide yourself"), and asked that those decisions be marked experimental and awaiting his approval. They include D1–D3, first proposed on the page "Child Exit Wake-up" (removed since; it is in Proc-Spawner 0.03 on CPAN). Section 6 lists every such decision in one place.

Words and IDs used here.

Code: lib/ShellSpawn.pm (the executor, also claude/pspawn-ShellSpawn.pm) and the new lib/ShellSpawn/Large.pm (also claude/pspawn-ShellSpawn-Large.pm), in the bundle claude/pspawn-tree.tar.gz-base64.txt. The bundle's parser/ now holds ShellSubsetLarge.pm too.

1. What the executor runs now

ShellSpawn::run(STRING, parser => CODE) parses STRING with CODE, which returns a tree or an error hash; the same CODE reads the text of eval, . and trap actions. run(TREE) takes a ready tree. The user's decision of 2026-11-01 (19:39): the caller passes the parser, with a reasonable default. The default (Claude's choice, EXPERIMENTAL): the largest of ShellSubsetLarge, ShellSubset, ShellSubsetSmall that the caller has already loaded; if none is, ShellSubset is loaded. The executor loads no parser otherwise, and none of the three parsers needs a larger one (ShellSubsetLarge builds on ShellSubset). try.pl takes PARSER=small, base or large (default large). The large subset is large-subset/large-subset-spec.md: functions, local, return, export, readonly, exec anywhere and with redirections only, here-documents, positional parameters, $#, $@, $*, $$, the ${N=w} ${N?w} ${N%p} ${N#p} forms, assignments in $(( )), and the builtins set shift eval . trap wait umask command getopts unset, cd -, kill … $$.

2. The extension points

A handler is a sub named by its fully qualified name, such as ShellSpawn::Large::b_shift. The name is looked up at first use, and its module is loaded then (ShellSpawn::handler). A name, unlike a code reference, prints readably in a dumped tree, can be passed to another perl process, and cannot capture the tree, so it cannot form a reference cycle.

There are three kinds:

  1. Command nodes. A node { ext => NAME, … }, or a node with one of the keys of %ShellSpawn::KIND (func export readonly local exec, mapped to ShellSpawn::Large::x_func and so on). Called as NAME->(CONTEXT, NODE, TAIL, K), like the executor's own x_… subs.
  2. Command names. %ShellSpawn::CMD maps a name to [NAME, DATA]. The shell's own table $context->{sh}{cmd} is searched before %ShellSpawn::CMD; it holds the functions defined so far. Called as NAME->(CONTEXT, ARGV, ENV, K, DATA), where CONTEXT holds the command's redirections. The old builtins (: exit break continue read) are in the table too. Every builtin left to sh mapped to ShellSpawn::Large::b_unsupported (A4). Today a name is looked up in the list of tables @Proc::ShellSpawn::CMDS, and only builtins none of them has fall to Proc::ShellSpawn::Large::b_unsupported (the table %A4, last): alias and unalias are built (Proc::ShellSpawn::Builtins), and fc, history and the other interactive-only builtins go to b_interactive.
  3. Word parts. A Part [ext => NAME, …], called as NAME->(CONTEXT, PART, K) with K->(TEXT). No parser emits these yet. The limit of word parts: a handler passes one string to K, so it cannot make several fields, as "$@" must; that is why $@ is in the core (section 3).

The rules for every handler:

The functions a handler may use (the "context API") are the executor's own: var setvar expand expand_str each_async x_list x_cmd redirect spawn find_cmd msg defer leave fail hold release release_ctx release_all on_read on_write. Since post-0.12 they can be called through the short alias ProcSS (ProcSS::fail($c, 2, $text)), which Proc::ShellSpawn sets for Proc::ShellSpawn and which its own modules use (JU3).

3. What went into the core, and why

These change behaviour in many places, not at one node, so they are hooks in ShellSpawn.pm:

4. What went into the plug-in module ShellSpawn::Large

5. Choices of behaviour (all as dash; checked against dash 0.5.12)

6. Decisions taken by Claude (all EXPERIMENTAL; endorsed experimentally by the user, 2026-11-02)

| ID | Decision | Where | |---|---|---| | D1 | Option A: a C handler for SIGCHLD in the binding (PosixSpawn::chld_to_fd, chld_restore) writes the wake-up byte; select waits without a timeout. B1's stop-gap (a deferred Perl handler, and select waking every 50 ms) stays as the fallback, used only if the binding lacks the function. | loop_until, turn (today wait_until and turn of Proc::Spawner::Loop; the handler is set and put back in Proc::Spawner::Loop::POSIX) | | D2 | A wait started inside a reaction (a call into the loop, such as run(), from a queued continuation) dies: "ShellSpawn: wait inside a reaction". Before, it was allowed. | loop_until | | D3 | No change: the SIGCHLD handler is installed only while the loop waits, and the previous one is put back when the loop returns. | loop_until | | E1 | Three kinds of extension point, and their calling conventions (section 2). That they are named by sub names is the user's decision, not Claude's. | section 2 | | E2 | The split between core hooks (section 3) and the plug-in module (section 4). | | | E3 | Replaced by the user's decision of 19:39: the caller passes the parser (run(STRING, parser => CODE)). Claude's part: the default is the largest parser already loaded (section 1). A4 (stop with status 2 when something unsupported shows up only at run time) then applies only where the caller chose ShellSubsetLarge, or loaded it. | run, default_parser | | E4 | run() reports a death by kill … $$ as 128 + N plus $SIGNALLED, not by killing Perl. | run, b_kill | | E5 | Signal traps act only between reactions, and only while run() runs. | b_trap |

To reject one of these, say which. D1 falls back to B1's stop-gap by removing the C handler; D2 to allowing nested waits; E3 to ShellSubset::parse. The others need a new design.

7. Tests (2026-11-01)

This section is of 2026-11-01. The current tests: t/dash.t (with the known differences in t/dash-known.txt), t/memory.t and the other files of t/; what did not pass at each level of the spawn primitive: test-results/.

8. Not done, limits