punkshell/src/modules/test/punk/#modpod-lib-999999.0a1.0/lib-999999.0a1.0.tm

# -*- tcl -*-
# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake  to update from <pkg>-buildversion.txt
# module template: shellspy/src/decktemplates/vendor/punk/modules/template_module-0.0.3.tm
#
# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# (C) 2025
#
# @@ Meta Begin
# Application test::punk::lib 999999.0a1.0
# Meta platform     tcl
# Meta license      MIT
# @@ Meta End

package require Tcl 8.6-

tcl::namespace::eval test::punk::lib {
    variable PUNKARGS
    variable pkg test::punk::lib
    variable version
    set version 999999.0a1.0

    package require packagetest
    packagetest::makeAPI test::punk::lib $version punk::lib; #will package provide test::punk::lib $version
    package forget punk::lib
    package require punk::lib
}


# == === === === === === === === === === === === === === ===
# Sample 'about' function with punk::args documentation
# == === === === === === === === === === === === === === ===
tcl::namespace::eval test::punk::lib {
    tcl::namespace::export {[a-z]*}  ;# Convention: export all lowercase
    variable PUNKARGS
    variable PUNKARGS_aliases

    lappend PUNKARGS [list {
            @id     -id "(package)test::punk::lib"
            @package    -name "test::punk::lib" -help\
            "Test suites for punk::lib module"
        }]

    namespace eval argdoc {
        #namespace for custom argument documentation
        proc package_name {} {
            return test::punk::lib
        }
        proc about_topics {} {
            #info commands results are returned in an arbitrary order (like array keys)
            set topic_funs [info commands [namespace current]::get_topic_*]
            set about_topics [list]
            foreach f $topic_funs {
                set tail [namespace tail $f]
                lappend about_topics [string range $tail [string length get_topic_] end] 
            }
            #Adjust this function or 'default_topics' if a different order is required
            return [lsort $about_topics]
        }
        proc default_topics {} {return [list Description *]}

        # -------------------------------------------------------------
        # get_topic_ functions add more to auto-include in about topics 
        # -------------------------------------------------------------
        proc get_topic_Description {} {
             punk::args::lib::tstr [string trim { 
                package test::punk::lib
                test suite for punk::lib
            } \n]
        }
        proc get_topic_License {} {
            return "MIT"
        }
        proc get_topic_Version {} {
            return "$::test::punk::lib::version"
        }
        proc get_topic_Contributors {} {
            set authors {{<julian@precisium.com> Julian Noble}}
            set contributors ""
            foreach a $authors {
                append contributors $a \n
            }
            if {[string index $contributors end] eq "\n"} {
                set contributors [string range $contributors 0 end-1]
            }
            return $contributors
        }
        proc get_topic_custom-topic {} {
            punk::args::lib::tstr -return string {
                A custom
                   topic
                      etc
            }
        }
        # -------------------------------------------------------------
    }

    # we re-use the argument definition from punk::args::standard_about and override some items
    set overrides [dict create]
    dict set overrides @id  -id   "::test::punk::lib::about"
    dict set overrides @cmd -name "test::punk::lib::about"
    dict set overrides @cmd -help [string trim [punk::args::lib::tstr {
                            About test::punk::lib
                            }] \n]
    dict set overrides topic -choices           [list {*}[test::punk::lib::argdoc::about_topics] *]
    dict set overrides topic -choicerestricted  1
    dict set overrides topic -default [test::punk::lib::argdoc::default_topics] ;#if -default is present 'topic' will always appear in parsed 'values' dict
    set newdef [punk::args::resolved_def -antiglobs -package_about_namespace -override $overrides ::punk::args::package::standard_about *]
    lappend PUNKARGS [list $newdef]
    proc about {args} {
        package require punk::args
        #standard_about accepts additional choices for topic - but we need to normalize any abbreviations to full topic name before passing on
        set argd [punk::args::parse $args withid ::test::punk::lib::about]
        lassign [dict values $argd] _leaders opts values _received
        punk::args::package::standard_about -package_about_namespace ::test::punk::lib::argdoc {*}$opts {*}[dict get $values topic]
    }
}
# end of sample 'about' function
# == === === === === === === === === === === === === === ===

# -----------------------------------------------------------------------------
#    register namespace(s) to have PUNKARGS,PUNKARGS_aliases variables checked
# -----------------------------------------------------------------------------
#    variable PUNKARGS
#    variable PUNKARGS_aliases
namespace eval ::punk::args::register {
    #use fully qualified so 8.6 doesn't find existing var in global namespace
    lappend ::punk::args::register::NAMESPACES ::test::punk::lib
}
# -----------------------------------------------------------------------------

package provide test::punk::lib [tcl::namespace::eval test::punk::lib {
    variable pkg test::punk::lib
    variable version
    set version 999999.0a1.0
}]
##  Ready
return