Revision history for BATsh

0.03  2026-06-06 JST (Japan Standard Time)

    - t/lib/INA_CPAN_Check.pm: emit exactly one TAP plan line per test
      file. Each check_* helper previously called plan_tests() itself,
      while the .t files also called plan_tests(count_*); this produced
      multiple "1..N" lines in a single file. Under a real TAP harness
      (prove / Test::Harness, as used by CPAN Testers) this raised
      "More than one plan found in TAP output" and made the affected
      files FAIL, even though every individual "ok" line passed when the
      scripts were run by hand. Affected files: t/9010-encoding.t,
      t/9030-distribution.t, t/9040-style.t. The plan_tests() call is
      now removed from every check_* helper, leaving the .t file as the
      sole owner of the plan line.
    - t/lib/INA_CPAN_Check.pm: count_A() now returns the actual number
      of MANIFEST entries instead of a fixed 1, so that the plan
      computed by t/9030-distribution.t matches the number of A1 checks
      that check_A() emits.
    - t/lib/INA_CPAN_Check.pm: remove the mid-stream plan_skip() calls
      from check_A() and check_C(); the MANIFEST-absent guard is handled
      by the .t file and by count_C() before any plan line is printed.
    - t/lib/INA_CPAN_Check.pm: check_K() now honours the k3_exempt
      option passed by t/9040-style.t. The argument was previously
      discarded by "my ($root) = @_;", so the intended exemption of
      accessor-style hash names (%env, %opts, %args) never took effect;
      the K3 detector also did not capture the hash name. check_K() now
      accepts "k3_exempt => REGEX", captures the returned hash name via
      /return \%(\w*)/, and skips a "return \%name" only when the name
      matches the supplied pattern. Behaviour is unchanged when
      k3_exempt is not passed (every "return \%..." is still flagged),
      so distributions that call check_K($root) without the option are
      unaffected.
    - t/lib/INA_CPAN_Check.pm: add a regression guard for the two TAP
      defect classes above. plan_tests() now refuses to emit a second
      "1..N" line, and an end-of-run reconciliation reports
      "planned X but ran Y" (setting a non-zero exit) when the emitted
      plan does not match the number of ok()/not-ok() lines. Both
      problems now FAIL immediately on a plain "perl t/foo.t", not only
      under a real harness.
    - t/lib/INA_CPAN_Check.pm: add selfcheck_suite(), which runs t/*.t
      (and xt/*.t) in a child Perl and verifies one plan line per file,
      plan == number of ok/not-ok lines, and no failures.
    - pmake.bat: at "pmake dist" time, after the existing source checks,
      run INA_CPAN_Check::selfcheck_suite() as check3 and abort the
      build if any test file fails the plan-sanity check (disable with
      --no-check3). Bump $PMAKE_BAT_VERSION to 0.34.
    - t/lib/INA_CPAN_Check.pm: pass \@files / \@pm_files (a reference)
      instead of [ @files ] (an anonymous copy) to _find_pm_t() in
      _scan_code(), check_D(), check_E(), and check_K(). The copy form
      meant the collected file list never reached the caller, so E1
      (no shebang in lib/*.pm) and K3 (return { %hash } form) silently
      scanned zero files and always passed.

    - Documentation: BATsh.pm BUGS AND LIMITATIONS corrected. It no longer
      claims SH-mode background execution is unsupported (it is supported
      for external commands; see above and BATsh::SH), and it now clarifies
      that non-builtin commands (FINDSTR, SORT, etc.) are invoked as
      external programs rather than "unsupported". README and BATsh.pm POD
      additionally enumerate previously undocumented limitations: CMD
      "%VAR:~n,m%" / "%VAR:str1=str2%" and dynamic "%RANDOM%/%DATE%/%TIME%/
      %CD%" variables; SH arrays, filename globbing, "~" tilde expansion,
      brace expansion, and the trap/getopts/select/alias/declare/eval/exec
      builtins and set -e/-u/-x options; and the shared (no sub-shell)
      "( ... )" grouping common to both modes.

    - SH expansion: a backslash-escaped "\$", "\`" or "\\" inside double
      quotes is now preserved literally and no longer triggers variable
      or command substitution (e.g. "\$_" yields a literal "$_").

    - SH read: the "read" built-in now returns a non-zero status at end of
      input so that "while read VAR; do ...; done < FILE" terminates
      instead of looping. Leading option flags such as "-r" are skipped
      and are no longer treated as target variable names.

    - SH assignment prefix: "VAR=value command args" (POSIX) now applies
      the assignment and then runs the command (e.g. "IFS= read -r LINE",
      "LC_ALL=C sort"); multiple prefixes are supported. A standalone
      assignment whose value merely contains spaces or a "$(...)"
      substitution (e.g. UPPER=$(echo "a b")) keeps the full value and is
      no longer mistaken for a prefix.

    - SH while/until: an input redirection on the "done" line
      ("while read L; do ...; done < FILE") now reopens STDIN from FILE for
      the duration of the loop so the loop's "read" consumes the file.

    - eg/06_sh_comprehensive.batsh: I/O-redirection section simplified to a
      plain "while read" loop now that the loop terminates correctly.

    - Tests: t/9070-examples.t now executes each eg/*.batsh in a child
      process and guards against runaway output and "syntax error"
      breakage (E4). t/9060-readme.t verifies the README advertises every
      eg/ example by name (R5). README gains an EXAMPLES section.

    - SH background execution: an unquoted trailing "&" starts an external
      command asynchronously and returns immediately. On Win32 the job is
      spawned via system(1, ...) (P_NOWAIT, PID returned); on Unix it is
      started through /bin/sh without a Perl fork, capturing the job PID
      via the shell's $! into a sysopen O_CREAT|O_EXCL temp file (Pure
      Perl, 5.005_03). The new $! parameter expands to the most recent
      background PID (empty before any job); $? is 0 on a successful
      launch (the job's own exit status is not awaited). Built-ins,
      functions, assignments and control words ignore the trailing "&"
      and run in the foreground; "&&", ">&"/"2>&1", quoted and escaped
      "\&" are not treated as background. No job control; CMD-mode "&"
      remains a sequential separator (see BUGS AND LIMITATIONS).

    - eg/05_cmd_comprehensive.batsh: the "IF ERRORLEVEL" diagnostic line
      "ECHO   ERRORLEVEL>=0: ELTEST=%ELTEST%" contained a bare ">", which
      CMD mode correctly treats as output redirection (matching cmd.exe).
      As written, the message was silently redirected to a file named
      "=0:" instead of being printed, and that stray file was created in
      the current directory each time the example ran (including under
      "make test" via t/9070-examples.t). The ">" is now caret-escaped
      ("ECHO   ERRORLEVEL ^>= 0: ELTEST=%ELTEST%"), so the line prints
      as intended and no file is written.

0.02  2026-04-28 JST (Japan Standard Time)

    [Highlights]
    - Full bash/sh interpreter implementation: if/for/while/until/case,
      function definitions (name() { ... }), local variable scoping,
      && / || / ; compound commands, pipelines (|), I/O redirection
      (> >> < 2> 2>> 2>&1), variable expansion (${var%pat}, ${var#pat},
      ${#var}, ${var^^}, ${var,,}, ${var:N:L}, ${var/p/r}, ${var//p/r}),
      positional parameters $1..$9 / $@ / $* / $#, shift, read, source.
    - cmd.exe pipeline (|) support via temporary file (Pure Perl, 5.005_03).
    - I/O redirection: stdout overwrite (>), append (>>), stdin (<),
      stderr (2>), stderr-to-stdout (2>&1), stdout-to-stderr (1>&2).
      Supported in both CMD mode and SH mode.
    - SH here-documents on STDIN: cmd <<DELIM ... DELIM, <<-DELIM (strip
      leading tabs), and <<'DELIM' (literal, no expansion). Body is
      materialised to a temp file created with sysopen O_CREAT|O_EXCL
      (Pure Perl, 5.005_03) and fed through the existing "< file" path,
      so both built-ins (read) and external commands see it on STDIN.
      Top-level mode dispatch is here-document aware, so uppercase body
      lines are not misrouted to CMD mode. Single here-document per line;
      here-strings (<<<) and same-line pipeline/compound combos are not
      supported (see BUGS AND LIMITATIONS).
    - cmd.exe batch-parameter tilde modifiers: %~0, %~f1, %~dp0, %~nx1,
      %~n0, %~x0, %~p1 etc. (f d p n x modifiers, combinable).
    - SET /P VAR=Prompt  interactive prompt input from STDIN.
    - $0 normalised to absolute path via File::Spec on run().

    [BATsh::Env]
    - Variable names are now stored and looked up in uppercase, matching
      cmd.exe's case-insensitive environment variable behaviour.
      SET myvar=x  followed by  ECHO %MYVAR%  now correctly outputs "x".
    - Added $DELAYED_EXPANSION package variable (default 0).
    - setlocal() now accepts an options string and parses
      ENABLEDELAYEDEXPANSION / DISABLEDELAYEDEXPANSION.
      The delayed-expansion flag is saved/restored with the variable store.
    - expand_cmd() now expands !VAR! references when $DELAYED_EXPANSION is on.

    [BATsh::CMD]
    - Implemented ^ escape character:
        ^X          -> literal X (protects & | < > etc.)
        ^^          -> literal ^
        trailing ^  -> line continuation (joins next line)
    - Implemented I/O redirection parsed before command dispatch:
        >file       stdout overwrite
        >>file      stdout append
        2>file      stderr overwrite
        2>>file     stderr append
        <file       stdin redirect
      Redirects with ^> are correctly treated as escaped > (not a redirect).
      fd-digit stripping limited to isolated '1' or '2' before '>' to avoid
      consuming trailing digits of command arguments (e.g. "ECHO line1 >f").
    - SETLOCAL now passes its option string to BATsh::Env::setlocal() so
      ENABLEDELAYEDEXPANSION and DISABLEDELAYEDEXPANSION take effect.
    - !VAR! delayed expansion: pre_expanded block bodies now call expand_cmd()
      at runtime when delayed expansion is active, so SET inside an IF/FOR
      block followed by ECHO !VAR! correctly reflects the updated value.
    - IF block pre-expansion: %VAR% in parenthesised IF/ELSE bodies is now
      expanded at parse time (matching cmd.exe semantics), so a SET inside the
      block does not affect %VAR% references in the same block.
    - FOR block pre-expansion: %VAR% in parenthesised FOR bodies is expanded
      once before the first iteration (at FOR-line parse time) and cached;
      the loop variable is substituted per-iteration via an internal placeholder.
    - IF /I (case-insensitive comparison) is now parsed before plain == so
      that "/I" is not consumed as part of the left-hand operand.
    - IF EXIST now handles quoted paths that contain spaces.
    - ECHO no longer resets ERRORLEVEL to 0 after printing.
    - FOR /F fully implemented:
        tokens=N,M-P  select specific token columns
        tokens=N*     select token N and put the remainder in the next variable
        delims=CHARS  field delimiters (default space/tab)
        skip=N        skip the first N lines of the source
        eol=C         skip lines beginning with character C (default ;)
        usebackq      swap quoting: "file" reads a file, 'cmd' runs a command
      Sources: bare filename, quoted filename, 'command' (backtick output),
      and ("literal string").
    - & (sequential), && (conditional-success), || (conditional-failure)
      compound commands are now supported.
    - SET VAR=value: variable name regex relaxed to accept any non-'=' prefix,
      matching cmd.exe's permissive variable naming.

    [BATsh::SH]
    - Full bash/sh interpreter implemented as Pure Perl (no external shell).
    - Control structures: if/then/elif/else/fi, for/do/done, while/do/done,
      until/do/done, case/esac with glob-pattern matching.
    - Function definitions: name() { ... } and function name { ... } syntax,
      including inline single-line bodies.  Functions receive positional
      arguments $1..$9; caller's arguments are saved and restored on return.
    - local variable scoping: local VAR=value saves the caller's value and
      restores it when the function returns.
    - Compound commands: cmd1 && cmd2, cmd1 || cmd2, cmd1 ; cmd2.
    - Pipeline: cmd1 | cmd2 [| cmd3 ...] implemented via temporary files
      (Perl 5.005_03 compatible bareword filehandles, no fork/exec).
    - I/O redirection: > >> < 2> 2>> 2>&1 1>&2, parsed after variable
      expansion so that filenames may contain variables.
    - Variable expansion: $VAR, ${VAR}, $1..$9, $@, $*, $#, $?, $$, $0.
      Parameter expansion forms: ${VAR:-default}, ${VAR:=default},
      ${VAR:+alt}, ${VAR%pat}, ${VAR%%pat}, ${VAR#pat}, ${VAR##pat},
      ${VAR/pat/rep}, ${VAR//pat/rep}, ${VAR^^}, ${VAR^}, ${VAR,,}, ${VAR,},
      ${VAR:N:L}, ${VAR:N}, ${#VAR}.
      Glob patterns in %/%%/#/## support *, ?, and [abc] character classes.
    - Arithmetic expansion: $(( expr )) with +, -, *, /, %, and positional
      parameters $1..$9 inside the expression.
    - Command substitution: $( cmd ) with full nesting/quoting support, and
      backtick `cmd` form.
    - shift [N]: shifts positional parameters left by N positions (default 1),
      updating both %N and %* in BATsh::Env.
    - read VAR: reads one line from STDIN, chomps it, stores in VAR.
    - source / . file: executes an external file in the current SH context.
    - Builtin commands: echo, printf, cd, pwd, exit, true, false, :, export,
      unset, set (noop), test / [ ... ] with -f -d -e -r -w -x -s -z -n
      and string (= == != < >) and integer (-eq -ne -lt -le -gt -ge) ops.
    - _cmd_subst uses fixed bareword filehandles (_SUBST_SAVOUT etc.) to
      avoid collision under Perl strict and recursive invocations.
    - _sh_strip_redirects and _sh_exec_with_redirs added for I/O redirection.
    - _replace_cmd_subst added: walks $( ) depth-tracking the nesting so that
      $( cmd | perl -e "print uc" ) parses the closing ) correctly.
    - _split_sh_compound and _exec_sh_compound added for && / || / ; handling.
    - _split_sh_pipe and _exec_sh_pipe added for pipeline handling.
    - $0 is set to the absolute path of the running script by BATsh::run().

    [BATsh.pm]
    - _exec_cmd_section no longer intercepts SETLOCAL/ENDLOCAL itself;
      both are passed through to BATsh::CMD::_dispatch so the option string
      (ENABLEDELAYEDEXPANSION etc.) is correctly forwarded.

0.01  2026-04-26 JST (Japan Standard Time)

    - Initial CPAN release.