diff --git a/src/decktemplates/custom/_project/modules/template_anyname-0.0.2.tm b/src/decktemplates/custom/_project/modules/template_anyname-0.0.2.tm new file mode 100644 index 00000000..4bca651b --- /dev/null +++ b/src/decktemplates/custom/_project/modules/template_anyname-0.0.2.tm @@ -0,0 +1,51 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) 2023 +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +apply {code { #auto determine package name and version from name and placement of .tm file + foreach base [tcl::tm::list] { + set nsprefix "";#in case sourced directly and not in any of the .tm paths + if {[string match -nocase ${base}* [info script]]} { + set nsprefix [string trimleft [join [lrange [file split [string range [info script] [string length $base]+1 end]] 0 end-1] ::]:: ::] + break + } + } + set ver [join [lassign [split [file rootname [file tail [info script] ]] -] pkgtail] -] + set pkgns ${nsprefix}${pkgtail} + namespace eval $pkgns [string map [list $pkgns $ver] $code] + package provide $pkgns $ver;# only provide package if code evaluated without error +} ::} { + #-------------------------------------- + variable pkg "" + variable version "" + #-------------------------------------- + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Requirements + ##e.g package require frobz + + + #proc test {args} {puts "[namespace current]::test got args: $args"} + + + + namespace eval [namespace current]::lib { + #proc test {args} {puts "[namespace current]::test got args: $args"} + } + + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Ready +} +return + diff --git a/src/decktemplates/custom/punk/modules/template_cli-0.0.1.tm b/src/decktemplates/custom/punk/modules/template_cli-0.0.1.tm new file mode 100644 index 00000000..52d25a43 --- /dev/null +++ b/src/decktemplates/custom/punk/modules/template_cli-0.0.1.tm @@ -0,0 +1,107 @@ +# -*- tcl -*- +# punk template_cli overridden - custom +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) %year% +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license %license% +# @@ Meta End + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# doctools header +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[manpage_begin %project%_cli-module_%pkg% 0 999999.0a1.0] +#[copyright "%year%"] +#[titledesc {Command Line Interface Module}] [comment {-- Name section and table of contents description --}] +#[moddesc {-}] [comment {-- Description at end of page heading --}] +#[require %pkg%] +#[description] +#[para] - + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section Overview] +#[para] overview of %pkg% +#[subsection Concepts] +#[para] - + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Requirements +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[subsection dependencies] +#[para] packages used by %pkg% +#[list_begin itemized] + +package require Tcl 8.6 +package require punk::overlay +package require punk::mix::base +package require punk::mix::util +#*** !doctools +#[item] [package {Tcl 8.6}] +#[item] [package {punk::overlay}] +#[item] [package {punk::mix::base}] +#[item] [package {punk::mix::util}] + +# #package require frobz +# #*** !doctools +# #[item] [package {frobz}] + +#*** !doctools +#[list_end] + +namespace eval %pkg% { + namespace ensemble create + #package require punk::overlay + #punk::overlay::import_commandset debug . ::punk:mix::commandset::debug + + + proc help {args} { + set basehelp [punk::mix::base help {*}$args] + return $basehelp + } + + + + +} + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::lib { + namespace path ::punk::mix::util ;#askuser, do_in_path, foreach-file etc + +} + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg% { + proc _cli {args} { + #don't use tailcall - base uses info level to determine caller + ::punk::mix::base::_cli {*}$args + } + variable default_command help + punk::overlay::custom_from_base [namespace current] ::punk::mix::base +} + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Ready +package provide %pkg% [namespace eval %pkg% { + variable version + set version 999999.0a1.0 +}] +return + + diff --git a/src/decktemplates/vendor/_project/modules/template_anyname-0.0.2.tm b/src/decktemplates/vendor/_project/modules/template_anyname-0.0.2.tm new file mode 100644 index 00000000..4bca651b --- /dev/null +++ b/src/decktemplates/vendor/_project/modules/template_anyname-0.0.2.tm @@ -0,0 +1,51 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) 2023 +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +apply {code { #auto determine package name and version from name and placement of .tm file + foreach base [tcl::tm::list] { + set nsprefix "";#in case sourced directly and not in any of the .tm paths + if {[string match -nocase ${base}* [info script]]} { + set nsprefix [string trimleft [join [lrange [file split [string range [info script] [string length $base]+1 end]] 0 end-1] ::]:: ::] + break + } + } + set ver [join [lassign [split [file rootname [file tail [info script] ]] -] pkgtail] -] + set pkgns ${nsprefix}${pkgtail} + namespace eval $pkgns [string map [list $pkgns $ver] $code] + package provide $pkgns $ver;# only provide package if code evaluated without error +} ::} { + #-------------------------------------- + variable pkg "" + variable version "" + #-------------------------------------- + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Requirements + ##e.g package require frobz + + + #proc test {args} {puts "[namespace current]::test got args: $args"} + + + + namespace eval [namespace current]::lib { + #proc test {args} {puts "[namespace current]::test got args: $args"} + } + + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Ready +} +return + diff --git a/src/decktemplates/vendor/punk/modules/modulename_buildversion.txt b/src/decktemplates/vendor/punk/modules/modulename_buildversion.txt new file mode 100644 index 00000000..53815fbd --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/modulename_buildversion.txt @@ -0,0 +1,3 @@ +%Major.Minor.Level% +#First line must be a semantic version number +#all other lines are ignored. diff --git a/src/decktemplates/vendor/punk/modules/modulename_description.txt b/src/decktemplates/vendor/punk/modules/modulename_description.txt new file mode 100644 index 00000000..ddb209af --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/modulename_description.txt @@ -0,0 +1,10 @@ +Identifier: %package% +Version: %version% +Title: %title% +Creator: %name% <%email%> +Description: %description% +Rights: BSD +URL: %url% +Available: +Architecture: tcl +Subject: diff --git a/src/decktemplates/vendor/punk/modules/nodoc/template_anyname-0.0.2.tm b/src/decktemplates/vendor/punk/modules/nodoc/template_anyname-0.0.2.tm new file mode 100644 index 00000000..4bca651b --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/nodoc/template_anyname-0.0.2.tm @@ -0,0 +1,51 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) 2023 +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +apply {code { #auto determine package name and version from name and placement of .tm file + foreach base [tcl::tm::list] { + set nsprefix "";#in case sourced directly and not in any of the .tm paths + if {[string match -nocase ${base}* [info script]]} { + set nsprefix [string trimleft [join [lrange [file split [string range [info script] [string length $base]+1 end]] 0 end-1] ::]:: ::] + break + } + } + set ver [join [lassign [split [file rootname [file tail [info script] ]] -] pkgtail] -] + set pkgns ${nsprefix}${pkgtail} + namespace eval $pkgns [string map [list $pkgns $ver] $code] + package provide $pkgns $ver;# only provide package if code evaluated without error +} ::} { + #-------------------------------------- + variable pkg "" + variable version "" + #-------------------------------------- + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Requirements + ##e.g package require frobz + + + #proc test {args} {puts "[namespace current]::test got args: $args"} + + + + namespace eval [namespace current]::lib { + #proc test {args} {puts "[namespace current]::test got args: $args"} + } + + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Ready +} +return + diff --git a/src/decktemplates/vendor/punk/modules/template_anyname-0.0.2.tm b/src/decktemplates/vendor/punk/modules/template_anyname-0.0.2.tm new file mode 100644 index 00000000..4bca651b --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/template_anyname-0.0.2.tm @@ -0,0 +1,51 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) 2023 +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +apply {code { #auto determine package name and version from name and placement of .tm file + foreach base [tcl::tm::list] { + set nsprefix "";#in case sourced directly and not in any of the .tm paths + if {[string match -nocase ${base}* [info script]]} { + set nsprefix [string trimleft [join [lrange [file split [string range [info script] [string length $base]+1 end]] 0 end-1] ::]:: ::] + break + } + } + set ver [join [lassign [split [file rootname [file tail [info script] ]] -] pkgtail] -] + set pkgns ${nsprefix}${pkgtail} + namespace eval $pkgns [string map [list $pkgns $ver] $code] + package provide $pkgns $ver;# only provide package if code evaluated without error +} ::} { + #-------------------------------------- + variable pkg "" + variable version "" + #-------------------------------------- + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Requirements + ##e.g package require frobz + + + #proc test {args} {puts "[namespace current]::test got args: $args"} + + + + namespace eval [namespace current]::lib { + #proc test {args} {puts "[namespace current]::test got args: $args"} + } + + # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + ## Ready +} +return + diff --git a/src/decktemplates/vendor/punk/modules/template_cli-0.0.1.tm b/src/decktemplates/vendor/punk/modules/template_cli-0.0.1.tm new file mode 100644 index 00000000..4c2fad08 --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/template_cli-0.0.1.tm @@ -0,0 +1,106 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) %year% +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license %license% +# @@ Meta End + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# doctools header +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[manpage_begin %project%_cli-module_%pkg% 0 999999.0a1.0] +#[copyright "%year%"] +#[titledesc {Command Line Interface Module}] [comment {-- Name section and table of contents description --}] +#[moddesc {-}] [comment {-- Description at end of page heading --}] +#[require %pkg%] +#[description] +#[para] - + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section Overview] +#[para] overview of %pkg% +#[subsection Concepts] +#[para] - + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Requirements +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[subsection dependencies] +#[para] packages used by %pkg% +#[list_begin itemized] + +package require Tcl 8.6 +package require punk::overlay +package require punk::mix::base +package require punk::mix::util +#*** !doctools +#[item] [package {Tcl 8.6}] +#[item] [package {punk::overlay}] +#[item] [package {punk::mix::base}] +#[item] [package {punk::mix::util}] + +# #package require frobz +# #*** !doctools +# #[item] [package {frobz}] + +#*** !doctools +#[list_end] + +namespace eval %pkg% { + namespace ensemble create + #package require punk::overlay + #punk::overlay::import_commandset debug . ::punk:mix::commandset::debug + + + proc help {args} { + set basehelp [punk::mix::base help {*}$args] + return $basehelp + } + + + + +} + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::lib { + namespace path ::punk::mix::util ;#askuser, do_in_path, foreach-file etc + +} + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg% { + proc _cli {args} { + #don't use tailcall - base uses info level to determine caller + ::punk::mix::base::_cli {*}$args + } + variable default_command help + punk::overlay::custom_from_base [namespace current] ::punk::mix::base +} + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Ready +package provide %pkg% [namespace eval %pkg% { + variable version + set version 999999.0a1.0 +}] +return + + diff --git a/src/decktemplates/vendor/punk/modules/template_module-0.0.1.tm b/src/decktemplates/vendor/punk/modules/template_module-0.0.1.tm new file mode 100644 index 00000000..3e44c9ff --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/template_module-0.0.1.tm @@ -0,0 +1,175 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt +# +# 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) %year% +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license %license% +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# doctools header +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[manpage_begin %project%_module_%pkg% 0 999999.0a1.0] +#[copyright "%year%"] +#[titledesc {Module API}] [comment {-- Name section and table of contents description --}] +#[moddesc {-}] [comment {-- Description at end of page heading --}] +#[require %pkg%] +#[keywords module] +#[description] +#[para] - + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section Overview] +#[para] overview of %pkg% +#[subsection Concepts] +#[para] - + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Requirements +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[subsection dependencies] +#[para] packages used by %pkg% +#[list_begin itemized] + +package require Tcl 8.6 +#*** !doctools +#[item] [package {Tcl 8.6}] + +# #package require frobz +# #*** !doctools +# #[item] [package {frobz}] + +#*** !doctools +#[list_end] + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section API] + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# oo::class namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::class { + #*** !doctools + #[subsection {Namespace %pkg%::class}] + #[para] class definitions + if {[info commands [namespace current]::interface_sample1] eq ""} { + #*** !doctools + #[list_begin enumerated] + + # oo::class create interface_sample1 { + # #*** !doctools + # #[enum] CLASS [class interface_sample1] + # #[list_begin definitions] + + # method test {arg1} { + # #*** !doctools + # #[call class::interface_sample1 [method test] [arg arg1]] + # #[para] test method + # puts "test: $arg1" + # } + + # #*** !doctools + # #[list_end] [comment {-- end definitions interface_sample1}] + # } + + #*** !doctools + #[list_end] [comment {--- end class enumeration ---}] + } +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# Base namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg% { + namespace export * + #variable xyz + + #*** !doctools + #[subsection {Namespace %pkg%}] + #[para] Core API functions for %pkg% + #[list_begin definitions] + + + + #proc sample1 {p1 args} { + # #*** !doctools + # #[call [fun sample1] [arg p1] [opt {?option value...?}]] + # #[para]Description of sample1 + # return "ok" + #} + + + + + #*** !doctools + #[list_end] [comment {--- end definitions namespace %pkg% ---}] +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# Secondary API namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::lib { + namespace export * + namespace path [namespace parent] + #*** !doctools + #[subsection {Namespace %pkg%::lib}] + #[para] Secondary functions that are part of the API + #[list_begin definitions] + + #proc utility1 {p1 args} { + # #*** !doctools + # #[call lib::[fun utility1] [arg p1] [opt {?option value...?}]] + # #[para]Description of utility1 + # return 1 + #} + + + + #*** !doctools + #[list_end] [comment {--- end definitions namespace %pkg%::lib ---}] +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[section Internal] +namespace eval %pkg%::system { + #*** !doctools + #[subsection {Namespace %pkg%::system}] + #[para] Internal functions that are not part of the API + + + +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Ready +package provide %pkg% [namespace eval %pkg% { + variable pkg %pkg% + variable version + set version 999999.0a1.0 +}] +return + +#*** !doctools +#[manpage_end] + diff --git a/src/decktemplates/vendor/punk/modules/template_module-0.0.2.tm b/src/decktemplates/vendor/punk/modules/template_module-0.0.2.tm new file mode 100644 index 00000000..bde17848 --- /dev/null +++ b/src/decktemplates/vendor/punk/modules/template_module-0.0.2.tm @@ -0,0 +1,176 @@ +# -*- tcl -*- +# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'pmix make' or bin/punkmake to update from -buildversion.txt +# module template: %moduletemplate% +# +# 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) %year% +# +# @@ Meta Begin +# Application %pkg% 999999.0a1.0 +# Meta platform tcl +# Meta license %license% +# @@ Meta End + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# doctools header +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[manpage_begin %project%_module_%pkg% 0 999999.0a1.0] +#[copyright "%year%"] +#[titledesc {Module API}] [comment {-- Name section and table of contents description --}] +#[moddesc {-}] [comment {-- Description at end of page heading --}] +#[require %pkg%] +#[keywords module] +#[description] +#[para] - + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section Overview] +#[para] overview of %pkg% +#[subsection Concepts] +#[para] - + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Requirements +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[subsection dependencies] +#[para] packages used by %pkg% +#[list_begin itemized] + +package require Tcl 8.6 +#*** !doctools +#[item] [package {Tcl 8.6}] + +# #package require frobz +# #*** !doctools +# #[item] [package {frobz}] + +#*** !doctools +#[list_end] + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +#*** !doctools +#[section API] + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# oo::class namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::class { + #*** !doctools + #[subsection {Namespace %pkg%::class}] + #[para] class definitions + if {[info commands [namespace current]::interface_sample1] eq ""} { + #*** !doctools + #[list_begin enumerated] + + # oo::class create interface_sample1 { + # #*** !doctools + # #[enum] CLASS [class interface_sample1] + # #[list_begin definitions] + + # method test {arg1} { + # #*** !doctools + # #[call class::interface_sample1 [method test] [arg arg1]] + # #[para] test method + # puts "test: $arg1" + # } + + # #*** !doctools + # #[list_end] [comment {-- end definitions interface_sample1}] + # } + + #*** !doctools + #[list_end] [comment {--- end class enumeration ---}] + } +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# Base namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg% { + namespace export * + #variable xyz + + #*** !doctools + #[subsection {Namespace %pkg%}] + #[para] Core API functions for %pkg% + #[list_begin definitions] + + + + #proc sample1 {p1 args} { + # #*** !doctools + # #[call [fun sample1] [arg p1] [opt {option value...}]] + # #[para]Description of sample1 + # return "ok" + #} + + + + + #*** !doctools + #[list_end] [comment {--- end definitions namespace %pkg% ---}] +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +# Secondary API namespace +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg%::lib { + namespace export * + namespace path [namespace parent] + #*** !doctools + #[subsection {Namespace %pkg%::lib}] + #[para] Secondary functions that are part of the API + #[list_begin definitions] + + #proc utility1 {p1 args} { + # #*** !doctools + # #[call lib::[fun utility1] [arg p1] [opt {?option value...?}]] + # #[para]Description of utility1 + # return 1 + #} + + + + #*** !doctools + #[list_end] [comment {--- end definitions namespace %pkg%::lib ---}] +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +#*** !doctools +#[section Internal] +namespace eval %pkg%::system { + #*** !doctools + #[subsection {Namespace %pkg%::system}] + #[para] Internal functions that are not part of the API + + + +} +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Ready +package provide %pkg% [namespace eval %pkg% { + variable pkg %pkg% + variable version + set version 999999.0a1.0 +}] +return + +#*** !doctools +#[manpage_end] + diff --git a/src/mixtemplates/modules/template_unversioned.tm b/src/decktemplates/vendor/punk/modules/template_module_unversioned.tm similarity index 100% rename from src/mixtemplates/modules/template_unversioned.tm rename to src/decktemplates/vendor/punk/modules/template_module_unversioned.tm diff --git a/src/mixtemplates/modules/template_module-0.0.1.tm b/src/decktemplates/vendor/punk/modules/template_moduleexactversion-0.0.1.tm similarity index 75% rename from src/mixtemplates/modules/template_module-0.0.1.tm rename to src/decktemplates/vendor/punk/modules/template_moduleexactversion-0.0.1.tm index f6b9cbd7..30043317 100644 --- a/src/mixtemplates/modules/template_module-0.0.1.tm +++ b/src/decktemplates/vendor/punk/modules/template_moduleexactversion-0.0.1.tm @@ -1,52 +1,45 @@ -# -*- tcl -*- -# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from -buildversion.txt -# -# 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) %year% -# -# @@ Meta Begin -# Application %pkg% 999999.0a1.0 -# Meta platform tcl -# Meta license %license% -# @@ Meta End - - - -# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ -## Requirements -##e.g package require frobz - - - - -# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ -namespace eval %pkg% { - - - - -} - - - - - - - - - - - - - - -# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ -## Ready -package provide %pkg% [namespace eval %pkg% { - variable pkg %pkg% - variable version - set version 999999.0a1.0 -}] +# -*- tcl -*- +# +# 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) %year% +# +# @@ Meta Begin +# Application %pkg% %version% +# Meta platform tcl +# Meta license %license% +# @@ Meta End + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Requirements +##e.g package require frobz + + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +namespace eval %pkg% { + + + + +} + + + + + + + + + +# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +## Ready +package provide %pkg% [namespace eval %pkg% { + variable version + set version %version% +}] return \ No newline at end of file diff --git a/src/modules/punk/mix/templates/utility/scriptappwrappers/punk-shellbat.bat b/src/decktemplates/vendor/punk/utility/scriptappwrappers/basic/shellbat.bat similarity index 100% rename from src/modules/punk/mix/templates/utility/scriptappwrappers/punk-shellbat.bat rename to src/decktemplates/vendor/punk/utility/scriptappwrappers/basic/shellbat.bat diff --git a/src/embedded/man/files/punk/_module_ansi-0.1.0.tm.n b/src/embedded/man/files/punk/_module_ansi-0.1.0.tm.n new file mode 100644 index 00000000..e5242133 --- /dev/null +++ b/src/embedded/man/files/punk/_module_ansi-0.1.0.tm.n @@ -0,0 +1,560 @@ +'\" +'\" Generated from file '_module_ansi-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2023 +'\" +.TH "punkshell_module_punk::ansi" 0 0\&.1\&.0 doc "punk Ansi library" +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.BS +.SH NAME +punkshell_module_punk::ansi \- Ansi string functions +.SH SYNOPSIS +package require \fBpunk::ansi \fR +.sp +\fBstripansi\fR \fItext\fR +.sp +\fBa?\fR ?ansicode\&.\&.\&.? +.sp +\fBa+\fR ?ansicode\&.\&.\&.? +.sp +\fBa\fR ?ansicode\&.\&.\&.? +.sp +\fBget_code_name\fR \fIcode\fR +.sp +\fBreset\fR +.sp +\fBreset_soft\fR +.sp +\fBreset_colour\fR +.sp +\fBclear\fR +.sp +\fBclear_above\fR +.sp +\fBclear_below\fR +.sp +\fBcursor_on\fR +.sp +\fBcursor_off\fR +.sp +\fBmove\fR \fIrow\fR \fIcol\fR +.sp +\fBmove_emit\fR \fIrow\fR \fIcol\fR \fIdata\fR ?row col data\&.\&.\&.? +.sp +\fBmove_forward\fR \fIn\fR +.sp +\fBmove_back\fR \fIn\fR +.sp +\fBmove_up\fR \fIn\fR +.sp +\fBmove_down\fR \fIn\fR +.sp +\fBerase_line\fR +.sp +\fBerase_sol\fR +.sp +\fBerase_eol\fR +.sp +\fBcursor_pos\fR +.sp +\fBtitleset\fR \fIwindowtitles\fR +.sp +\fBdetect\fR \fItext\fR +.sp +\fBdetect_csi\fR \fItext\fR +.sp +\fBdetect_sgr\fR \fItext\fR +.sp +\fBstrip\fR \fItext\fR +.sp +\fBlength\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Ansi based terminal control string functions +.PP +See \fBpunk::ansi::console\fR for related functions for controlling a console +.SH OVERVIEW +.PP +overview of punk::ansi +.PP +punk::ansi functions return their values - no implicit emission to console/stdout +.SS CONCEPTS +.PP +Ansi codes can be used to control most terminals on most platforms in an 'almost' standard manner +.PP +There are many differences in terminal implementations - but most should support a core set of features +.PP +punk::ansi does not contain any code for direct terminal manipulation via the local system APIs\&. +.PP +Sticking to ansi codes where possible may be better for cross-platform and remote operation where such APIs are unlikely to be useable\&. +.SS DEPENDENCIES +.PP +packages used by punk::ansi +.IP \(bu +\fBTcl 8\&.6\fR +.PP +.SH API +.SS "NAMESPACE PUNK::ANSI" +.PP +Core API functions for punk::ansi +.TP +\fBstripansi\fR \fItext\fR +.sp +Return a string with ansi codes stripped out +.TP +\fBa?\fR ?ansicode\&.\&.\&.? +.sp +Return an ansi string representing a table of codes and a panel showing the colours +.TP +\fBa+\fR ?ansicode\&.\&.\&.? +.sp +Returns the ansi code to apply those from the supplied list - without any reset being performed first +.sp +e\&.g to set foreground red and bold +.sp +punk::ansi::a red bold +.sp +to set background red +.sp +punk::ansi::a Red +.sp +see \fBpunk::ansi::a?\fR to display a list of codes +.TP +\fBa\fR ?ansicode\&.\&.\&.? +.sp +Returns the ansi code to reset any current settings and apply those from the supplied list +.sp +by calling punk::ansi::a with no arguments - the result is a reset to plain text +.sp +e\&.g to set foreground red and bold +.sp +punk::ansi::a red bold +.sp +to set background red +.sp +punk::ansi::a Red +.sp +see \fBpunk::ansi::a?\fR to display a list of codes +.TP +\fBget_code_name\fR \fIcode\fR +.sp +for example +.sp +get_code_name red will return 31 +.sp +get_code_name 31 will return red +.TP +\fBreset\fR +.sp +reset console +.TP +\fBreset_soft\fR +.TP +\fBreset_colour\fR +.sp +reset colour only +.TP +\fBclear\fR +.TP +\fBclear_above\fR +.TP +\fBclear_below\fR +.TP +\fBcursor_on\fR +.TP +\fBcursor_off\fR +.TP +\fBmove\fR \fIrow\fR \fIcol\fR +.sp +Return an ansi sequence to move to row,col +.sp +aka cursor home +.TP +\fBmove_emit\fR \fIrow\fR \fIcol\fR \fIdata\fR ?row col data\&.\&.\&.? +.sp +Return an ansi string representing a move to row col with data appended +.sp +row col data can be repeated any number of times to return a string representing the output of the data elements at all those points +.sp +Compare to punk::console::move_emit which calls this function - but writes it to stdout +.sp +punk::console::move_emit_return will also return the cursor to the original position +.sp +There is no punk::ansi::move_emit_return because in a standard console there is no ansi string which can represent a jump back to starting position\&. +.sp +There is an ansi code to write the current cursor position to stdin (which will generally display on the console) - this is not quite the same thing\&. +.sp +punk::console::move_emit_return does it by emitting that code and starting a loop to read stdin +.sp +punk::ansi could implement a move_emit_return using the punk::console mechanism - but the resulting string would capture the cursor position at the time the string is built - which is not necessarily when the string is used\&. +.sp +The following example shows how to do this manually, emitting the string blah at screen position 10,10 and emitting DONE back at the line we started: +.sp +.CS + +punk::ansi::move_emit 10 10 blah {*}[punk::console::get_cursor_pos_list] DONE +.CE +.sp +A string created by any move_emit_return for punk::ansi would not behave in an intuitive manner compared to other punk::ansi move functions - so is deliberately omitted\&. +.TP +\fBmove_forward\fR \fIn\fR +.TP +\fBmove_back\fR \fIn\fR +.TP +\fBmove_up\fR \fIn\fR +.TP +\fBmove_down\fR \fIn\fR +.TP +\fBerase_line\fR +.TP +\fBerase_sol\fR +.sp +Erase to start of line, leaving cursor position alone\&. +.TP +\fBerase_eol\fR +.TP +\fBcursor_pos\fR +.sp +cursor_pos unlikely to be useful on it's own like this as when written to the terminal, this sequence causes the terminal to emit the row;col sequence to stdin +.sp +The output on screen will look something like ^[[47;3R +.sp +Use punk::console::get_cursor_pos or punk::console::get_cursor_pos_list instead\&. +.sp +These functions will emit the code - but read it in from stdin so that it doesn't display, and then return the row and column as a colon-delimited string or list respectively\&. +.sp +The punk::ansi::cursor_pos function is used by punk::console::get_cursor_pos and punk::console::get_cursor_pos_list +.TP +\fBtitleset\fR \fIwindowtitles\fR +.sp +Returns the code to set the title of the terminal window to windowtitle +.sp +This may not work on terminals which have multiple panes/windows +.PP +.SS "NAMESPACE PUNK::ANSI::TA" +.PP +text ansi functions +.PP +based on but not identical to the Perl Text Ansi module: +.PP +https://github\&.com/perlancar/perl-Text-ANSI-Util/blob/master/lib/Text/ANSI/BaseUtil\&.pm +.TP +\fBdetect\fR \fItext\fR +.sp +Return a boolean indicating whether Ansi codes were detected in text +.sp +.TP +\fBdetect_csi\fR \fItext\fR +.sp +Return a boolean indicating whether an Ansi Control Sequence Introducer (CSI) was detected in text +.sp +The csi is often represented in code as \\x1b or \\033 followed by a left bracket [ +.sp +The initial byte or escape is commonly referenced as ESC in Ansi documentation +.sp +There is also a multi-byte escape sequence \\u009b +.sp +This is less commonly used but is also detected here +.sp +(This function is not in perl ta) +.TP +\fBdetect_sgr\fR \fItext\fR +.sp +Return a boolean indicating whether an ansi Select Graphics Rendition code was detected\&. +.sp +This is the set of CSI sequences ending in 'm' +.sp +This is most commonly an Ansi colour code - but also things such as underline and italics +.sp +An SGR with empty or a single zero argument is a reset of the SGR features - this is also detected\&. +.sp +(This function is not in perl ta) +.TP +\fBstrip\fR \fItext\fR +.sp +Return text stripped of Ansi codes +.sp +This is a tailcall to punk::ansi::stripansi +.TP +\fBlength\fR \fItext\fR +.sp +Return the character length after stripping ansi codes - not the printing length +.PP +.SS "NAMESPACE PUNK::ANSI::ANSISTRING" +.PP +punk::ansi::string ensemble +.PP +.SH KEYWORDS +ansi, console, module, string, terminal +.SH COPYRIGHT +.nf +Copyright (c) 2023 + +.fi diff --git a/src/embedded/man/files/punk/_module_args-0.1.0.tm.n b/src/embedded/man/files/punk/_module_args-0.1.0.tm.n new file mode 100644 index 00000000..b88bae9f --- /dev/null +++ b/src/embedded/man/files/punk/_module_args-0.1.0.tm.n @@ -0,0 +1,400 @@ +'\" +'\" Generated from file '_module_args-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2024 +'\" +.TH "punkshell_module_punk::args" 0 0\&.1\&.0 doc "args to option-value dict and values dict" +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.BS +.SH NAME +punkshell_module_punk::args \- args parsing +.SH SYNOPSIS +package require \fBpunk::args \fR +.sp +\fBopts_values\fR \fIoptionspecs\fR \fIrawargs\fR ?option value\&.\&.\&.? +.sp +.BE +.SH DESCRIPTION +.PP +Utilities for parsing proc args +.SH OVERVIEW +.PP +overview of punk::args +.SS CONCEPTS +.PP +There are 2 main conventions for parsing a proc args list +.IP [1] +.sp +leading option-value pairs followed by a list of values (Tk style) +.IP [2] +.sp +leading list of values followed by option-value pairs (Tcl style) +.PP +.PP +punk::args is focused on the 1st convention (Tk style): parsing of args in leading option-value pair style - even for non-Tk usage\&. +.PP +The proc can still contain some leading required values e\&.g +.CS + +proc dostuff {arg1 arg2 args} {\&.\&.\&.}} +.CE +.PP +but having the core values elements at the end of args is more generally useful - especially in cases where the number of trailing values is unknown and/or the proc is to be called in a functional 'pipeline' style\&. +.PP +The basic principle is that a call to punk::args::opts_vals is made near the beginning of the proc e\&.g +.CS + + + proc dofilestuff {args} { + lassign [dict values [punk::args { + -directory -default "" + -translation -default binary + } $args]] opts values + + puts "translation is [dict get $opts -translation]" + foreach f [dict values $values] { + puts "doing stuff with file: $f" + } + } + +.CE +.SS NOTES +.PP +There are alternative args parsing packages such as: +.IP [1] +argp +.IP [2] +The tcllib set of TEPAM modules +.sp +TEPAM requires an alternative procedure declaration syntax instead of proc - but has support for Tk and documentation generation\&. +.PP +.PP +punk::args was designed initially without specific reference to TEPAM - and to handle some edge cases in specific projects where TEPAM wasn't suitable\&. +.PP +In subsequent revisions of punk::args - some features were made to operate in a way that is similar to TEPAM - to avoid gratuitous differences where possible, but of course there are differences +.PP +and those used TEPAM or mixing TEPAM and punk::args should take care to assess the differences\&. +.PP +TEPAM is a mature solution and is widely available as it is included in tcllib\&. +.PP +Serious consideration should be given to using TEPAM if suitable for your project\&. +.SS DEPENDENCIES +.PP +packages used by punk::args +.IP \(bu +\fBTcl 8\&.6\fR +.PP +.SH API +.SS "NAMESPACE PUNK::ARGS::CLASS" +.PP +class definitions +.PP +.SS "NAMESPACE PUNK::ARGS" +.PP +Core API functions for punk::args +.TP +\fBopts_values\fR \fIoptionspecs\fR \fIrawargs\fR ?option value\&.\&.\&.? +.sp +Parse rawargs as a sequence of zero or more option-value pairs followed by zero or more values +.sp +Returns a dict of the form: opts values +.sp +ARGUMENTS: +.RS +.TP +multiline-string \fIoptionspecs\fR +.sp +This a block of text with records delimited by newlines (lf or crlf) +.sp +Each optionspec line must be of the form: +.sp +-optionname -key val -key2 val2\&.\&.\&. +.sp +where the valid keys for each option specification are: -default -type -range -choices -optional +.TP +list \fIrawargs\fR +.sp +This is a list of the arguments to parse\&. Usually it will be the \\$args value from the containing proc +.RE +.sp +.PP +.SS "NAMESPACE PUNK::ARGS::LIB" +.PP +Secondary functions that are part of the API +.PP +.SH INTERNAL +.SS "NAMESPACE PUNK::ARGS::SYSTEM" +.PP +Internal functions that are not part of the API +.SH KEYWORDS +args, arguments, module, parse, proc +.SH COPYRIGHT +.nf +Copyright (c) 2024 + +.fi diff --git a/src/embedded/man/files/punk/_module_fileline-0.1.0.tm.n b/src/embedded/man/files/punk/_module_fileline-0.1.0.tm.n index 04516610..0702b522 100644 --- a/src/embedded/man/files/punk/_module_fileline-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_fileline-0.1.0.tm.n @@ -368,6 +368,8 @@ CR line-endings that are intended to be interpreted as such should be mapped to packages needed by punk::fileline .IP \(bu \fBTcl 8\&.6\fR +.IP \(bu +\fBpunk::args\fR .PP .SS "OPTIONAL DEPENDENCIES" .PP diff --git a/src/embedded/man/files/punk/_module_flib-0.1.0.tm.n b/src/embedded/man/files/punk/_module_flib-0.1.0.tm.n index aa104154..0a589f59 100644 --- a/src/embedded/man/files/punk/_module_flib-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_flib-0.1.0.tm.n @@ -2,7 +2,7 @@ '\" Generated from file '_module_flib-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2024 '\" -.TH "shellspy_module_punk::flib" 0 0\&.1\&.0 doc "-" +.TH "punkshell_module_punk::flib" 0 0\&.1\&.0 doc "-" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -272,7 +272,7 @@ Database Class: \\fB\\$3\\fR .. .BS .SH NAME -shellspy_module_punk::flib \- Module API +punkshell_module_punk::flib \- Module API .SH SYNOPSIS package require \fBpunk::flib \fR .sp diff --git a/src/embedded/man/files/punk/_module_path-0.1.0.tm.n b/src/embedded/man/files/punk/_module_path-0.1.0.tm.n index a5be8569..e6555545 100644 --- a/src/embedded/man/files/punk/_module_path-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_path-0.1.0.tm.n @@ -280,7 +280,7 @@ package require \fBpunk::path \fR .sp \fBglobmatchpath\fR \fIpathglob\fR \fIpath\fR ?option value\&.\&.\&.? .sp -\fBtreefilenames\fR \fIbasepath\fR \fItailglob\fR ?option value\&.\&.\&.? +\fBtreefilenames\fR ?option value\&.\&.\&.? ?globpattern\&.\&.\&.? .sp \fBrelative\fR \fIreference\fR \fIlocation\fR .sp @@ -346,9 +346,19 @@ ie - the driveletter alone in paths such as c:/etc will still be case insensitiv .sp Explicitly specifying -nocase 0 will require the entire case to match including the driveletter\&. .TP -\fBtreefilenames\fR \fIbasepath\fR \fItailglob\fR ?option value\&.\&.\&.? +\fBtreefilenames\fR ?option value\&.\&.\&.? ?globpattern\&.\&.\&.? .sp -basic (glob based) list of filenames matching tailglob - recursive +basic (glob based) list of filenames matching each pattern in tailglobs - recursive +.sp +options: +.sp +?-dir? +.sp +defaults to [pwd] - base path for tree to search +.sp +?-antiglob_paths? +.sp +list of path patterns to exclude - may include * and ** path segments e\&.g /usr/** .sp no natsorting - so order is dependent on filesystem .TP diff --git a/src/embedded/man/index.n b/src/embedded/man/index.n index 72297173..c9535816 100644 --- a/src/embedded/man/index.n +++ b/src/embedded/man/index.n @@ -272,6 +272,24 @@ Database Class: \\fB\\$3\\fR .SH INDEX doc .RS +ansi +.RS +.TP +\fBfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::ansi +.RE +args +.RS +.TP +\fBfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::args +.RE +arguments +.RS +.TP +\fBfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::args +.RE capability .RS .TP @@ -284,6 +302,12 @@ changelog \fBfiles/project_changes\&.n\fR punkshell__project_changes .RE +console +.RS +.TP +\fBfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::ansi +.RE file .RS .TP @@ -299,21 +323,30 @@ punkshell_module_punk::path module .RS .TP +\fBfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::ansi +.TP +\fBfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::args +.TP \fBfiles/punk/_module_cap-0\&.1\&.0\&.tm\&.n\fR punkshell_module_punk::cap .TP \fBfiles/punk/_module_fileline-0\&.1\&.0\&.tm\&.n\fR punkshell_module_punk::fileline .TP +\fBfiles/punk/_module_flib-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::flib +.TP \fBfiles/punk/_module_path-0\&.1\&.0\&.tm\&.n\fR punkshell_module_punk::path -.TP -\fBfiles/punk/_module_flib-0\&.1\&.0\&.tm\&.n\fR -shellspy_module_punk::flib .RE parse .RS .TP +\fBfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::args +.TP \fBfiles/punk/_module_fileline-0\&.1\&.0\&.tm\&.n\fR punkshell_module_punk::fileline .RE @@ -329,6 +362,12 @@ plugin \fBfiles/punk/_module_cap-0\&.1\&.0\&.tm\&.n\fR punkshell_module_punk::cap .RE +proc +.RS +.TP +\fBfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::args +.RE punk .RS .TP @@ -365,6 +404,18 @@ punkshell__project_changes \fBfiles/project_intro\&.n\fR punkshell__project_intro .RE +string +.RS +.TP +\fBfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::ansi +.RE +terminal +.RS +.TP +\fBfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR +punkshell_module_punk::ansi +.RE text .RS .TP diff --git a/src/embedded/man/toc.n b/src/embedded/man/toc.n index 11f04ac4..54c26123 100644 --- a/src/embedded/man/toc.n +++ b/src/embedded/man/toc.n @@ -282,17 +282,23 @@ doc \fBpunkshell__project_intro\fR \fIfiles/project_intro\&.n\fR: Introduction to punkshell .TP +\fBpunkshell_module_punk::ansi\fR +\fIfiles/punk/_module_ansi-0\&.1\&.0\&.tm\&.n\fR: Ansi string functions +.TP +\fBpunkshell_module_punk::args\fR +\fIfiles/punk/_module_args-0\&.1\&.0\&.tm\&.n\fR: args parsing +.TP \fBpunkshell_module_punk::cap\fR \fIfiles/punk/_module_cap-0\&.1\&.0\&.tm\&.n\fR: capability provider and handler plugin system .TP \fBpunkshell_module_punk::fileline\fR \fIfiles/punk/_module_fileline-0\&.1\&.0\&.tm\&.n\fR: file line-handling utilities .TP +\fBpunkshell_module_punk::flib\fR +\fIfiles/punk/_module_flib-0\&.1\&.0\&.tm\&.n\fR: Module API +.TP \fBpunkshell_module_punk::mix::commandset::project\fR \fIfiles/punk/mix/commandset/_module_project-0\&.1\&.0\&.tm\&.n\fR: pmix commandset - project .TP \fBpunkshell_module_punk::path\fR \fIfiles/punk/_module_path-0\&.1\&.0\&.tm\&.n\fR: Filesystem path utilities -.TP -\fBshellspy_module_punk::flib\fR -\fIfiles/punk/_module_flib-0\&.1\&.0\&.tm\&.n\fR: Module API diff --git a/src/embedded/md/.doc/tocdoc b/src/embedded/md/.doc/tocdoc index 6e7f1881..0b0e5394 100644 --- a/src/embedded/md/.doc/tocdoc +++ b/src/embedded/md/.doc/tocdoc @@ -2,9 +2,11 @@ [item doc/files/main.md punkshell {punkshell - Core}] [item doc/files/project_changes.md punkshell__project_changes {punkshell Changes}] [item doc/files/project_intro.md punkshell__project_intro {Introduction to punkshell}] +[item doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi {Ansi string functions}] +[item doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args {args parsing}] [item doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap {capability provider and handler plugin system}] [item doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline {file line-handling utilities}] +[item doc/files/punk/_module_flib-0.1.0.tm.md punkshell_module_punk::flib {Module API}] [item doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::mix::commandset::project {pmix commandset - project}] [item doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path {Filesystem path utilities}] -[item doc/files/punk/_module_flib-0.1.0.tm.md shellspy_module_punk::flib {Module API}] [toc_end] diff --git a/src/embedded/md/.idx b/src/embedded/md/.idx index a8577a6d..30b5609e 100644 --- a/src/embedded/md/.idx +++ b/src/embedded/md/.idx @@ -1 +1 @@ -{file {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} repl {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} shell {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} changelog {{doc/files/project_changes.md punkshell__project_changes}} capability {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} module {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} {doc/files/punk/_module_flib-0.1.0.tm.md shellspy_module_punk::flib}} punk {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}}} {{shell doc/files/project_changes.md punkshell__project_changes} . {changelog doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/main.md punkshell} . {text doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/project_intro.md punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {plugin doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {path doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {punk doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/project_intro.md punkshell__project_intro} . {parse doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {punk doc/files/main.md punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {module doc/files/punk/_module_flib-0.1.0.tm.md shellspy_module_punk::flib} . {repl doc/files/project_changes.md punkshell__project_changes} . {punk doc/files/project_intro.md punkshell__project_intro} . {file doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/main.md punkshell} . {capability doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} .} 12 {file file repl repl text text shell shell changelog changelog capability capability parse parse filesystem filesystem path path module module punk punk plugin plugin} \ No newline at end of file +{file {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} console {{doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi}} repl {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} arguments {{doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args}} changelog {{doc/files/project_changes.md punkshell__project_changes}} shell {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} capability {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} ansi {{doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} {doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args}} terminal {{doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi}} proc {{doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args}} path {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} args {{doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args}} punk {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} module {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} {doc/files/punk/_module_flib-0.1.0.tm.md punkshell_module_punk::flib} {doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} {doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} string {{doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi}}} {{module doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi} . {shell doc/files/project_changes.md punkshell__project_changes} . {changelog doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/main.md punkshell} . {string doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi} . {parse doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} . {text doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/project_intro.md punkshell__project_intro} . {proc doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} . {module doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {path doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {filesystem doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {args doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} . {plugin doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {module doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {module doc/files/punk/_module_flib-0.1.0.tm.md punkshell_module_punk::flib} . {module doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} . {console doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi} . {shell doc/files/project_intro.md punkshell__project_intro} . {punk doc/files/project_changes.md punkshell__project_changes} . {parse doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {punk doc/files/main.md punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/project_changes.md punkshell__project_changes} . {punk doc/files/project_intro.md punkshell__project_intro} . {file doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {arguments doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args} . {repl doc/files/main.md punkshell} . {ansi doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi} . {capability doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {terminal doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi} .} 19 {file file repl repl console console text text arguments arguments shell shell changelog changelog capability capability parse parse ansi ansi proc proc terminal terminal filesystem filesystem path path args args module module punk punk plugin plugin string string} \ No newline at end of file diff --git a/src/embedded/md/.toc b/src/embedded/md/.toc index ae8ed7b0..81739c3f 100644 --- a/src/embedded/md/.toc +++ b/src/embedded/md/.toc @@ -1 +1 @@ -doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.md punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path {Filesystem path utilities}} {doc/files/punk/_module_flib-0.1.0.tm.md shellspy_module_punk::flib {Module API}} {doc/files/project_changes.md punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.md punkshell {punkshell - Core}}}} \ No newline at end of file +doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.md punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path {Filesystem path utilities}} {doc/files/punk/_module_flib-0.1.0.tm.md punkshell_module_punk::flib {Module API}} {doc/files/punk/_module_args-0.1.0.tm.md punkshell_module_punk::args {args parsing}} {doc/files/project_changes.md punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/punk/_module_ansi-0.1.0.tm.md punkshell_module_punk::ansi {Ansi string functions}} {doc/files/main.md punkshell {punkshell - Core}}}} \ No newline at end of file diff --git a/src/embedded/md/.xrf b/src/embedded/md/.xrf index 5cf81d6c..65f3ef59 100644 --- a/src/embedded/md/.xrf +++ b/src/embedded/md/.xrf @@ -1 +1 @@ -kw,capability {index.md capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell Changes} doc/files/project_changes.md {Introduction to punkshell} doc/files/project_intro.md sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md sa,punkshell(n) doc/files/main.md filesystem {index.md filesystem} sa,punkshell doc/files/main.md kw,shell {index.md shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md kw,parse {index.md parse} sa,punkshell__project_changes(n) doc/files/project_changes.md kw,path {index.md path} kw,module {index.md module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell(n) doc/files/main.md kw,plugin {index.md plugin} punkshell doc/files/main.md kw,file {index.md file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md changelog {index.md changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md punkshell__project_changes(n) doc/files/project_changes.md sa,punkshell__project_changes doc/files/project_changes.md path {index.md path} sa,shellspy_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.md file {index.md file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_changes doc/files/project_changes.md kw,filesystem {index.md filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md shellspy_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.md {Module API} doc/files/punk/_module_flib-0.1.0.tm.md shell {index.md shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md kw,repl {index.md repl} capability {index.md capability} kw,text {index.md text} parse {index.md parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell - Core} doc/files/main.md {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.md repl {index.md repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md kw,punk {index.md punk} sa,punkshell__project_intro(n) doc/files/project_intro.md text {index.md text} sa,punkshell__project_intro doc/files/project_intro.md {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.md sa,shellspy_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.md sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_intro(n) doc/files/project_intro.md {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.md punkshell__project_intro doc/files/project_intro.md kw,changelog {index.md changelog} module {index.md module} punk {index.md punk} shellspy_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.md plugin {index.md plugin} \ No newline at end of file +kw,capability {index.md capability} punkshell_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.md punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::args(0) doc/files/punk/_module_args-0.1.0.tm.md kw,proc {index.md proc} sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell Changes} doc/files/project_changes.md punkshell_module_punk::ansi doc/files/punk/_module_ansi-0.1.0.tm.md {Introduction to punkshell} doc/files/project_intro.md proc {index.md proc} sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md sa,punkshell(n) doc/files/main.md filesystem {index.md filesystem} sa,punkshell doc/files/main.md kw,shell {index.md shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md kw,parse {index.md parse} sa,punkshell_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.md sa,punkshell__project_changes(n) doc/files/project_changes.md kw,terminal {index.md terminal} kw,args {index.md args} kw,path {index.md path} kw,module {index.md module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell(n) doc/files/main.md kw,string {index.md string} kw,plugin {index.md plugin} punkshell doc/files/main.md kw,file {index.md file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md changelog {index.md changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.md punkshell__project_changes(n) doc/files/project_changes.md sa,punkshell__project_changes doc/files/project_changes.md kw,arguments {index.md arguments} terminal {index.md terminal} args {index.md args} path {index.md path} file {index.md file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::args doc/files/punk/_module_args-0.1.0.tm.md {args parsing} doc/files/punk/_module_args-0.1.0.tm.md punkshell__project_changes doc/files/project_changes.md {Ansi string functions} doc/files/punk/_module_ansi-0.1.0.tm.md kw,filesystem {index.md filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {Module API} doc/files/punk/_module_flib-0.1.0.tm.md sa,punkshell_module_punk::ansi(0) doc/files/punk/_module_ansi-0.1.0.tm.md shell {index.md shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::args doc/files/punk/_module_args-0.1.0.tm.md kw,repl {index.md repl} capability {index.md capability} kw,text {index.md text} parse {index.md parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell - Core} doc/files/main.md {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::ansi(0) doc/files/punk/_module_ansi-0.1.0.tm.md kw,ansi {index.md ansi} {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.md console {index.md console} repl {index.md repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md kw,punk {index.md punk} sa,punkshell__project_intro(n) doc/files/project_intro.md text {index.md text} sa,punkshell__project_intro doc/files/project_intro.md {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.md arguments {index.md arguments} sa,punkshell_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.md kw,console {index.md console} sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::args(0) doc/files/punk/_module_args-0.1.0.tm.md ansi {index.md ansi} punkshell__project_intro(n) doc/files/project_intro.md {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.md punkshell__project_intro doc/files/project_intro.md kw,changelog {index.md changelog} module {index.md module} punk {index.md punk} sa,punkshell_module_punk::ansi doc/files/punk/_module_ansi-0.1.0.tm.md string {index.md string} plugin {index.md plugin} \ No newline at end of file diff --git a/src/embedded/md/doc/files/punk/_module_ansi-0.1.0.tm.md b/src/embedded/md/doc/files/punk/_module_ansi-0.1.0.tm.md new file mode 100644 index 00000000..06bc52c1 --- /dev/null +++ b/src/embedded/md/doc/files/punk/_module_ansi-0.1.0.tm.md @@ -0,0 +1,333 @@ + +[//000000001]: # (punkshell\_module\_punk::ansi \- punk Ansi library) +[//000000002]: # (Generated from file '\_module\_ansi\-0\.1\.0\.tm\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (Copyright © 2023) +[//000000004]: # (punkshell\_module\_punk::ansi\(0\) 0\.1\.0 doc "punk Ansi library") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index ]
+ +# NAME + +punkshell\_module\_punk::ansi \- Ansi string functions + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Overview](#section2) + + - [Concepts](#subsection1) + + - [dependencies](#subsection2) + + - [API](#section3) + + - [Namespace punk::ansi](#subsection3) + + - [Namespace punk::ansi::ta](#subsection4) + + - [Namespace punk::ansi::ansistring](#subsection5) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require punk::ansi + +[__stripansi__ *text*](#1) +[__a?__ ?ansicode\.\.\.?](#2) +[__a\+__ ?ansicode\.\.\.?](#3) +[__a__ ?ansicode\.\.\.?](#4) +[__get\_code\_name__ *code*](#5) +[__reset__](#6) +[__reset\_soft__](#7) +[__reset\_colour__](#8) +[__clear__](#9) +[__clear\_above__](#10) +[__clear\_below__](#11) +[__cursor\_on__](#12) +[__cursor\_off__](#13) +[__move__ *row* *col*](#14) +[__move\_emit__ *row* *col* *data* ?row col data\.\.\.?](#15) +[__move\_forward__ *n*](#16) +[__move\_back__ *n*](#17) +[__move\_up__ *n*](#18) +[__move\_down__ *n*](#19) +[__erase\_line__](#20) +[__erase\_sol__](#21) +[__erase\_eol__](#22) +[__cursor\_pos__](#23) +[__titleset__ *windowtitles*](#24) +[__detect__ *text*](#25) +[__detect\_csi__ *text*](#26) +[__detect\_sgr__ *text*](#27) +[__strip__ *text*](#28) +[__length__ *text*](#29) + +# DESCRIPTION + +Ansi based terminal control string functions + +See __punk::ansi::console__ for related functions for controlling a console + +# Overview + +overview of punk::ansi + +punk::ansi functions return their values \- no implicit emission to +console/stdout + +## Concepts + +Ansi codes can be used to control most terminals on most platforms in an +'almost' standard manner + +There are many differences in terminal implementations \- but most should support +a core set of features + +punk::ansi does not contain any code for direct terminal manipulation via the +local system APIs\. + +Sticking to ansi codes where possible may be better for cross\-platform and +remote operation where such APIs are unlikely to be useable\. + +## dependencies + +packages used by punk::ansi + + - __Tcl 8\.6__ + +# API + +## Namespace punk::ansi + +Core API functions for punk::ansi + + - __stripansi__ *text* + + Return a string with ansi codes stripped out + + - __a?__ ?ansicode\.\.\.? + + Return an ansi string representing a table of codes and a panel showing the + colours + + - __a\+__ ?ansicode\.\.\.? + + Returns the ansi code to apply those from the supplied list \- without any + reset being performed first + + e\.g to set foreground red and bold + + punk::ansi::a red bold + + to set background red + + punk::ansi::a Red + + see __punk::ansi::a?__ to display a list of codes + + - __a__ ?ansicode\.\.\.? + + Returns the ansi code to reset any current settings and apply those from the + supplied list + + by calling punk::ansi::a with no arguments \- the result is a reset to plain + text + + e\.g to set foreground red and bold + + punk::ansi::a red bold + + to set background red + + punk::ansi::a Red + + see __punk::ansi::a?__ to display a list of codes + + - __get\_code\_name__ *code* + + for example + + get\_code\_name red will return 31 + + get\_code\_name 31 will return red + + - __reset__ + + reset console + + - __reset\_soft__ + + - __reset\_colour__ + + reset colour only + + - __clear__ + + - __clear\_above__ + + - __clear\_below__ + + - __cursor\_on__ + + - __cursor\_off__ + + - __move__ *row* *col* + + Return an ansi sequence to move to row,col + + aka cursor home + + - __move\_emit__ *row* *col* *data* ?row col data\.\.\.? + + Return an ansi string representing a move to row col with data appended + + row col data can be repeated any number of times to return a string + representing the output of the data elements at all those points + + Compare to punk::console::move\_emit which calls this function \- but writes + it to stdout + + punk::console::move\_emit\_return will also return the cursor to the original + position + + There is no punk::ansi::move\_emit\_return because in a standard console there + is no ansi string which can represent a jump back to starting position\. + + There is an ansi code to write the current cursor position to stdin \(which + will generally display on the console\) \- this is not quite the same thing\. + + punk::console::move\_emit\_return does it by emitting that code and starting a + loop to read stdin + + punk::ansi could implement a move\_emit\_return using the punk::console + mechanism \- but the resulting string would capture the cursor position at + the time the string is built \- which is not necessarily when the string is + used\. + + The following example shows how to do this manually, emitting the string + blah at screen position 10,10 and emitting DONE back at the line we started: + + punk::ansi::move_emit 10 10 blah {*}[punk::console::get_cursor_pos_list] DONE + + A string created by any move\_emit\_return for punk::ansi would not behave in + an intuitive manner compared to other punk::ansi move functions \- so is + deliberately omitted\. + + - __move\_forward__ *n* + + - __move\_back__ *n* + + - __move\_up__ *n* + + - __move\_down__ *n* + + - __erase\_line__ + + - __erase\_sol__ + + Erase to start of line, leaving cursor position alone\. + + - __erase\_eol__ + + - __cursor\_pos__ + + cursor\_pos unlikely to be useful on it's own like this as when written to + the terminal, this sequence causes the terminal to emit the row;col sequence + to stdin + + The output on screen will look something like ^\[\[47;3R + + Use punk::console::get\_cursor\_pos or punk::console::get\_cursor\_pos\_list + instead\. + + These functions will emit the code \- but read it in from stdin so that it + doesn't display, and then return the row and column as a colon\-delimited + string or list respectively\. + + The punk::ansi::cursor\_pos function is used by punk::console::get\_cursor\_pos + and punk::console::get\_cursor\_pos\_list + + - __titleset__ *windowtitles* + + Returns the code to set the title of the terminal window to windowtitle + + This may not work on terminals which have multiple panes/windows + +## Namespace punk::ansi::ta + +text ansi functions + +based on but not identical to the Perl Text Ansi module: + +https://github\.com/perlancar/perl\-Text\-ANSI\-Util/blob/master/lib/Text/ANSI/BaseUtil\.pm + + - __detect__ *text* + + Return a boolean indicating whether Ansi codes were detected in text + + - __detect\_csi__ *text* + + Return a boolean indicating whether an Ansi Control Sequence Introducer + \(CSI\) was detected in text + + The csi is often represented in code as \\x1b or \\033 followed by a left + bracket \[ + + The initial byte or escape is commonly referenced as ESC in Ansi + documentation + + There is also a multi\-byte escape sequence \\u009b + + This is less commonly used but is also detected here + + \(This function is not in perl ta\) + + - __detect\_sgr__ *text* + + Return a boolean indicating whether an ansi Select Graphics Rendition code + was detected\. + + This is the set of CSI sequences ending in 'm' + + This is most commonly an Ansi colour code \- but also things such as + underline and italics + + An SGR with empty or a single zero argument is a reset of the SGR features \- + this is also detected\. + + \(This function is not in perl ta\) + + - __strip__ *text* + + Return text stripped of Ansi codes + + This is a tailcall to punk::ansi::stripansi + + - __length__ *text* + + Return the character length after stripping ansi codes \- not the printing + length + +## Namespace punk::ansi::ansistring + +punk::ansi::string ensemble + +# KEYWORDS + +[ansi](\.\./\.\./\.\./index\.md\#ansi), [console](\.\./\.\./\.\./index\.md\#console), +[module](\.\./\.\./\.\./index\.md\#module), [string](\.\./\.\./\.\./index\.md\#string), +[terminal](\.\./\.\./\.\./index\.md\#terminal) + +# COPYRIGHT + +Copyright © 2023 diff --git a/src/embedded/md/doc/files/punk/_module_args-0.1.0.tm.md b/src/embedded/md/doc/files/punk/_module_args-0.1.0.tm.md new file mode 100644 index 00000000..a5ca3ac5 --- /dev/null +++ b/src/embedded/md/doc/files/punk/_module_args-0.1.0.tm.md @@ -0,0 +1,177 @@ + +[//000000001]: # (punkshell\_module\_punk::args \- args to option\-value dict and values dict) +[//000000002]: # (Generated from file '\_module\_args\-0\.1\.0\.tm\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (Copyright © 2024) +[//000000004]: # (punkshell\_module\_punk::args\(0\) 0\.1\.0 doc "args to option\-value dict and values dict") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index ]
+ +# NAME + +punkshell\_module\_punk::args \- args parsing + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Synopsis](#synopsis) + + - [Description](#section1) + + - [Overview](#section2) + + - [Concepts](#subsection1) + + - [Notes](#subsection2) + + - [dependencies](#subsection3) + + - [API](#section3) + + - [Namespace punk::args::class](#subsection4) + + - [Namespace punk::args](#subsection5) + + - [Namespace punk::args::lib](#subsection6) + + - [Internal](#section4) + + - [Namespace punk::args::system](#subsection7) + + - [Keywords](#keywords) + + - [Copyright](#copyright) + +# SYNOPSIS + +package require punk::args + +[__opts\_values__ *optionspecs* *rawargs* ?option value\.\.\.?](#1) + +# DESCRIPTION + +Utilities for parsing proc args + +# Overview + +overview of punk::args + +## Concepts + +There are 2 main conventions for parsing a proc args list + + 1. leading option\-value pairs followed by a list of values \(Tk style\) + + 1. leading list of values followed by option\-value pairs \(Tcl style\) + +punk::args is focused on the 1st convention \(Tk style\): parsing of args in +leading option\-value pair style \- even for non\-Tk usage\. + +The proc can still contain some leading required values e\.g + + proc dostuff {arg1 arg2 args} {...}} + +but having the core values elements at the end of args is more generally useful +\- especially in cases where the number of trailing values is unknown and/or the +proc is to be called in a functional 'pipeline' style\. + +The basic principle is that a call to punk::args::opts\_vals is made near the +beginning of the proc e\.g + + proc dofilestuff {args} { + lassign [dict values [punk::args { + -directory -default "" + -translation -default binary + } $args]] opts values + + puts "translation is [dict get $opts -translation]" + foreach f [dict values $values] { + puts "doing stuff with file: $f" + } + } + +## Notes + +There are alternative args parsing packages such as: + + 1. argp + + 1. The tcllib set of TEPAM modules + + TEPAM requires an alternative procedure declaration syntax instead of proc + \- but has support for Tk and documentation generation\. + +punk::args was designed initially without specific reference to TEPAM \- and to +handle some edge cases in specific projects where TEPAM wasn't suitable\. + +In subsequent revisions of punk::args \- some features were made to operate in a +way that is similar to TEPAM \- to avoid gratuitous differences where possible, +but of course there are differences + +and those used TEPAM or mixing TEPAM and punk::args should take care to assess +the differences\. + +TEPAM is a mature solution and is widely available as it is included in tcllib\. + +Serious consideration should be given to using TEPAM if suitable for your +project\. + +## dependencies + +packages used by punk::args + + - __Tcl 8\.6__ + +# API + +## Namespace punk::args::class + +class definitions + +## Namespace punk::args + + - __opts\_values__ *optionspecs* *rawargs* ?option value\.\.\.? + + Parse rawargs as a sequence of zero or more option\-value pairs followed by + zero or more values + + Returns a dict of the form: opts values + + ARGUMENTS: + + * multiline\-string *optionspecs* + + This a block of text with records delimited by newlines \(lf or crlf\) + + Each optionspec line must be of the form: + + \-optionname \-key val \-key2 val2\.\.\. + + where the valid keys for each option specification are: \-default \-type + \-range \-choices \-optional + + * list *rawargs* + + This is a list of the arguments to parse\. Usually it will be the \\$args + value from the containing proc + +## Namespace punk::args::lib + +Secondary functions that are part of the API + +# Internal + +## Namespace punk::args::system + +# KEYWORDS + +[args](\.\./\.\./\.\./index\.md\#args), +[arguments](\.\./\.\./\.\./index\.md\#arguments), +[module](\.\./\.\./\.\./index\.md\#module), [parse](\.\./\.\./\.\./index\.md\#parse), +[proc](\.\./\.\./\.\./index\.md\#proc) + +# COPYRIGHT + +Copyright © 2024 diff --git a/src/embedded/md/doc/files/punk/_module_fileline-0.1.0.tm.md b/src/embedded/md/doc/files/punk/_module_fileline-0.1.0.tm.md index 021d2207..27ff3de3 100644 --- a/src/embedded/md/doc/files/punk/_module_fileline-0.1.0.tm.md +++ b/src/embedded/md/doc/files/punk/_module_fileline-0.1.0.tm.md @@ -129,6 +129,8 @@ packages needed by punk::fileline - __Tcl 8\.6__ + - __punk::args__ + ## optional dependencies packages that add functionality but aren't strictly required diff --git a/src/embedded/md/doc/files/punk/_module_flib-0.1.0.tm.md b/src/embedded/md/doc/files/punk/_module_flib-0.1.0.tm.md index 77613898..625bcfa9 100644 --- a/src/embedded/md/doc/files/punk/_module_flib-0.1.0.tm.md +++ b/src/embedded/md/doc/files/punk/_module_flib-0.1.0.tm.md @@ -1,8 +1,8 @@ -[//000000001]: # (shellspy\_module\_punk::flib \- \-) +[//000000001]: # (punkshell\_module\_punk::flib \- \-) [//000000002]: # (Generated from file '\_module\_flib\-0\.1\.0\.tm\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © 2024) -[//000000004]: # (shellspy\_module\_punk::flib\(0\) 0\.1\.0 doc "\-") +[//000000004]: # (punkshell\_module\_punk::flib\(0\) 0\.1\.0 doc "\-")
[ Main Table Of Contents | Table Of Contents | Keyword Index ]
# NAME -shellspy\_module\_punk::flib \- Module API +punkshell\_module\_punk::flib \- Module API # Table Of Contents diff --git a/src/embedded/md/doc/files/punk/_module_path-0.1.0.tm.md b/src/embedded/md/doc/files/punk/_module_path-0.1.0.tm.md index 3a9398a6..55ae4818 100644 --- a/src/embedded/md/doc/files/punk/_module_path-0.1.0.tm.md +++ b/src/embedded/md/doc/files/punk/_module_path-0.1.0.tm.md @@ -48,7 +48,7 @@ package require punk::path [__pathglob\_as\_re__ *pathglob*](#1) [__globmatchpath__ *pathglob* *path* ?option value\.\.\.?](#2) -[__treefilenames__ *basepath* *tailglob* ?option value\.\.\.?](#3) +[__treefilenames__ ?option value\.\.\.? ?globpattern\.\.\.?](#3) [__relative__ *reference* *location*](#4) # DESCRIPTION @@ -123,9 +123,21 @@ class definitions Explicitly specifying \-nocase 0 will require the entire case to match including the driveletter\. - - __treefilenames__ *basepath* *tailglob* ?option value\.\.\.? + - __treefilenames__ ?option value\.\.\.? ?globpattern\.\.\.? - basic \(glob based\) list of filenames matching tailglob \- recursive + basic \(glob based\) list of filenames matching each pattern in tailglobs \- + recursive + + options: + + ?\-dir? + + defaults to \[pwd\] \- base path for tree to search + + ?\-antiglob\_paths? + + list of path patterns to exclude \- may include \* and \*\* path segments e\.g + /usr/\*\* no natsorting \- so order is dependent on filesystem diff --git a/src/embedded/md/doc/toc.md b/src/embedded/md/doc/toc.md index 478cfdbd..8467a87e 100644 --- a/src/embedded/md/doc/toc.md +++ b/src/embedded/md/doc/toc.md @@ -9,12 +9,16 @@ - [punkshell\_\_project\_intro](doc/files/project\_intro\.md) Introduction to punkshell + - [punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md) Ansi string functions + + - [punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md) args parsing + - [punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md) capability provider and handler plugin system - [punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md) file line\-handling utilities + - [punkshell\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md) Module API + - [punkshell\_module\_punk::mix::commandset::project](doc/files/punk/mix/commandset/\_module\_project\-0\.1\.0\.tm\.md) pmix commandset \- project - [punkshell\_module\_punk::path](doc/files/punk/\_module\_path\-0\.1\.0\.tm\.md) Filesystem path utilities - - - [shellspy\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md) Module API diff --git a/src/embedded/md/index.md b/src/embedded/md/index.md index 70f60b05..9e32db26 100644 --- a/src/embedded/md/index.md +++ b/src/embedded/md/index.md @@ -5,16 +5,26 @@ ---- -[C](#cC) · [F](#cF) · [M](#cM) · [P](#cP) · [R](#cR) · [S](#cS) · [T](#cT) +[A](#cA) · [C](#cC) · [F](#cF) · [M](#cM) · [P](#cP) · [R](#cR) · [S](#cS) · [T](#cT) ---- +#### Keywords: A + +||| +|---|---| +|ansi|[punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md)| +|args|[punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md)| +|arguments|[punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md)| + + #### Keywords: C ||| |---|---| |capability|[punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md)| |changelog|[punkshell\_\_project\_changes](doc/files/project\_changes\.md)| +|console|[punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md)| #### Keywords: F @@ -29,16 +39,17 @@ ||| |---|---| -|module|[punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::path](doc/files/punk/\_module\_path\-0\.1\.0\.tm\.md) · [shellspy\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md)| +|module|[punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::path](doc/files/punk/\_module\_path\-0\.1\.0\.tm\.md)| #### Keywords: P ||| |---|---| -|parse|[punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md)| +|parse|[punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md) · [punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md)| |path|[punkshell\_module\_punk::path](doc/files/punk/\_module\_path\-0\.1\.0\.tm\.md)| |plugin|[punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md)| +|proc|[punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md)| |punk|[punkshell](doc/files/main\.md) · [punkshell\_\_project\_changes](doc/files/project\_changes\.md) · [punkshell\_\_project\_intro](doc/files/project\_intro\.md)| @@ -54,10 +65,12 @@ ||| |---|---| |shell|[punkshell](doc/files/main\.md) · [punkshell\_\_project\_changes](doc/files/project\_changes\.md) · [punkshell\_\_project\_intro](doc/files/project\_intro\.md)| +|string|[punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md)| #### Keywords: T ||| |---|---| +|terminal|[punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md)| |text|[punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md)| diff --git a/src/embedded/md/toc.md b/src/embedded/md/toc.md index 478cfdbd..8467a87e 100644 --- a/src/embedded/md/toc.md +++ b/src/embedded/md/toc.md @@ -9,12 +9,16 @@ - [punkshell\_\_project\_intro](doc/files/project\_intro\.md) Introduction to punkshell + - [punkshell\_module\_punk::ansi](doc/files/punk/\_module\_ansi\-0\.1\.0\.tm\.md) Ansi string functions + + - [punkshell\_module\_punk::args](doc/files/punk/\_module\_args\-0\.1\.0\.tm\.md) args parsing + - [punkshell\_module\_punk::cap](doc/files/punk/\_module\_cap\-0\.1\.0\.tm\.md) capability provider and handler plugin system - [punkshell\_module\_punk::fileline](doc/files/punk/\_module\_fileline\-0\.1\.0\.tm\.md) file line\-handling utilities + - [punkshell\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md) Module API + - [punkshell\_module\_punk::mix::commandset::project](doc/files/punk/mix/commandset/\_module\_project\-0\.1\.0\.tm\.md) pmix commandset \- project - [punkshell\_module\_punk::path](doc/files/punk/\_module\_path\-0\.1\.0\.tm\.md) Filesystem path utilities - - - [shellspy\_module\_punk::flib](doc/files/punk/\_module\_flib\-0\.1\.0\.tm\.md) Module API diff --git a/src/embedded/www/.doc/tocdoc b/src/embedded/www/.doc/tocdoc index d7016cc5..a6b4cc5d 100644 --- a/src/embedded/www/.doc/tocdoc +++ b/src/embedded/www/.doc/tocdoc @@ -2,9 +2,11 @@ [item doc/files/main.html punkshell {punkshell - Core}] [item doc/files/project_changes.html punkshell__project_changes {punkshell Changes}] [item doc/files/project_intro.html punkshell__project_intro {Introduction to punkshell}] +[item doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi {Ansi string functions}] +[item doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args {args parsing}] [item doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap {capability provider and handler plugin system}] [item doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline {file line-handling utilities}] +[item doc/files/punk/_module_flib-0.1.0.tm.html punkshell_module_punk::flib {Module API}] [item doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::mix::commandset::project {pmix commandset - project}] [item doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path {Filesystem path utilities}] -[item doc/files/punk/_module_flib-0.1.0.tm.html shellspy_module_punk::flib {Module API}] [toc_end] diff --git a/src/embedded/www/.idx b/src/embedded/www/.idx index a764e688..f66fc98b 100644 --- a/src/embedded/www/.idx +++ b/src/embedded/www/.idx @@ -1 +1 @@ -{file {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} repl {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} shell {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} changelog {{doc/files/project_changes.html punkshell__project_changes}} capability {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} module {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} {doc/files/punk/_module_flib-0.1.0.tm.html shellspy_module_punk::flib}} punk {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}}} {{repl doc/files/main.html punkshell} . {file doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/project_intro.html punkshell__project_intro} . {capability doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {shell doc/files/project_changes.html punkshell__project_changes} . {changelog doc/files/project_changes.html punkshell__project_changes} . {shell doc/files/main.html punkshell} . {text doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {repl doc/files/project_intro.html punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {path doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {plugin doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {shell doc/files/project_intro.html punkshell__project_intro} . {punk doc/files/project_changes.html punkshell__project_changes} . {parse doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/main.html punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {module doc/files/punk/_module_flib-0.1.0.tm.html shellspy_module_punk::flib} . {repl doc/files/project_changes.html punkshell__project_changes} .} 12 {file file repl repl text text shell shell changelog changelog capability capability parse parse filesystem filesystem path path module module punk punk plugin plugin} \ No newline at end of file +{file {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} console {{doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi}} repl {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} arguments {{doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args}} changelog {{doc/files/project_changes.html punkshell__project_changes}} shell {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} capability {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} ansi {{doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} {doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args}} terminal {{doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi}} proc {{doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args}} path {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} args {{doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args}} punk {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} module {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} {doc/files/punk/_module_flib-0.1.0.tm.html punkshell_module_punk::flib} {doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} {doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} string {{doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi}}} {{repl doc/files/main.html punkshell} . {arguments doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} . {file doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/project_intro.html punkshell__project_intro} . {ansi doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi} . {terminal doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi} . {capability doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {module doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi} . {shell doc/files/project_changes.html punkshell__project_changes} . {changelog doc/files/project_changes.html punkshell__project_changes} . {repl doc/files/project_intro.html punkshell__project_intro} . {text doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {parse doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} . {shell doc/files/main.html punkshell} . {string doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi} . {module doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {proc doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} . {path doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {filesystem doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {plugin doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {args doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} . {module doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {module doc/files/punk/_module_flib-0.1.0.tm.html punkshell_module_punk::flib} . {module doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args} . {console doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi} . {shell doc/files/project_intro.html punkshell__project_intro} . {punk doc/files/project_changes.html punkshell__project_changes} . {parse doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/main.html punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {repl doc/files/project_changes.html punkshell__project_changes} .} 19 {file file repl repl console console text text arguments arguments shell shell changelog changelog capability capability parse parse ansi ansi proc proc terminal terminal filesystem filesystem path path args args module module punk punk plugin plugin string string} \ No newline at end of file diff --git a/src/embedded/www/.toc b/src/embedded/www/.toc index 22a54fd3..4bd50c19 100644 --- a/src/embedded/www/.toc +++ b/src/embedded/www/.toc @@ -1 +1 @@ -doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.html punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path {Filesystem path utilities}} {doc/files/punk/_module_flib-0.1.0.tm.html shellspy_module_punk::flib {Module API}} {doc/files/project_changes.html punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.html punkshell {punkshell - Core}}}} \ No newline at end of file +doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.html punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path {Filesystem path utilities}} {doc/files/punk/_module_flib-0.1.0.tm.html punkshell_module_punk::flib {Module API}} {doc/files/punk/_module_args-0.1.0.tm.html punkshell_module_punk::args {args parsing}} {doc/files/project_changes.html punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/punk/_module_ansi-0.1.0.tm.html punkshell_module_punk::ansi {Ansi string functions}} {doc/files/main.html punkshell {punkshell - Core}}}} \ No newline at end of file diff --git a/src/embedded/www/.xrf b/src/embedded/www/.xrf index 69c386ed..c9541f58 100644 --- a/src/embedded/www/.xrf +++ b/src/embedded/www/.xrf @@ -1 +1 @@ -kw,capability {index.html capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell Changes} doc/files/project_changes.html {Introduction to punkshell} doc/files/project_intro.html sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html sa,punkshell(n) doc/files/main.html filesystem {index.html filesystem} sa,punkshell doc/files/main.html kw,shell {index.html shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html kw,parse {index.html parse} sa,punkshell__project_changes(n) doc/files/project_changes.html kw,path {index.html path} kw,module {index.html module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell(n) doc/files/main.html kw,plugin {index.html plugin} punkshell doc/files/main.html kw,file {index.html file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html changelog {index.html changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html punkshell__project_changes(n) doc/files/project_changes.html sa,punkshell__project_changes doc/files/project_changes.html path {index.html path} sa,shellspy_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.html file {index.html file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_changes doc/files/project_changes.html kw,filesystem {index.html filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html shellspy_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.html {Module API} doc/files/punk/_module_flib-0.1.0.tm.html shell {index.html shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html kw,repl {index.html repl} capability {index.html capability} kw,text {index.html text} parse {index.html parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell - Core} doc/files/main.html {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.html repl {index.html repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html kw,punk {index.html punk} sa,punkshell__project_intro(n) doc/files/project_intro.html text {index.html text} sa,punkshell__project_intro doc/files/project_intro.html {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.html sa,shellspy_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.html sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_intro(n) doc/files/project_intro.html {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.html punkshell__project_intro doc/files/project_intro.html kw,changelog {index.html changelog} module {index.html module} punk {index.html punk} shellspy_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.html plugin {index.html plugin} \ No newline at end of file +kw,capability {index.html capability} punkshell_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.html punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::args(0) doc/files/punk/_module_args-0.1.0.tm.html kw,proc {index.html proc} sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell Changes} doc/files/project_changes.html punkshell_module_punk::ansi doc/files/punk/_module_ansi-0.1.0.tm.html {Introduction to punkshell} doc/files/project_intro.html proc {index.html proc} sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html sa,punkshell(n) doc/files/main.html filesystem {index.html filesystem} sa,punkshell doc/files/main.html kw,shell {index.html shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html kw,parse {index.html parse} sa,punkshell_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.html sa,punkshell__project_changes(n) doc/files/project_changes.html kw,terminal {index.html terminal} kw,args {index.html args} kw,path {index.html path} kw,module {index.html module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell(n) doc/files/main.html kw,string {index.html string} kw,plugin {index.html plugin} punkshell doc/files/main.html kw,file {index.html file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html changelog {index.html changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::flib(0) doc/files/punk/_module_flib-0.1.0.tm.html punkshell__project_changes(n) doc/files/project_changes.html sa,punkshell__project_changes doc/files/project_changes.html kw,arguments {index.html arguments} terminal {index.html terminal} args {index.html args} path {index.html path} file {index.html file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::args doc/files/punk/_module_args-0.1.0.tm.html {args parsing} doc/files/punk/_module_args-0.1.0.tm.html punkshell__project_changes doc/files/project_changes.html {Ansi string functions} doc/files/punk/_module_ansi-0.1.0.tm.html kw,filesystem {index.html filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {Module API} doc/files/punk/_module_flib-0.1.0.tm.html sa,punkshell_module_punk::ansi(0) doc/files/punk/_module_ansi-0.1.0.tm.html shell {index.html shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::args doc/files/punk/_module_args-0.1.0.tm.html kw,repl {index.html repl} capability {index.html capability} kw,text {index.html text} parse {index.html parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell - Core} doc/files/main.html {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::ansi(0) doc/files/punk/_module_ansi-0.1.0.tm.html kw,ansi {index.html ansi} {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.html console {index.html console} repl {index.html repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html kw,punk {index.html punk} sa,punkshell__project_intro(n) doc/files/project_intro.html text {index.html text} sa,punkshell__project_intro doc/files/project_intro.html {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.html arguments {index.html arguments} sa,punkshell_module_punk::flib doc/files/punk/_module_flib-0.1.0.tm.html kw,console {index.html console} sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::args(0) doc/files/punk/_module_args-0.1.0.tm.html ansi {index.html ansi} punkshell__project_intro(n) doc/files/project_intro.html {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.html punkshell__project_intro doc/files/project_intro.html kw,changelog {index.html changelog} module {index.html module} punk {index.html punk} sa,punkshell_module_punk::ansi doc/files/punk/_module_ansi-0.1.0.tm.html string {index.html string} plugin {index.html plugin} \ No newline at end of file diff --git a/src/embedded/www/doc/files/punk/_module_ansi-0.1.0.tm.html b/src/embedded/www/doc/files/punk/_module_ansi-0.1.0.tm.html new file mode 100644 index 00000000..99b0bf5e --- /dev/null +++ b/src/embedded/www/doc/files/punk/_module_ansi-0.1.0.tm.html @@ -0,0 +1,312 @@ + +punkshell_module_punk::ansi - punk Ansi library + + + + + +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index + ]
+
+

punkshell_module_punk::ansi(0) 0.1.0 doc "punk Ansi library"

+

Name

+

punkshell_module_punk::ansi - Ansi string functions

+
+ + +

Description

+

Ansi based terminal control string functions

+

See punk::ansi::console for related functions for controlling a console

+
+

Overview

+

overview of punk::ansi

+

punk::ansi functions return their values - no implicit emission to console/stdout

+

Concepts

+

Ansi codes can be used to control most terminals on most platforms in an 'almost' standard manner

+

There are many differences in terminal implementations - but most should support a core set of features

+

punk::ansi does not contain any code for direct terminal manipulation via the local system APIs.

+

Sticking to ansi codes where possible may be better for cross-platform and remote operation where such APIs are unlikely to be useable.

+
+

dependencies

+

packages used by punk::ansi

+
    +

  • Tcl 8.6

    • +
+
+
+

API

+

Namespace punk::ansi

+

Core API functions for punk::ansi

+
+
stripansi text
+

Return a string with ansi codes stripped out

+
a? ?ansicode...?
+

Return an ansi string representing a table of codes and a panel showing the colours

+
a+ ?ansicode...?
+

Returns the ansi code to apply those from the supplied list - without any reset being performed first

+

e.g to set foreground red and bold

+

punk::ansi::a red bold

+

to set background red

+

punk::ansi::a Red

+

see punk::ansi::a? to display a list of codes

+
a ?ansicode...?
+

Returns the ansi code to reset any current settings and apply those from the supplied list

+

by calling punk::ansi::a with no arguments - the result is a reset to plain text

+

e.g to set foreground red and bold

+

punk::ansi::a red bold

+

to set background red

+

punk::ansi::a Red

+

see punk::ansi::a? to display a list of codes

+
get_code_name code
+

for example

+

get_code_name red will return 31

+

get_code_name 31 will return red

+
reset
+

reset console

+
reset_soft
+
+
reset_colour
+

reset colour only

+
clear
+
+
clear_above
+
+
clear_below
+
+
cursor_on
+
+
cursor_off
+
+
move row col
+

Return an ansi sequence to move to row,col

+

aka cursor home

+
move_emit row col data ?row col data...?
+

Return an ansi string representing a move to row col with data appended

+

row col data can be repeated any number of times to return a string representing the output of the data elements at all those points

+

Compare to punk::console::move_emit which calls this function - but writes it to stdout

+

punk::console::move_emit_return will also return the cursor to the original position

+

There is no punk::ansi::move_emit_return because in a standard console there is no ansi string which can represent a jump back to starting position.

+

There is an ansi code to write the current cursor position to stdin (which will generally display on the console) - this is not quite the same thing.

+

punk::console::move_emit_return does it by emitting that code and starting a loop to read stdin

+

punk::ansi could implement a move_emit_return using the punk::console mechanism - but the resulting string would capture the cursor position at the time the string is built - which is not necessarily when the string is used.

+

The following example shows how to do this manually, emitting the string blah at screen position 10,10 and emitting DONE back at the line we started:

+
punk::ansi::move_emit 10 10 blah {*}[punk::console::get_cursor_pos_list] DONE
+

A string created by any move_emit_return for punk::ansi would not behave in an intuitive manner compared to other punk::ansi move functions - so is deliberately omitted.

+
move_forward n
+
+
move_back n
+
+
move_up n
+
+
move_down n
+
+
erase_line
+
+
erase_sol
+

Erase to start of line, leaving cursor position alone.

+
erase_eol
+
+
cursor_pos
+

cursor_pos unlikely to be useful on it's own like this as when written to the terminal, this sequence causes the terminal to emit the row;col sequence to stdin

+

The output on screen will look something like ^[[47;3R

+

Use punk::console::get_cursor_pos or punk::console::get_cursor_pos_list instead.

+

These functions will emit the code - but read it in from stdin so that it doesn't display, and then return the row and column as a colon-delimited string or list respectively.

+

The punk::ansi::cursor_pos function is used by punk::console::get_cursor_pos and punk::console::get_cursor_pos_list

+
titleset windowtitles
+

Returns the code to set the title of the terminal window to windowtitle

+

This may not work on terminals which have multiple panes/windows

+
+
+

Namespace punk::ansi::ta

+

text ansi functions

+

based on but not identical to the Perl Text Ansi module:

+

https://github.com/perlancar/perl-Text-ANSI-Util/blob/master/lib/Text/ANSI/BaseUtil.pm

+
+
detect text
+

Return a boolean indicating whether Ansi codes were detected in text

+
detect_csi text
+

Return a boolean indicating whether an Ansi Control Sequence Introducer (CSI) was detected in text

+

The csi is often represented in code as \x1b or \033 followed by a left bracket [

+

The initial byte or escape is commonly referenced as ESC in Ansi documentation

+

There is also a multi-byte escape sequence \u009b

+

This is less commonly used but is also detected here

+

(This function is not in perl ta)

+
detect_sgr text
+

Return a boolean indicating whether an ansi Select Graphics Rendition code was detected.

+

This is the set of CSI sequences ending in 'm'

+

This is most commonly an Ansi colour code - but also things such as underline and italics

+

An SGR with empty or a single zero argument is a reset of the SGR features - this is also detected.

+

(This function is not in perl ta)

+
strip text
+

Return text stripped of Ansi codes

+

This is a tailcall to punk::ansi::stripansi

+
length text
+

Return the character length after stripping ansi codes - not the printing length

+
+
+

Namespace punk::ansi::ansistring

+

punk::ansi::string ensemble

+
+
+
+
+ + +
diff --git a/src/embedded/www/doc/files/punk/_module_args-0.1.0.tm.html b/src/embedded/www/doc/files/punk/_module_args-0.1.0.tm.html new file mode 100644 index 00000000..2425434f --- /dev/null +++ b/src/embedded/www/doc/files/punk/_module_args-0.1.0.tm.html @@ -0,0 +1,238 @@ + +punkshell_module_punk::args - args to option-value dict and values dict + + + + + +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index + ]
+
+

punkshell_module_punk::args(0) 0.1.0 doc "args to option-value dict and values dict"

+

Name

+

punkshell_module_punk::args - args parsing

+
+ +

Synopsis

+
+
    +
  • package require punk::args
    • +
+ +
+
+

Description

+

Utilities for parsing proc args

+
+

Overview

+

overview of punk::args

+

Concepts

+

There are 2 main conventions for parsing a proc args list

+
    +

  1. leading option-value pairs followed by a list of values (Tk style)

    2. +

  2. leading list of values followed by option-value pairs (Tcl style)

    3. +
+

punk::args is focused on the 1st convention (Tk style): parsing of args in leading option-value pair style - even for non-Tk usage.

+

The proc can still contain some leading required values e.g

+
proc dostuff {arg1 arg2 args} {...}}
+

but having the core values elements at the end of args is more generally useful - especially in cases where the number of trailing values is unknown and/or the proc is to be called in a functional 'pipeline' style.

+

The basic principle is that a call to punk::args::opts_vals is made near the beginning of the proc e.g

+
+   proc dofilestuff {args} {
+       lassign [dict values [punk::args {
+           -directory   -default ""
+           -translation -default binary
+       } $args]] opts values
+       puts "translation is [dict get $opts -translation]"
+       foreach f [dict values $values] {
+           puts "doing stuff with file: $f"
+       }
+   }
+
+
+

Notes

+

There are alternative args parsing packages such as:

+
    +

  1. argp

    2. +

  2. The tcllib set of TEPAM modules

    +

    TEPAM requires an alternative procedure declaration syntax instead of proc - but has support for Tk and documentation generation.

    3. +
+

punk::args was designed initially without specific reference to TEPAM - and to handle some edge cases in specific projects where TEPAM wasn't suitable.

+

In subsequent revisions of punk::args - some features were made to operate in a way that is similar to TEPAM - to avoid gratuitous differences where possible, but of course there are differences

+

and those used TEPAM or mixing TEPAM and punk::args should take care to assess the differences.

+

TEPAM is a mature solution and is widely available as it is included in tcllib.

+

Serious consideration should be given to using TEPAM if suitable for your project.

+
+

dependencies

+

packages used by punk::args

+
    +

  • Tcl 8.6

    • +
+
+
+

API

+

Namespace punk::args::class

+

class definitions

+
    +
+
+

Namespace punk::args

+

Core API functions for punk::args

+
+
opts_values optionspecs rawargs ?option value...?
+

Parse rawargs as a sequence of zero or more option-value pairs followed by zero or more values

+

Returns a dict of the form: opts <options_dict> values <values_dict>

+

ARGUMENTS:

+
+
multiline-string optionspecs
+

This a block of text with records delimited by newlines (lf or crlf)

+

Each optionspec line must be of the form:

+

-optionname -key val -key2 val2...

+

where the valid keys for each option specification are: -default -type -range -choices -optional

+
list rawargs
+

This is a list of the arguments to parse. Usually it will be the \$args value from the containing proc

+
+
+
+

Namespace punk::args::lib

+

Secondary functions that are part of the API

+
+
+
+
+

Internal

+

Namespace punk::args::system

+

Internal functions that are not part of the API

+
+
+ + +
diff --git a/src/embedded/www/doc/files/punk/_module_fileline-0.1.0.tm.html b/src/embedded/www/doc/files/punk/_module_fileline-0.1.0.tm.html index 66609dc2..16ae4633 100644 --- a/src/embedded/www/doc/files/punk/_module_fileline-0.1.0.tm.html +++ b/src/embedded/www/doc/files/punk/_module_fileline-0.1.0.tm.html @@ -200,6 +200,7 @@

packages needed by punk::fileline

  • Tcl 8.6

    • +

  • punk::args

optional dependencies

diff --git a/src/embedded/www/doc/files/punk/_module_flib-0.1.0.tm.html b/src/embedded/www/doc/files/punk/_module_flib-0.1.0.tm.html index 4186d614..9bbd9dac 100644 --- a/src/embedded/www/doc/files/punk/_module_flib-0.1.0.tm.html +++ b/src/embedded/www/doc/files/punk/_module_flib-0.1.0.tm.html @@ -1,5 +1,5 @@ -shellspy_module_punk::flib - - +punkshell_module_punk::flib - -