jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
752 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: ae72dffd91
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ae72dffd91'
${ noResults }
punkshell/goals/G-050-synopsis-validity-mar...

2.5 KiB
Raw Blame History

G-050 punk::ns::synopsis argument-validity marking and status-aware returns

Status: proposed Scope: src/modules/punk/ns-999999.0a1.0.tm (synopsis), src/modules/punk/args-999999.0a1.0.tm (synopsis renderer), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (synopsis pins) Acceptance: see GOALS.md index entry (canonical).

Context

'i <args...>' (cmdhelp) marks supplied argument words for validity; 's <args...>' (synopsis) does not - its output is identical whether the trailing words are valid, invalid or absent (pinned 2026-07-10: synopsis_GAP_no_argument_validity_marking). The user-facing intent is parity: the synopsis line(s) should show which supplied words validated (goodarg style) and where the first problem is (badarg style), with the same info/error scheme signalling as the usage table.

Separately, synopsis's handling of curried aliases is length-arithmetic based: the excess computation (ns-999999.0a1.0.tm, "This isn't quite right.. e.g see: s pse" REVIEW comment) counts args_remaining vs supplied words and lreplaces that many leading synopsis words with resolved_args. For a curried alias the substituted command renders as the braced alias target (e.g {::ns::realcmd curriedarg} ...) rather than the alias name (pinned: synopsis_curried_alias_shows_braced_target).

Approach

Consume the G-049 parse-status structure: parse the trailing words against the resolved definition (same docid resolution as cmdhelp via cmdinfo), then render the synopsis with per-word marking derived from the status, and expose the status in the dict return. Replacing the excess-args arithmetic with an actual parse against the resolved definition is the same change - the parse knows how many words the definition consumed and how the curried words map onto leaders.

Also worth addressing while in there: the existing in-source note that treating the synopsis line as a Tcl list for lreplace is risky with ANSI content ("todo - consider always using 'punk::args::synopsis -return dict' and operating on that list to rebuild string").

Notes

  • Depends on G-049 (status structure). G-044's hint display is a future consumer of the same API - keep the marking function reusable outside synopsis/cmdhelp rendering.
  • Existing string-shape tests: args testsuite synopsis.test and the installed test::punk::args synopsis tests ("must be no leading space" convention) - marking must be ANSI-only so ansistripped output stays stable, or those tests get a documented update.