From 66df76c82e2ea355c7aecbcc284bd6c3fa62d5cf Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 12 Jul 2026 21:24:24 +1000 Subject: [PATCH] G-045 achieved: punk::args 0.8.1 define quoting documentation; flip + archival edits (project 0.12.8) Increment 5 (final): the container quoting rules pinned by defquoting.test now appear in the punk::args::define -help documentation - braced values fully literal (backslash sequences survive as typed); double-quoted values get Tcl backslash semantics at record parse while $ and [] stay literal with no substitution outside tstr placeholders; the backslash-escaped placeholder idiom renders a literal placeholder. Rendered section verified in punk902z src (meta-escapes display correctly). punk::args suite 186 pass / 1 pre-existing skip / 0 fail. Acceptance review recorded in the detail file: all criteria satisfied across increments 1-5 (@cmd -unindentedfields 0.6.1, i help alignment punk 0.2.4, -& record continuation 0.7.0, @normalize + define_docs consumer proof 0.8.0/punk 0.2.5, quoting documentation 0.8.1; suite grown 128 -> 187 tests, GAPs flipped, none weakened, full source-tree suite zero regressions). Flip edits: G-045 index entry moved to GOALS-archive.md (achieved 2026-07-12), detail file Status flipped with evidence in Progress, reference sweep updates G-053 notes. The detail file move to goals/archive/ follows in the next commit as a pure rename (per the goals/AGENTS.md archive rules) - goals_lint is transiently unclean between the two. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- CHANGELOG.md | 4 +++ GOALS-archive.md | 4 +++ GOALS.md | 4 --- goals/G-045-punkargs-authoring-ergonomics.md | 38 +++++++++++++++++--- goals/G-053-punkargs-multiple-ranges.md | 5 +-- punkproject.toml | 2 +- src/modules/punk/args-999999.0a1.0.tm | 24 ++++++++++--- src/modules/punk/args-buildversion.txt | 3 +- 8 files changed, 68 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2d63057..0ef695b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to Entries are newest-first; one bullet per notable change. See the root `AGENTS.md` "Project Versioning" section for the bump policy. +## [0.12.8] - 2026-07-12 + +- G-045 achieved: punk::args 0.8.1 documents the definition container quoting rules in the punk::args::define help (braced values fully literal; double-quoted values with Tcl backslash semantics at record parse while $ and [] stay literal; the backslash-escaped tstr placeholder idiom). This completes the definition authoring ergonomics goal: @cmd -unindentedfields honoured (0.6.1), -& record continuation (0.7.0), @normalize block-form indent normalization with the help-system definitions as consumer proof (0.8.0 / punk 0.2.5), quoting documentation (0.8.1). + ## [0.12.7] - 2026-07-12 - G-045 (increment): punk::args 0.8.0 adds the bare @normalize directive - opts a definition into indent normalization of block-form multi-line field values (structural leading newline dropped, content re-based to the file-style 4-space continuation convention, relative indents preserved, -unindentedfields exempt, no-op on conforming file-style definitions). Intended for constructed (string-built) definitions. punk 0.2.5: the help-system definitions (::punk::help / help_chunks) convert to indented block authoring under @normalize; 'i help' rendering unchanged. diff --git a/GOALS-archive.md b/GOALS-archive.md index e880a091..22abaed9 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -46,6 +46,10 @@ Acceptance: a documented procedure reproduces the spin on the current kit (e.g. Scope: src/modules/punk/args-999999.0a1.0.tm (parse + usage rendering), src/modules/punk/ns-999999.0a1.0.tm (cmdinfo/cmd_traverse choice resolution parity), src/modules/punk-999999.0a1.0.tm (punk::help topic argdoc as first consumer), src/tests/modules/punk/args/testsuites/, src/tests/modules/punk/ns/testsuites/ Acceptance: a definition using -choicealiases parses an alias (and an alias prefix where -choiceprefix allows) to its canonical choice in the parse result, with -choicerestricted 0 passthrough and the deny/reserve lists honoured unchanged; usage display shows one entry per canonical choice with aliases folded (no duplicate rows; -choicelabels attach to the canonical); punk::ns::cmdinfo/cmd_traverse resolve subcommand words to docids with the same outcome as the parser for alias, prefix, denied, reserved and unknown words (the pre-goal characterization tests updated from pinned-GAP to fixed); punk::help's topic definition adopts the feature so `i help` lists one entry per registered topic while `help h`/`help e` still fall through to command lookup; definitions without -choicealiases behave unchanged (existing punk::args and punk::ns suites pass). +### G-045 [achieved 2026-07-12] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization → detail: goals/archive/G-045-punkargs-authoring-ergonomics.md +Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof) +Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened. + ### G-046 [achieved 2026-07-10] punk::args deferred -help resolution (parse-time performance + reentrancy) and rendering/value-shape fixes → detail: goals/archive/G-046-punkargs-deferred-help-and-fixes.md Scope: src/modules/punk/args-999999.0a1.0.tm (resolve/get_dict: display-field deferral, dynamic-cache subst path, prefix writeback, string renderer, cmdhelp-facing messages), src/modules/punk/ansi-999999.0a1.0.tm (mark_columns argdoc as the reentrancy/perf testbed), src/tests/modules/punk/args/testsuites/ (GAP tests flip; perf verification) Acceptance: parsing/argument resolution provably skips -help expansion (a definition whose -help contains a ${[...]} that would error or record its invocation shows the substitution did NOT run during a parse-only path, only for help display); first parse of punk::ansi::mark_columns drops from ~4s to well under a second with 'i punk::ansi::mark_columns' still rendering the embedded example, and a -help that parses its OWN definition id resolves or errors cleanly rather than looping; first-parse timing improves for at least one other heavily documented command (recorded in the detail file); rendering_atdynamic_multiline_help_insertion_GAP flips to all-aligned; choicegroups_imap_prefix_listwrap_GAP flips to shape-identical (prefix input yields the same plain string as exact input); the -return string renderer's cmd-help continuations align under the first line with relative indents preserved (rendering_string_renderer_characterization updated); the 'Bad number of leading values...' prefix shown by goodargs parsing in 'i string is'-style output is reworded or suppressed for the usage-display path; full punk::args and punk::ns suites pass with no non-GAP expectations weakened. diff --git a/GOALS.md b/GOALS.md index 7aaea16e..6090dce6 100644 --- a/GOALS.md +++ b/GOALS.md @@ -210,10 +210,6 @@ Detail: goals/G-043-subshell-definition-plugins.md Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering) Detail: goals/G-044-repl-command-completion.md -### G-045 [active] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization -Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof) -Detail: goals/G-045-punkargs-authoring-ergonomics.md - ### G-047 [proposed] Declared primary VCS in punkproject.toml with per-developer commit-target override Scope: punkproject.toml (schema), punkproject.local.toml (new, uncommitted per-checkout override), root AGENTS.md (Commit Conventions (any VCS) section), .gitignore + .fossil-settings/ignore-glob (ignore rules for the local file, per the coexistence contract), src/project_layouts/ (layout template payload - default values and ignore seeding only; project.new validation is follow-on work) Detail: goals/G-047-declared-primary-vcs.md diff --git a/goals/G-045-punkargs-authoring-ergonomics.md b/goals/G-045-punkargs-authoring-ergonomics.md index 602611bc..7cd18381 100644 --- a/goals/G-045-punkargs-authoring-ergonomics.md +++ b/goals/G-045-punkargs-authoring-ergonomics.md @@ -1,6 +1,6 @@ # G-045 punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization -Status: active +Status: achieved 2026-07-12 Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof) Goal: authoring punk::args definitions no longer requires backslash line-continuations or ad-hoc workarounds for multi-line records and constructed definitions - a parser-recognised record-continuation mechanism (candidate: an unquoted trailing -& token, with the detail file recording the collision analysis and the element-count disambiguation alternative), -unindentedfields honoured for @cmd fields, and constructed (string-built) definitions able to opt into the same whole-block indent normalization file-style definitions get - with the container quoting rules (braced=literal, quoted=Tcl backslash semantics, \$\{ escape) promoted from defquoting.test into the define documentation. Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened. @@ -228,6 +228,36 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te regressions; make.tcl modules builds clean; 'i help'/'i help_chunks' verified aligned in punk902z src. -Remaining for acceptance: -- defquoting.test container quoting rules promoted into the punk::args::define - -help documentation +### 2026-07-12 increment 5: define quoting documentation (punk::args 0.8.1) - acceptance complete + +- The container quoting rules pinned by defquoting.test now appear in the + punk::args::define -help documentation (-help key section): braced values + fully literal; double-quoted values with Tcl backslash semantics at record + parse ($ and [] literal, no substitution outside tstr placeholders); the + backslash-escaped placeholder idiom. Rendered output of the new section + verified in punk902z src - the meta-escapes display as intended (\n as two + characters, \Deleted, doubled backslash, literal dollar-brace placeholders). +- punk::args suite 186 pass / 1 pre-existing skip / 0 fail (tclsh 9.0.3). + +Acceptance review at flip (2026-07-12): all criteria satisfied. +- -& record continuation parses identically to its backslash equivalent + (recordcontinuation.test byte-equality; additive - existing definitions + unchanged); collision rules and the {-&} escape documented (increment 3). +- @cmd -help/-summary honour -unindentedfields; + rendering_unindentedfields_cmd_help_GAP flipped to aligned (increment 1; + -summary vacuously honoured - no renderer transforms it, verified). +- Constructed definitions can request whole-block normalization (@normalize, + block-form values); rendering_constructed_def_indent_characterization + updated to the chosen opt-in semantics (unopted behaviour pinned as + contract); ::punk::helptopic::define_docs dropped its manual + pre-normalization - first to interim left-margin authoring (increment 2), + then to indented blocks + @normalize as the consumer proof (increment 4). +- Quoting rules from defquoting.test appear in the define -help documentation + (increment 5). +- Full punk::args suite passes with GAP tests flipped, none weakened: 186 + pass / 1 pre-existing skip / 0 fail (suite grown from 128 to 187 tests via + the new recordcontinuation.test and normalize.test); full source-tree suite + showed zero regressions at increments 3 and 4 (exec-14.3 known baseline + only). Verified on native tclsh 9.0.3 plus punk902z src for rendered + output; punk 0.2.5 / punk::args 0.6.1-0.8.1 shipped in project versions + 0.12.4-0.12.8. diff --git a/goals/G-053-punkargs-multiple-ranges.md b/goals/G-053-punkargs-multiple-ranges.md index dfd25e7c..e0bb19d5 100644 --- a/goals/G-053-punkargs-multiple-ranges.md +++ b/goals/G-053-punkargs-multiple-ranges.md @@ -62,8 +62,9 @@ rendering gain meaningful bounded-repetition forms (e.g. "0-1", "2-4"). - `-multipleunique` / `-multipleuniqueset` remain the uniqueness knobs and only make sense for max > 1; they compose with ranges unchanged. -- Related: G-045 (authoring ergonomics), G-046 (parse-time performance - the - canonicalization must not regress the hot path). +- Related: G-045 (authoring ergonomics, achieved 2026-07-12 - see + goals/archive/G-045-punkargs-authoring-ergonomics.md), G-046 (parse-time + performance - the canonicalization must not regress the hot path). - The runtests `-include-paths` fix (repeatable, accumulate, single-list form still accepted) shipped independently on 2026-07-10 and does not depend on this goal. - Archived-goal references in this file: G-046 achieved 2026-07-10 (goals/archive/G-046-punkargs-deferred-help-and-fixes.md). diff --git a/punkproject.toml b/punkproject.toml index 1e19d6e3..d640f65d 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,4 +1,4 @@ [project] name = "punkshell" -version = "0.12.7" +version = "0.12.8" license = "BSD-2-Clause" diff --git a/src/modules/punk/args-999999.0a1.0.tm b/src/modules/punk/args-999999.0a1.0.tm index 176db2c7..f8644005 100644 --- a/src/modules/punk/args-999999.0a1.0.tm +++ b/src/modules/punk/args-999999.0a1.0.tm @@ -1081,10 +1081,26 @@ tcl::namespace::eval punk::args { For the @examples directive this is the text for examples as displayed with 'eg ' The -help string can be delimited with double quotes or with - curly braces, the choice will affect what inner chars require - backslash escaping - but neither type of help block is - automatically subject to variable or command substitution aside - from those specifically wrapped in placeholders. + curly braces. The container determines the quoting rules, + which apply to multi-line field values generally: + + Braced {...} values are fully literal: $, [] and backslash + sequences all survive as typed (\\n stays two characters, + and a bare backslash as in \\Deleted keeps its backslash). + Only tstr placeholders (when \$\{...\} content is present + anywhere in the definition block) and their backslash + escape are special. + + Double-quoted \"...\" values get Tcl backslash semantics + at record parse: \\n becomes a real newline and \\\\ + collapses to a single backslash - while $ and [] remain + literal. No variable or command substitution is performed + on record content outside \$\{...\} tstr placeholders. + + In a tstr-processed block, escaping the placeholder's + dollar sign and braces with backslashes renders a literal + placeholder - the idiom used for the \$\{...\} examples + throughout this help text. For cases where unbalanced braces, double quotes are to be displayed to the user without visible backslash escapes, diff --git a/src/modules/punk/args-buildversion.txt b/src/modules/punk/args-buildversion.txt index be9b495b..8378f85d 100644 --- a/src/modules/punk/args-buildversion.txt +++ b/src/modules/punk/args-buildversion.txt @@ -1,6 +1,7 @@ -0.8.0 +0.8.1 #First line must be a semantic version number #all other lines are ignored. +#0.8.1 - G-045 documentation-only: the container quoting rules pinned by defquoting.test promoted into the define -help documentation (-help key section): braced values fully literal (backslash sequences survive as typed) with only tstr placeholders and their backslash escape special; double-quoted values get Tcl backslash semantics at record parse (\n -> newline, doubled backslash collapses) while $ and [] stay literal with no variable/command substitution outside tstr placeholders; the backslash-escaped placeholder idiom renders a literal placeholder. #0.8.0 - G-045: new bare @normalize directive - opts a definition into indent normalization of BLOCK-FORM multi-line field values (first line whitespace-only, as authored by opening a braced literal with a newline): the structural first newline and a whitespace-only trailing line are dropped, the content lines' common leading whitespace is the block's base indent, the first content line is unindented fully and subsequent lines re-based to the standard 4-space continuation convention (deeper relative indents preserved; whitespace-only inner lines become empty). Head-form values are never altered - their base indent is ambiguous (uniform continuation indent may be the deliberate +2 relative convention over base 4) - which makes @normalize a no-op on conforming file-style definitions (idempotence pinned). Fields in a record's -unindentedfields are exempt. Implemented as a resolve pre-pass over split records (private::normalize_records / rebase_multiline_value); @normalize with options is an error. Intended for constructed/string-built definitions (no whole-block indent treatment otherwise); ::punk::helptopic::define_docs converts to it as the consumer proof (punk 0.2.5). New testsuite normalize.test; define doc documents the directive; rendering.test P4 notes stay pinned as the unopted default. #0.7.0 - G-045: record-continuation token -& - an unquoted trailing -& element on a definition record line continues the record on the next line. Implemented in private::split_definition_records: the token is dropped and the next line joins after a single space with its leading whitespace collapsed, exactly how the Tcl parser joins backslash-newline continuations before a braced definition reaches the splitter - so a -& record assembles byte-identical to its backslash-continued equivalent (proven by parse+render equality test). Motivation: constructed/string-built definitions cannot author backslash-newline ergonomically (the building code's own quoting consumes it); -& is plain text and survives any construction. Collision rules: the token must be a bare word preceded by whitespace (or the whole line), trailing whitespace after it is tolerated (more forgiving than raw backslash-newline); a braced/quoted -& is data ({-&} is the escape for a literal trailing value); -& mid-line, -& as a word suffix (abc-&), and -& on lines inside still-open braced/quoted values are all data. Backslash continuation authoring is unchanged (continuation is additive). New testsuite recordcontinuation.test; define doc documents the token alongside backslash continuation. #0.6.1 - G-045: @cmd honours -unindentedfields for -help - arg_error's display-time indent transform (undent " "+help, max 4) is now gated by "-help" membership in the @cmd line's -unindentedfields list (same gate argument -help already had), so left-margin-authored cmd help renders its first line flush with continuations in both the table and string renderers. Previously the option was accepted on @cmd but ignored (rendering.test rendering_unindentedfields_cmd_help_GAP - flipped to rendering_unindentedfields_cmd_help). No in-tree definitions set @cmd -unindentedfields, so existing rendering is unchanged. Note: @cmd -summary has no indent transform in any renderer, so -unindentedfields membership for -summary is accepted and vacuously honoured. define doc for -unindentedfields now states where the option is valid.