---
name: tcl-nslist
description: "Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill."
---

# tcl-nslist

Namespace/package discovery for the punkshell repo - the "what is available?"
counterpart of tcl-whatis ("how do I call X?"). Asks the live interpreter via
punk::ns::get_ns_dicts - the same machinery behind the interactive n// / n///
namespace browsers - so it reports what is actually loaded, including
runtime-generated commands, aliases and imports that grep cannot see, and
auto-loads the providing package when the namespace is not yet populated.

## Command

Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the
Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.

    punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? <nsglob>...

`lib:developer/nslist` is punkshell script-path shorthand for
`scriptlib/developer/nslist.tcl`.

- `<nsglob>` - namespace name or glob, qualified or not: `punk::ns` is listed
  as `::punk::ns::*`. If the namespace does not exist, `package require` of
  the name (then of successively shorter :: prefixes) is attempted first.
  Last-segment glob chars filter members (`punk::ns::ns*`); glob chars in
  earlier segments match multiple namespaces (`::tcl::*::d*`); a trailing
  `::**` segment recurses through all descendant namespaces
  (`punk::nav::**`). Quote glob arguments in PowerShell.
  An ensemble command name (e.g `string`) is followed to its implementation
  namespace, with a note.
- `-synopsis` - append punk::args usage lines for every documented command in
  the namespace (a one-call API cheat-sheet; large for big namespaces).
- `-pathcommands` - also list the commands resolvable via each `namespace
  path` entry.

Exit codes: 0 every pattern listed something, 1 some pattern matched nothing,
2 usage error.

## Output fields

One block per matched namespace (blank-line separated); empty categories are
omitted:

    namespace:       ::punk::ns          fully-qualified namespace
    children:        argdoc lib ...      child namespace tails
    packagetails:    lib ...             children that are also loadable package names
    packageprefixes: ...                 children with deeper loadable packages below them
    commands:        147                 total member commands (count)
    procs:           ...                 script procs
    aliases:         ...                 interp aliases (may lack a same-named command)
    ensembles:       ...
    native:          ...                 C-implemented commands
    imported:        ...                 imported from another namespace
    other:           ...                 kinds not otherwise classified
    exported:        ...                 commands matching the namespace export patterns
    documented:      ...                 have punk::args docs - tcl-whatis gives full detail
    exportpatterns:  {[a-z]*}            raw namespace export patterns
    namespacepath:   ...                 extra namespaces this ns resolves commands from
    note:            ...                 autoload / ensemble-follow / empty-namespace notes
    synopsis:                            with -synopsis: usage line(s) per documented command

ooclasses/ooobjects/ooprivateclasses/ooprivateobjects/coroutines/interps/
zlibstreams lines appear when such commands exist. `packagetails` is the
discovery lever: a child listed there can be `package require`d and listed
itself.

## Caveats

- Keep the `src` launch argument: it loads and queries the working-tree
  modules under `src/modules`; without it the kit-stamped copies inside the
  executable answer instead.
- Load noise ("src mode: registered ...") goes to stderr; read stdout only
  (append `2>/dev/null` in bash, `2>$null` in PowerShell).
- Prefer the Bash tool over the PowerShell tool for these invocations:
  PowerShell-tool children get an attached console, which can flip punkshell's
  colour/terminal detection and change output classification.
- Only what is loaded in that session is reported. The script auto-requires
  the queried package, but a namespace can be populated further by other
  packages (e.g plugins) - an unexpectedly sparse listing may mean a related
  package is not loaded, not that the commands do not exist.
- `documented:` lists commands with registered punk::args definitions;
  undocumented commands are still real - tcl-whatis reports their proc
  signature and `-body` even without an argdoc.
- From Tcl code, the same data is available structurally:
  `punk::ns::get_ns_dicts ::the::ns::* ?-allbelow <bool>? ?-nspathcommands <bool>?`
  returns a list of dicts (keys documented - see
  `punk91 src script lib:developer/whatis -doc punk::ns::get_ns_dicts`),
  and `punk::ns::nslist_dict` accepts caller-relative globs. In an interactive
  punkshell the `n//` / `n///` aliases render the same information.