bashexpand 0.1.1

Bash-style parameter expansion (${var:-default}, ${var@L}, ${var##pat}, ...) over any variable source: maps, closures, the environment, or your own backend.
Documentation
# SPEC — bashexpand

## §G goal

Rust lib crate. Bash-style `${...}` parameter expansion, full operator set, over pluggable var source (`Context` trait): map, closure, env, custom backend. Zero deps.

## §C constraints

- C1 zero dependencies, by design (Cargo.toml empty deps)
- C2 `#![forbid(unsafe_code)]`, `#![warn(missing_docs)]`
- C3 MSRV 1.70, edition 2021
- C4 no shell semantics beyond expansion: NO arrays, NO positional/special param semantics (`$@`/`$?`; digit name like `$1` = plain ctx var, see V17), NO `$(...)`, NO `$((...))`, NO extglob `@(...)`, NO POSIX classes `[[:alpha:]]`, NO `@P/@A/@K/@a`
- C5 safe on untrusted templates: linear glob + depth limit
- C6 all ops char-based (Unicode correct, not byte)
- C7 MIT license

## §I interfaces

- I.expand — `fn expand(input, &mut ctx) -> Result<String, Error<C::Error>>` (src/lib.rs:408)
- I.expander — `Expander::new().max_depth(n).expand(...)` builder; `DEFAULT_MAX_DEPTH = 64` (src/lib.rs:435)
- I.context — trait `Context { type Error; get(&mut, name) -> Result<Option<Cow<str>>, E>; set(&mut, name, val) -> Result<bool, E> }`; default `set` = `Ok(false)` read-only (src/lib.rs:160)
- I.impls — `Context` for: `HashMap<String,String>` (writable), `BTreeMap<String,String>` (writable), `&HashMap<String,String>` (RO), `&BTreeMap<String,String>` (RO), `FnMut(&str)->Option<String>` (RO), `Env` (process env, RO), `TryFn<F>` (fallible), `Chain<A,B>`
- I.chain — `ContextExt::chain(fallback)`, nestable; get: first hit win; set: first writable win
- I.error — `Error<E>` enum: `Required{var,message}`, `BadSubstitution(String)`, `AssignUnsupported{var}`, `TooDeep`, `Context(E)`; `From<E>`, `Display`, `std::error::Error`
- I.syntax — operators: `$var` `${var}` `${v:-w}` `${v-w}` `${v:=w}` `${v=w}` `${v:+w}` `${v+w}` `${v:?m}` `${v?m}` `${#v}` `${!v}` `${v:off}` `${v:off:len}` `${v#p}` `${v##p}` `${v%p}` `${v%%p}` `${v/p/r}` `${v//p/r}` `${v/#p/r}` `${v/%p/r}` `${v^}` `${v^^}` `${v,}` `${v,,}` (opt glob) `${v@U}` `@u` `@L` `@Q` `@E}` `\$`
- I.glob — `*` `?` `[a-z]` `[!a-z]` `[^a-z]` `\x` escapes
- I.examples — examples/: config_template, custom_backend, inline_closure, layered_config

## §V invariants

- V1 no unsafe, no deps — build fail if either appear (C1, C2)
- V2 glob match iterative O(pat×text); `a*a*a*a*b` vs 200 chars no blowup (test glob_no_blowup)
- V3 nesting deeper than max_depth → `Error::TooDeep`; nesting counted in operator words, patterns, replacements (test depth_limit, expander_custom_depth)
- V4 `:=` on RO ctx → `Error::AssignUnsupported`, never silent continue (test inline_closure_read_only)
- V5 ctx lookup error → `Error::Context(E)`, never treated as unset (test fallible_backend_with_tryfn)
- V6 unset var plain `${v}` → `""`; colon forms (`:-` `:=` `:+` `:?`) treat set-but-empty as missing, colon-less forms don't (tests defaults, bash_parity_table)
- V7 char-based Unicode: `${#s}` counts chars, substring by char index, case ops full Unicode (test unicode)
- V8 `@Q` output safe single-quoted shell word incl embedded `'` (test quoting_is_safe)
- V9 chain get first hit win, chain set first writable win, chains nest (tests chain_*)
- V10 malformed expansion (`${unclosed`, unknown op, bad substring spec, unknown `@` transform) → `Error::BadSubstitution`, never panic (test bad_substitution)
- V11 operator words recursively expanded: `${a:-${b:-c}}` (test defaults)
- V12 output match bash for operator set in I.syntax (test bash_parity_table)
- V13 `\$` → literal `$`; lone `$` pass through verbatim (test basics)
- V14 `@` transform on UNSET var → `""`, even unknown transform (`${u@Z}` → `""`); unknown transform on SET var still `BadSubstitution` — bash 5.1 parity (test fuzz_parity_with_real_bash + unit)
- V15 substring negative offset beyond `-len` (`${v: -k}`, k > #v) → `""`, no clamp to 0 — bash parity (test fuzz_parity_with_real_bash + unit)
- V16 shared-ref map ctx (`&HashMap`, `&BTreeMap`) RO: get work via `Cow::Borrowed` (no alloc), `:=` → `Error::AssignUnsupported` (V4 path), expand callable with only `&map` in scope
- V17 name = `[_alnum]+`, digit-lead OK: `$1`/`${1}` → ctx lookup `"1"`, unset → `""` (V6) — same as bash read positional param, ctx = param store; fuzz gen (T4) must not emit digit-lead names (bash side would read positional args, not env)
- V18 assign to digit-lead name (`${1=w}`, `${1:=w}`) → `Error::AssignUnsupported` when assign would fire, even on writable ctx — bash parity "cannot assign in this way"; no-op when var set (`${1=w}` on set var → value, no error) (test basics)
- V19 docs no drift: README + crate-doc code fences compile & pass as doctests (`cargo test --doc` incl README via `#[cfg(doctest)]` include); README non-goals list = C4 exactly; CHANGELOG unreleased section list every user-visible feature merged

## §T tasks

id|status|desc|cites
T1|x|fix Cargo.toml URLs — repo/docs say `bash-expand`, remote = `param-expand`, crate = `bashexpand`|§C
T2|x|release 0.1.0 — CHANGELOG say unreleased ?|§C
T3|.|CI setup — Cargo.toml exclude `.github/` but dir absent ?|V1,V12
T4|x|fuzz/property test vs real bash for parity|V12,V14,V15
T5|x|impl `Context` for `&HashMap`/`&BTreeMap` (RO) + doc note in trait/crate docs + tests|V4,V16,I.impls
T6|x|fix doc drift — README non-goals still ban `$1`, `@a` absent, no digit-name note, no RO `&map` mention; CHANGELOG 0.1.0 miss RO map ctx + digit-name features|V16,V17,V19
T7|x|recipes in built docs — crate rustdoc `# Recipes` section (doctested) + README fences doctested via `#[cfg(doctest)]` `include_str!`|V19,I.examples

## §B bugs

id|date|cause|fix
B1|2026-07-29|`@` branch read `value.unwrap_or_default()` — unset vs empty erased before transform → `${u@Q}` gave `''`, bash gives `""` (src/lib.rs:603,630)|V14
B2|2026-07-29|substring start clamp `(n + off).max(0)` — out-of-range negative offset became 0 → whole string, bash gives `""` (src/lib.rs:800)|V15
B3|2026-07-29|`read_name`/`is_name` reject digit-lead name → `${1}` `BadSubstitution`, `$1` literal passthrough; old V13/C4 pinned it (src/lib.rs:799,816)|V17
B4|2026-07-29|B3 fix let `${1:=x}` assign key `"1"` on writable ctx + V17 misframed numeric lookup as bash divergence — bash read positional same way, only assign forbidden (src/lib.rs:601)|V18