# src/modules — Main Editable Module Source ## Purpose Source of truth for all editable Punk project modules. This is where agents should make generic module source edits. Each `.tm` file is a Tcl module belonging to a named package. ## Ownership - Agents should edit files here as the primary development area for generic modules. - The top-level modules (non-punk namespace) include shellfilter, shellrun, overtype, textblock, patternpunk, and related packages. - The `punk/` subdirectory holds all `punk::*` namespace modules. - Tcl-major-specific sibling trees under `src/modules_tcl8/` and `src/modules_tcl9/` mirror these module conventions where applicable, but their local AGENTS.md files control source selection for version-specific behavior. ## Local Contracts - Module filenames use the literal suffix `-999999.0a1.0.tm`. - Corresponding `-buildversion.txt` files hold the real version number. - The exception is `punk::libunknown`, which uses its own version `0.1`. - `#modpod-*` directories contain internal files packed into `.tm` archives during build; do not flatten or edit them without understanding the modpod format. - `_build/` directory holds build intermediates and should not be manually edited. - Always declare dependencies explicitly using `package require ` near file tops. - Prefer fully qualified namespaces when referencing external packages, such as `package require tcl::zlib` or `package require TclOO`. - Organize custom modules as namespaces mirroring directory structure, such as `namespace eval punk::` or deeper paths like `punk::lib::util::`. - Use semantic versions that `package vcompare` can interpret; strip leading zeros according to tcl package version rules ie in each segment including either side of a or b. - For optional features, probe with `if {[catch {package require foo}]} { ... }` and degrade gracefully. - Vendormodules, bootsupport snapshots, VFS modules, and built output modules do not use the magic version scheme unless their own local docs explicitly say otherwise. ### Module Subsystems - Terminal/display modules include `punk::ansi` for ANSI codes, cp437, and Sixel support; `punk::console`; `textblock` for text composition and framing; and `overtype` for text overlay. - Shell modules include `punk::repl`, `punk::shellrun` for `run`/`runout`/`runerr`/`runx`, and `punk::nav::ns` for namespace browsing. - Functional and pattern modules include `pattern` and `patterncmd`; treat them as experimental and use them only with user instruction or confirmation. - Argument handling uses `punk::args` for processing, validation, and documentation generation; prefer it for public APIs and user-facing utilities unless the code path is performance critical. - Networking modules include `punk::imap4`, `punk::netbox`, `punk::basictelnet`, and `punk::net::vxlan`. - Plugin and capability provider/handler support uses `punk::cap`. ## Work Guidance - Treat `src/modules/` as the source of truth for generic editable Punk modules. - Expect the literal suffix `-999999.0a1.0.tm` and do not shorten or normalize it. - Prefer Unix-style LF line endings for `.tm` source files in this tree. - If the same proc exists in both `src/modules/` and `src/modules_tcl/`, prefer `src/modules/` unless version-specific behavior is relevant or only the version-specific file is active. - Use `deck module.new ` or `punk::mix::commandset::module::new` to scaffold new modules. - Run `tclsh src/make.tcl modules` to build modules, or `tclsh src/make.tcl project` for a full build. ### Formatting And Layout - Opening braces stay on the same line for procs. - Multiline control structures may span lines for readability if Tcl syntax allows without line-continuation backslashes, such as braced `expr` contents or `if` expressions. - Line-continuation backslashes should only be used in documentation blocks for `punk::args`, such as `punk::args::define` arguments or `lappend PUNKARGS` elements. - Proc bodies should not use line-continuation backslashes because they make debug line-number matching harder; use Tcl expand syntax where practical. - For test-specific continuation rules, use `src/tests/AGENTS.md`. - Keep pipelines readable by aligning `% var = ...` and `pipecase` segments when practical. - Keep inline comments concise and describe intent, not mechanics. - Document non-trivial procedures and exports with the standard `argdoc`/`PUNKARGS` template below. Example expand-style dictionary literal: ```tcl dict create {*}{ a A b B c C } ``` Example expand-style dictionary literal with substituted values: ```tcl dict create {*}{ } a A b B c C {*}{ } d $DVAL {*}{ } ``` ### Naming Conventions - Procedures: `lowercase_with_underscores` for internals; `camelCase` is allowed for public APIs where existing patterns fit. - Variables: `lowercase_with_underscores`; avoid single-letter names except for loop indices. - Namespaces: mirror directory structure; nested modules should reflect filesystem hierarchy. - Private helpers: prefix with `_`, such as `_resolve_stream`; do not export them. - Constants: `UPPER_CASE_WITH_UNDERSCORES` declared through `namespace eval { variable CONSTANT value }` when practical. - Keep `namespace export` lists alphabetized for clarity. ### Procedure Documentation Template Guide ```tcl #- comments such as this with a leading dash are descriptions for the agent of how-to/what-to to implement #- whereas comments without the dash are either literal comments, or if angle-bracketed, descriptions of what to put in the comment. namespace eval argdoc { lappend PUNKARGS [list { @id -id ::full::namespace::path::procedure_name @cmd -name "full::namespace::path::procedure_name"\ -summary\ "Short single line procedure description"\ -help\ "Procedure summary without too much overlap with documented arguments below. Existing - include description of return value" @leaders arg1 -type any -optional 0 -multiple 0 -help\ "description of mandatory leading argument arg1" @opts -force -type boolean -flag1 -type none -help\ "description of non-argument accepting flag -flag1" -- -type none -help\ "End of opts marker" @values -min 1 -max -1 arg2 -type list -optional 0 -help\ {Description of mandatory arg arg2 possibly spanning multiple lines, but each line should generally be wrapped manually to keep sensibly short for terminal display. Help blocks may be wrapped in curly braces or double quotes. See the punk::args module for details of acceptable structure. } glob -type string -optional 1 -multiple 1 -help\ "Description of optional argument glob which can be repeated. Indenting of argument -help contents should follow this example. Note that we indent subsequent lines by 2 additional spaces, whereas the @cmd -help does no such indenting. This provides a more presentable display when calling `i procedure_name`." }] } proc procedure_name {args} { # #- agent: these comments are not literal contents of the proc - they are to be read as a guide. #- argument parsing implementation: #- If not highly performance sensitive use punk::args to parse, #- make use of `punk::args::parse $args withid ::full::namespace::path::procedurename` #- namespace eval ::punk::args::register { #- #use fully qualified so 8.6 doesn't find existing var in global namespace #- lappend ::punk::args::register::NAMESPACES ::punk::ansi ::punk::ansi::ansistring ::punk::ansi::colour ::punk::ansi::argdoc #- } #- If performance sensitive or not part of a broad-concept of 'API' for the module and useful utilities, #- use fast `switch` based code to parse the arguments. #- procedure functionality implementation } ``` Update the template with concrete details whenever functions are user-facing or complex. ### Error Handling And Logging - Prefer `try { ... } on error {result options} { ... }` for structured Tcl 8.6+ error handling. - Fallback pattern: ```tcl if {[catch {some_command} result]} { puts stderr "Error: $result" return -code error $result } ``` - For Punk pipelines, wrap risky commands inside `pipecase` blocks and emit descriptive messages via `puts stderr` or Punk logging helpers. - Never swallow errors silently; propagate with context so shell users see actionable details. ### Pipeline And Functional Style Notes - Punk Pipeline functionality is experimental and should usually be avoided in agent-generated code unless the user specifically requests it. - Pipeline syntax includes forms such as `var.= command1 |> command2 |> command3`. - Pattern-match assignment syntax includes forms such as `x@0,y@1,z@2.= list a b c`, where `@` targets an index and `/` is range-safe. - Destructuring examples include `x@end/@@k1.= list {k1 aaa} {k1 bb}`. - `.=` means following args form a command; `=` accepts a single value. - Use `% var = ...` bindings to capture intermediate values; keep names meaningful. - `pipecase` should list specific patterns before catch-alls to avoid hidden matches. - `fun name pattern { ... }` definitions should remain side-effect light; treat them as pure functions unless otherwise documented. - Keep pipelines short and composable; extract helper procs or `fun` definitions when they exceed about 10 logical steps. ### Module Structure Expectations ```tcl # package require #- comments such as this with a leading dash are descriptions for the agent of how-to/what-to to implement #- whereas comments without the dash are either literal comments, or if angle-bracketed, descriptions of what to put in the comment. namespace eval { variable version namespace export public_proc1 public_proc2 namespace eval argdoc { lappend PUNKARGS [list { @id -id ::public_proc1 ... elided ... #- punk::args textblock similar to example given in Procedure Documentation Template #- This should exist immediately prior to each proc (or at least very close), #- even if it is only being used for documentation and not for parsing. #- If the public_proc1 proc does not use the PUNKARGS definition for parsing, then the parsing within the proc #- and the punk::args definitions of proc args and behaviour must be kept synchronized. }] } proc public_proc1 {args} { #- argument parsing code, using `punk::args::parse` if part of API and not performance critical #- if argument parsing is done in code here, the behaviour must match the arguments as defined in the PUNKARGS list created above. #- Implementation } namespace eval argdoc { lappend PUNKARGS [list { @id -id ::some_other_public_proc ... elided ... }] } proc some_other_public_proc {args} { ... elided ... } namespace eval private { # #- use of same PUNKARGS mechanism within a further nested argdoc namespace is recommended for clarity #- even within private namespaces. #- Generally privately namespaced procs will use the PUNKARGS for documentation only, #- unless there is no concern about the usually slight overhead of punk::args::parse. proc private_helper {arg1 arg2} { #- Private implementation } proc private_helper2 {args} { #- argument parsing code, using `switch`, `regexp`, etc if needed. #- Private implementation } } namespace eval utils { # #- other appropriately named sub namespaces such as 'utils' or 'lib' can be used to structure the codebase. #- If these form part of what can reasonably be considered the API of the module, they should #- be documented using the punk::args mechanism described above. #- more procs } } namespace eval ::punk::args::register { #use fully qualified so 8.6 doesn't find existing var in global namespace lappend ::punk::args::register::NAMESPACES ::utils } ## Ready package provide [tcl::namespace::eval { variable version #- this version number, exactly 999999.0a1.0, is a literal used in src module folders #- we refer to this sometimes as the magic version number set version 999999.0a1.0 }] return ``` ### Type And Data Handling - Tcl is dynamically typed; emulate structural typing through argument validation at proc boundaries. - Validate user inputs with `punk::args::parse`, `switch -exact`, `regexp`, or Punk pipeline predicates before mutation. - Use dictionaries for structured data, or parallel lists if it is likely to be a performance win. - Tcl arrays can be used, but limit them to simple flat structures or cases where they are specifically warranted. - When bridging to binary data, such as ANSI/xbin parsing, document expected encodings and conversions. ### Versioning And Releases - Stick to semantic versioning: `major.minor.patch`. - Use the magic version `999999.0a1.0` for source modules and add or update the actual version number in the associated `-buildversion.txt` file. - Update the `-buildversion.txt` file when API changes are made. - There may be occasional exceptions such as `punk::libunknown-0.1.tm`, which is deliberately manually versioned; new modules should use the magic version mechanism. - Modules with the magic version number must not appear in output paths such as `/modules`. - When referencing ranges, use bounded specs such as `1.2.3-2.0.0`. - Convert loose versions to bounded form in module metadata; helper utilities exist in boot modules for this purpose. - Update `punk::libunknown` registries whenever adding or removing modules to keep discovery accurate. ### Documentation And Comments - Primary documentation for procs should use the `punk::args` system, preferably within an `argdoc` sub-namespace using `lappend PUNKARGS `. - If a public proc parses arguments manually, keep the implementation behavior synchronized with its PUNKARGS definition. - Update relevant docs or usage notes when behavior changes. - Mention environment variables or flags required to run new features. ## Verification - VS Code Tcl lint diagnostics are clean for modified `.tm` files when available. - `tclsh src/make.tcl modules` completes without errors for module changes. - Module tests pass: `tclsh src/tests/modules//tests/all.tcl`. ## Child DOX Index - `punk/` — Core punk namespace modules (see punk/AGENTS.md) - `opunk/` — Alternative punk namespace (opunk::str) - `punkcheck/` — Build/check system (punkcheck + punkcheck::cli) - `test/` — Installed-module test packages (see test/AGENTS.md)