diff --git a/src/embedded/man/files/_module_overtype-1.6.2.tm.n b/src/embedded/man/files/_module_overtype-1.6.2.tm.n new file mode 100644 index 00000000..3851633d --- /dev/null +++ b/src/embedded/man/files/_module_overtype-1.6.2.tm.n @@ -0,0 +1,354 @@ +'\" +'\" Generated from file '_module_overtype-1\&.6\&.2\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2024 +'\" +.TH "overtype_module_overtype" 0 1\&.6\&.2 doc "overtype text layout" +.\" 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 +overtype_module_overtype \- overtype text layout - ansi aware +.SH SYNOPSIS +package require \fBovertype \fR +.sp +\fBovertype::left\fR \fIargs\fR +.sp +\fBovertype::renderline\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +- +.SH OVERVIEW +.PP +overview of overtype +.SS CONCEPTS +.PP +- +.SS DEPENDENCIES +.PP +packages used by overtype +.IP \(bu +\fBTcl 8\&.6\fR +.IP \(bu +\fBtextutil\fR +.IP \(bu +\fBpunk::ansi\fR +.sp +- required to detect, split, strip and calculate lengths of text possibly containing ansi codes +.IP \(bu +\fBpunk::char\fR +.sp +- box drawing - and also unicode character width determination for proper layout of text with double-column-width chars +.PP +.SH API +.SS "NAMESPACE OVERTYPE" +.PP +Core API functions for overtype +.TP +\fBovertype::left\fR \fIargs\fR +.sp +usage: ?-transparent [0|1]? ?-overflow [1|0]? ?-ellipsis [1|0]? ?-ellipsistext \&.\&.\&.? undertext overtext +.TP +\fBovertype::renderline\fR \fIargs\fR +.sp +renderline is the core engine for overtype string processing (frames & textblocks), and the raw mode commandline repl for the Tcl Punk Shell +.sp +It is also a central part of an ansi (micro) virtual terminal-emulator of sorts +.sp +This system does a half decent job at rendering 90's ANSI art to manipulable colour text blocks that can be joined & framed for layout display within a unix or windows terminal +.sp +Renderline helps maintain ANSI text styling reset/replay codes so that the styling of one block doesn't affect another\&. +.sp +Calling on the punk::ansi library - it can coalesce codes to keep the size down\&. +.sp +It is a giant mess of doing exactly what common wisdom says not to do\&.\&.\&. lots at once\&. +.sp +renderline is part of the Unicode and ANSI aware Overtype system which 'renders' a block of text onto a static underlay +.sp +The underlay is generally expected to be an ordered set of lines or a rectangular text block analogous to a terminal screen - but it can also be ragged in line length, or just blank\&. +.sp +The overlay couuld be similar - in which case it may often be used to overwrite a column or section of the underlay\&. +.sp +The overlay could however be a sequence of ANSI-laden text that jumps all over the place\&. +.sp +renderline itself only deals with a single line - or sometimes a single character\&. It is generally called from a loop that does further terminal-like or textblock processing\&. +.sp +By suppyling the -info 1 option - it can return various fields indicating the state of the render\&. +.sp +The main 3 are the result, overflow_right, and unapplied\&. +.sp +Renderline handles cursor movements from either keystrokes or ANSI sequences but for a full system the aforementioned loop will need to be in place to manage the set of lines under manipulation\&. +.PP +.SH KEYWORDS +ansi, module, text +.SH COPYRIGHT +.nf +Copyright (c) 2024 + +.fi 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.1.tm.n similarity index 68% rename from src/embedded/man/files/punk/_module_ansi-0.1.0.tm.n rename to src/embedded/man/files/punk/_module_ansi-0.1.1.tm.n index 7b7ed9ec..aa11d894 100644 --- a/src/embedded/man/files/punk/_module_ansi-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_ansi-0.1.1.tm.n @@ -1,8 +1,8 @@ '\" -'\" Generated from file '_module_ansi-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Generated from file '_module_ansi-0\&.1\&.1\&.tm\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2023 '\" -.TH "punkshell_module_punk::ansi" 0 0\&.1\&.0 doc "punk Ansi library" +.TH "punkshell_module_punk::ansi" 0 0\&.1\&.1 doc "punk Ansi library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -278,12 +278,16 @@ package require \fBpunk::ansi \fR .sp \fBstripansi\fR \fItext\fR .sp +\fBstripansi\fR \fItext\fR +.sp \fBa?\fR ?ansicode\&.\&.\&.? .sp \fBa+\fR ?ansicode\&.\&.\&.? .sp \fBa\fR ?ansicode\&.\&.\&.? .sp +\fBa\fR ?ansicode\&.\&.\&.? +.sp \fBget_code_name\fR \fIcode\fR .sp \fBreset\fR @@ -314,16 +318,56 @@ package require \fBpunk::ansi \fR .sp \fBmove_down\fR \fIn\fR .sp +\fBmove_column\fR \fIcol\fR +.sp +\fBmove_row\fR \fIrow\fR +.sp +\fBcursor_save\fR +.sp +\fBcursor_restore\fR +.sp +\fBcursor_save_dec\fR +.sp +\fBcursor_restore_attributes\fR +.sp +\fBenable_line_wrap\fR +.sp +\fBdisable_line_wrap\fR +.sp +\fBquery_mode_line_wrap\fR +.sp \fBerase_line\fR .sp \fBerase_sol\fR .sp \fBerase_eol\fR .sp +\fBscroll_up\fR \fIn\fR +.sp +\fBscroll_down\fR \fIn\fR +.sp +\fBinsert_spaces\fR \fIcount\fR +.sp +\fBdelete_characters\fR \fIcount\fR +.sp +\fBerase_characters\fR \fIcount\fR +.sp +\fBinsert_lines\fR \fIcount\fR +.sp +\fBdelete_lines\fR \fIcount\fR +.sp \fBcursor_pos\fR .sp +\fBrequest_cursor_information\fR +.sp +\fBrequest_tabstops\fR +.sp \fBtitleset\fR \fIwindowtitles\fR .sp +\fBis_sgr_reset\fR \fIcode\fR +.sp +\fBhas_sgr_leadingreset\fR \fIcode\fR +.sp \fBdetect\fR \fItext\fR .sp \fBdetect_csi\fR \fItext\fR @@ -334,6 +378,10 @@ package require \fBpunk::ansi \fR .sp \fBlength\fR \fItext\fR .sp +\fBVIEW\fR \fIstring\fR +.sp +\fBCOUNT\fR \fIstring\fR +.sp \fBindex\fR \fIstring\fR \fIindex\fR .sp .BE @@ -360,7 +408,9 @@ Sticking to ansi codes where possible may be better for cross-platform and remot .PP packages used by punk::ansi .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR +.IP \(bu +\fBpunk::char\fR .PP .SH API .SS "NAMESPACE PUNK::ANSI" @@ -370,6 +420,16 @@ Core API functions for punk::ansi \fBstripansi\fR \fItext\fR .sp Return a string with ansi codes stripped out +.sp +Alternate graphics chars are replaced with modern unicode equivalents (e\&.g boxdrawing glyphs) +.TP +\fBstripansi\fR \fItext\fR +.sp +Return a string with ansi codes stripped out +.sp +Alternate graphics modes will be stripped - exposing the raw characters as they appear without graphics mode\&. +.sp +ie instead of a horizontal line you may see: qqqqqq .TP \fBa?\fR ?ansicode\&.\&.\&.? .sp @@ -405,6 +465,22 @@ 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 @@ -474,6 +550,59 @@ A string created by any move_emit_return for punk::ansi would not behave in an i .TP \fBmove_down\fR \fIn\fR .TP +\fBmove_column\fR \fIcol\fR +.TP +\fBmove_row\fR \fIrow\fR +.sp +VPA - Vertical Line Position Absolute +.TP +\fBcursor_save\fR +.sp +equivalent term::ansi::code::ctrl::sc +.sp +This is the ANSI/SCO cursor save as opposed to the DECSC version +.sp +On many terminals either will work - but cursor_save_dec is shorter and perhaps more widely supported +.TP +\fBcursor_restore\fR +.sp +equivalent term::ansi::code::ctrl::rc +.sp +ANSI/SCO - see also cursor_restore_dec for the DECRC version +.TP +\fBcursor_save_dec\fR +.sp +equivalent term::ansi::code::ctrl::sca +.sp +DECSC +.TP +\fBcursor_restore_attributes\fR +.sp +equivalent term::ansi::code::ctrl::rca +.sp +DECRC +.TP +\fBenable_line_wrap\fR +.sp +enable automatic line wrapping when characters entered beyond rightmost column +.sp +This will also allow forward movements to move to subsequent lines +.sp +This is DECAWM - and is the same sequence output by 'tput smam' +.TP +\fBdisable_line_wrap\fR +.sp +disable automatic line wrapping +.sp +reset DECAWM - same sequence output by 'tput rmam' +tput rmam +.TP +\fBquery_mode_line_wrap\fR +.sp +DECRQM to query line-wrap state +.sp +The punk::ansi::query_mode_ functions just emit the ansi query sequence\&. +.TP \fBerase_line\fR .TP \fBerase_sol\fR @@ -482,6 +611,20 @@ Erase to start of line, leaving cursor position alone\&. .TP \fBerase_eol\fR .TP +\fBscroll_up\fR \fIn\fR +.TP +\fBscroll_down\fR \fIn\fR +.TP +\fBinsert_spaces\fR \fIcount\fR +.TP +\fBdelete_characters\fR \fIcount\fR +.TP +\fBerase_characters\fR \fIcount\fR +.TP +\fBinsert_lines\fR \fIcount\fR +.TP +\fBdelete_lines\fR \fIcount\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 @@ -494,12 +637,44 @@ These functions will emit the code - but read it in from stdin so that it doesn' .sp The punk::ansi::cursor_pos function is used by punk::console::get_cursor_pos and punk::console::get_cursor_pos_list .TP +\fBrequest_cursor_information\fR +.sp +DECRQPSR (DEC Request Presentation State Report) for DECCCIR Cursor Information report +.sp +When written to the terminal, this sequence causes the terminal to emit cursor information to stdin +.sp +A stdin readloop will need to be in place to read this information +.TP +\fBrequest_tabstops\fR +.sp +DECRQPSR (DEC Request Presentation State Report) for DECTABSR Tab stop report +.sp +When written to the terminal, this sequence causes the terminal to emit tabstop information to stdin +.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::CODETYPE" +.PP +API functions for punk::ansi::codetype +.PP +Utility functions for processing ansi code sequences +.TP +\fBis_sgr_reset\fR \fIcode\fR +.sp +Return a boolean indicating whether this string has a trailing pure SGR reset +.sp +Note that if the reset is not the very last item in the string - it will not be detected\&. +.sp +This is primarily intended for testing a single ansi code sequence, but code can be any string where the trailing SGR code is to be tested\&. +.TP +\fBhas_sgr_leadingreset\fR \fIcode\fR +.sp +The reset must be the very first item in code to be detected\&. Trailing strings/codes ignored\&. +.PP .SS "NAMESPACE PUNK::ANSI::TA" .PP text ansi functions @@ -551,7 +726,36 @@ Return the character length after stripping ansi codes - not the printing length .PP .SS "NAMESPACE PUNK::ANSI::ANSISTRING" .PP -punk::ansi::string ensemble +punk::ansi::ansistring ensemble - ansi-aware string operations +.PP +Working with strings containing ansi in a way that preserves/understands the codes is always going to be significantly slower than working with plain strings +.PP +Just as working with other forms of markup such as HTML - you simply need to be aware of the tradeoffs and design accordingly\&. +.TP +\fBVIEW\fR \fIstring\fR +.sp +Return a string with specific ANSI control characters substituted with visual equivalents frome the appropriate unicode C0 and C1 visualisation sets +.sp +For debugging purposes, certain other standard control characters are converted to visual representation, for example backspace (mapped to \\\\U2408 '\\U2408') +.sp +Horizontal tab is mapped to \\\\U2409 '\\U2409'\&. For many of the punk terminal text operations, tabs have already been mapped to the appropriate number of spaces using textutil::tabify functions +.sp +As punkshell uses linefeed where possible in preference to crlf even on windows, cr is mapped to \\\\U240D '\\U240D' - but lf is left as is\&. +.TP +\fBCOUNT\fR \fIstring\fR +.sp +Returns the count of visible graphemes and non-ansi control characters +.sp +Incomplete! grapheme clustering support not yet implemented - only diacritics are currently clustered to count as one grapheme\&. +.sp +This will not count strings hidden inside a 'privacy message' or other ansi codes which may have content between their opening escape and their termination sequence\&. +.sp +This is not quite equivalent to calling string length on the result of stripansi $string due to diacritics and/or grapheme combinations +.sp +Note that this returns the number of characters in the payload (after applying combiners) +It is not always the same as the width of the string as rendered on a terminal due to 2wide Unicode characters and the usual invisible control characters such as \\r and \\n +.sp +To get the width, use punk::ansi::printing_length instead, which is also ansi aware\&. .TP \fBindex\fR \fIstring\fR \fIindex\fR .sp 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 index 6983f3fb..2dfc5097 100644 --- 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 @@ -347,7 +347,7 @@ Serious consideration should be given to using TEPAM if suitable for your projec .PP packages used by punk::args .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .PP .SH API .SS "NAMESPACE PUNK::ARGS::CLASS" diff --git a/src/embedded/man/files/_module_overtype-1.5.3.tm.n b/src/embedded/man/files/punk/_module_assertion-0.1.0.tm.n similarity index 75% rename from src/embedded/man/files/_module_overtype-1.5.3.tm.n rename to src/embedded/man/files/punk/_module_assertion-0.1.0.tm.n index b400c597..b40b48e6 100644 --- a/src/embedded/man/files/_module_overtype-1.5.3.tm.n +++ b/src/embedded/man/files/punk/_module_assertion-0.1.0.tm.n @@ -1,8 +1,8 @@ '\" -'\" Generated from file '_module_overtype-1\&.5\&.3\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Generated from file '_module_assertion-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2024 '\" -.TH "overtype_module_overtype" 0 1\&.5\&.3 doc "overtype text layout" +.TH "shellspy_module_punk::assertion" 0 0\&.1\&.0 doc "per-namespace assertions with" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -272,39 +272,55 @@ Database Class: \\fB\\$3\\fR .. .BS .SH NAME -overtype_module_overtype \- overtype text layout - ansi aware +shellspy_module_punk::assertion \- assertion alternative to control::assert .SH SYNOPSIS -package require \fBovertype \fR +package require \fBpunk::assertion \fR .sp .BE .SH DESCRIPTION .PP -- +The punk::assertion library has the same semantics as Tcllib's control::assert library for the assert command itself\&. +.PP +The main difference is the way in which assert is enabled/disabled in namespaces\&. +.PP +Due to commands such as 'namespace path' - the assert command could be available in arbitrary namespaces unrelated by tree structure to namespaces where assert has been directly imported\&. +.PP +punk::assertion::active 0|1 allows activating and deactivating assertions in any namespace where the assert command is available - but only affecting the activations state of the namespace in which it is called\&. +.PP +If such a non-primary assertion namespace never had active set to 0 or 1 - then it will activate/deactivate when the namespace corresponding to the found assert command (primary) is activated/deactivated\&. +.PP +Once marked active or inactive - such a non-primary namespace will no longer follow the primary .SH OVERVIEW .PP -overview of overtype +overview of punk::assertion .SS CONCEPTS .PP - .SS DEPENDENCIES .PP -packages used by overtype +packages used by punk::assertion .IP \(bu \fBTcl 8\&.6\fR -.IP \(bu -\fBtextutil\fR -.IP \(bu -\fBpunk::ansi\fR -.sp -- required to detect, split, strip and calculate lengths of text possibly containing ansi codes -.IP \(bu -\fBpunk::char\fR -.sp -- box drawing - and also unicode character width determination for proper layout of text with double-column-width chars .PP .SH API +.SS "NAMESPACE PUNK::ASSERTION::CLASS" +.PP +class definitions +.PP +.SS "NAMESPACE PUNK::ASSERTION" +.PP +Core API functions for punk::assertion +.PP +.SS "NAMESPACE PUNK::ASSERTION::LIB" +.PP +Secondary functions that are part of the API +.PP +.SH INTERNAL +.SS "NAMESPACE PUNK::ASSERTION::SYSTEM" +.PP +Internal functions that are not part of the API .SH KEYWORDS -ansi, module, text +assert, assertion, debug, module .SH COPYRIGHT .nf Copyright (c) 2024 diff --git a/src/embedded/man/files/_module_overtype-1.5.2.tm.n b/src/embedded/man/files/punk/_module_basictelnet-0.1.0.tm.n similarity index 84% rename from src/embedded/man/files/_module_overtype-1.5.2.tm.n rename to src/embedded/man/files/punk/_module_basictelnet-0.1.0.tm.n index d46b6ea2..0c0707e9 100644 --- a/src/embedded/man/files/_module_overtype-1.5.2.tm.n +++ b/src/embedded/man/files/punk/_module_basictelnet-0.1.0.tm.n @@ -1,8 +1,8 @@ '\" -'\" Generated from file '_module_overtype-1\&.5\&.2\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Generated from file '_module_basictelnet-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2024 '\" -.TH "overtype_module_overtype" 0 1\&.5\&.2 doc "overtype text layout" +.TH "shellspy_module_punk::basictelnet" 0 0\&.1\&.0 doc "basic telnet client" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -272,39 +272,45 @@ Database Class: \\fB\\$3\\fR .. .BS .SH NAME -overtype_module_overtype \- overtype text layout - ansi aware +shellspy_module_punk::basictelnet \- basic telnet client - DKF/Wiki .SH SYNOPSIS -package require \fBovertype \fR +package require \fBpunk::basictelnet \fR .sp .BE .SH DESCRIPTION .PP -- +see https://wiki\&.tcl-lang\&.org/page/Tcl+Telnet .SH OVERVIEW .PP -overview of overtype +overview of punk::basictelnet .SS CONCEPTS .PP - .SS DEPENDENCIES .PP -packages used by overtype +packages used by punk::basictelnet .IP \(bu \fBTcl 8\&.6\fR -.IP \(bu -\fBtextutil\fR -.IP \(bu -\fBpunk::ansi\fR -.sp -- required to detect, split, strip and calculate lengths of text possibly containing ansi codes -.IP \(bu -\fBpunk::char\fR -.sp -- box drawing - and also unicode character width determination for proper layout of text with double-column-width chars .PP .SH API +.SS "NAMESPACE PUNK::BASICTELNET::CLASS" +.PP +class definitions +.PP +.SS "NAMESPACE PUNK::BASICTELNET" +.PP +Core API functions for punk::basictelnet +.PP +.SS "NAMESPACE PUNK::BASICTELNET::LIB" +.PP +Secondary functions that are part of the API +.PP +.SH INTERNAL +.SS "NAMESPACE PUNK::BASICTELNET::SYSTEM" +.PP +Internal functions that are not part of the API .SH KEYWORDS -ansi, module, text +module .SH COPYRIGHT .nf Copyright (c) 2024 diff --git a/src/embedded/man/files/punk/_module_encmime-0.1.0.tm.n b/src/embedded/man/files/punk/_module_encmime-0.1.0.tm.n index 4eb296ce..3eee681e 100644 --- a/src/embedded/man/files/punk/_module_encmime-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_encmime-0.1.0.tm.n @@ -304,7 +304,7 @@ This pseudo-package was created to minimize dependencies for punk::char and punk .PP packages used by punk::encmime .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .PP .SH API .SS "NAMESPACE PUNK::ENCMIME::CLASS" 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 0187fdb8..dc6d49cf 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 @@ -373,7 +373,7 @@ CR line-endings that are intended to be interpreted as such should be mapped to .PP packages needed by punk::fileline .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .IP \(bu \fBpunk::args\fR .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 2ad83e2d..066c1d21 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 @@ -290,7 +290,7 @@ Experiments in functional program related features and integration with the patt .PP packages used by punk::flib .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .IP \(bu \fBpattern 1\&.2\&.4\fR .PP diff --git a/src/embedded/man/files/punk/_module_lib-0.1.0.tm.n b/src/embedded/man/files/punk/_module_lib-0.1.1.tm.n similarity index 70% rename from src/embedded/man/files/punk/_module_lib-0.1.0.tm.n rename to src/embedded/man/files/punk/_module_lib-0.1.1.tm.n index d7404601..af00fd15 100644 --- a/src/embedded/man/files/punk/_module_lib-0.1.0.tm.n +++ b/src/embedded/man/files/punk/_module_lib-0.1.1.tm.n @@ -1,8 +1,8 @@ '\" -'\" Generated from file '_module_lib-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Generated from file '_module_lib-0\&.1\&.1\&.tm\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2024 '\" -.TH "punkshell_module_punk::lib" 0 0\&.1\&.0 doc "punk library" +.TH "punkshell_module_punk::lib" 0 0\&.1\&.1 doc "punk library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -276,8 +276,18 @@ punkshell_module_punk::lib \- punk general utility functions .SH SYNOPSIS package require \fBpunk::lib \fR .sp +\fBlremove\fR \fIlist\fR ?index \&.\&.\&.? +.sp +\fBlpop\fR \fIlistvar\fR ?index? +.sp \fBK\fR \fIx\fR \fIy\fR .sp +\fBis_utf8_multibyteprefix\fR \fIstr\fR +.sp +\fBis_utf8_single\fR \fI1234bytes\fR +.sp +\fBget_utf8_leading\fR \fIrawbytes\fR +.sp \fBhex2dec\fR ?option value\&.\&.\&.? \fIlist_largeHex\fR .sp \fBdex2hex\fR ?option value\&.\&.\&.? \fIlist_decimals\fR @@ -312,6 +322,14 @@ package require \fBpunk::lib \fR .sp \fBaskuser\fR \fIquestion\fR .sp +\fBlinesort\fR ?sortoption ?val?\&.\&.\&.? \fItextblock\fR +.sp +\fBlist_as_lines\fR ?-joinchar char? \fIlinelist\fR +.sp +\fBlines_as_list\fR ?option value \&.\&.\&.? \fItext\fR +.sp +\fBopts_values\fR ?option value\&.\&.\&.? \fIoptionspecs\fR \fIrawargs\fR +.sp .BE .SH DESCRIPTION .PP @@ -332,13 +350,29 @@ This requirement for no strong dependencies, means that many utility functions t .PP packages used by punk::lib .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .PP .SH API .SS "NAMESPACE PUNK::LIB::CLASS" .PP class definitions .PP +.SS "NAMESPACE PUNK::LIB::COMPAT" +.PP +compatibility functions for features that may not be available in earlier Tcl versions +.PP +These are generally 'forward compatibility' functions ie allowing earlier versions to use later features/idioms by using a Tcl-only version of a missing builtin\&. +.PP +Such Tcl-only versions will inevitably be less performant - perhaps significantly so\&. +.TP +\fBlremove\fR \fIlist\fR ?index \&.\&.\&.? +.sp +Forwards compatible lremove for versions 8\&.6 or less to support equivalent 8\&.7 lremove +.TP +\fBlpop\fR \fIlistvar\fR ?index? +.sp +Forwards compatible lpop for versions 8\&.6 or less to support equivalent 8\&.7 lpop +.PP .SS "NAMESPACE PUNK::LIB" .PP Core API functions for punk::lib @@ -351,6 +385,40 @@ see \fIhttps://wiki\&.tcl-lang\&.org/page/K\fR .sp It is used in cases where command-substitution at the calling-point performs some desired effect\&. .TP +\fBis_utf8_multibyteprefix\fR \fIstr\fR +.sp +Returns a boolean if str is potentially a prefix for a multibyte utf-8 character +.sp +ie - tests if it is possible that appending more data will result in a utf-8 codepoint +.sp +Will return false for an already complete utf-8 codepoint +.sp +It is assumed the incomplete sequence is at the beginning of the bytes argument +.sp +Suitable input for this might be from the unreturned tail portion of get_utf8_leading $testbytes +.sp +e\&.g using: set head [get_utf8_leading $testbytes] ; set tail [string range $testbytes [string length $head] end] +.TP +\fBis_utf8_single\fR \fI1234bytes\fR +.sp +Tests input of 1,2,3 or 4 bytes and responds with a boolean indicating if it is a valid utf-8 character (codepoint) +.TP +\fBget_utf8_leading\fR \fIrawbytes\fR +.sp +return the leading portion of rawbytes that is a valid utf8 sequence\&. +.sp +This will stop at the point at which the bytes can't be interpreted as a complete utf-8 codepoint +.sp +e\&.g It will not return the first byte or 2 of a 3-byte utf-8 character if the last byte is missing, and will return only the valid utf-8 string from before the first byte of the incomplete character\&. +.sp +It will also only return the prefix before any bytes that cannot be part of a utf-8 sequence at all\&. +.sp +Note that while this will return valid utf8 - it has no knowledge of grapheme clusters or diacritics +.sp +This means if it is being used to process bytes split at some arbitrary point - the trailing data that isn't returned could be part of a grapheme cluster that belongs with the last character of the leading string already returned +.sp +The utf-8 BOM \\xEF\\xBB\\xBF is a valid UTF8 3-byte sequence and so can also be returned as part of the leading utf8 bytes +.TP \fBhex2dec\fR ?option value\&.\&.\&.? \fIlist_largeHex\fR .sp Convert a list of (possibly large) unprefixed hex strings to their decimal values @@ -487,12 +555,16 @@ This function merges the two dicts whilst maintaining the key order of main foll .TP \fBaskuser\fR \fIquestion\fR .sp -A very basic utility to read an answer from stdin +A basic utility to read an answer from stdin .sp The prompt is written to the terminal and then it waits for a user to type something .sp stdin is temporarily configured to blocking and then put back in its original state in case it wasn't already so\&. .sp +If the terminal is using punk::console and is in raw mode - the terminal will temporarily be put in line mode\&. +.sp +(Generic terminal raw vs linemode detection not yet present) +.sp The user must hit enter to submit the response .sp The return value is the string if any that was typed prior to hitting enter\&. @@ -509,6 +581,57 @@ The question argument can be manually colourised using the various punk::ansi fu } .CE +.TP +\fBlinesort\fR ?sortoption ?val?\&.\&.\&.? \fItextblock\fR +.sp +Sort lines in textblock +.sp +Returns another textblock with lines sorted +.sp +options are flags as accepted by lsort ie -ascii -command -decreasing -dictionary -index -indices -integer -nocase -real -stride -unique +.TP +\fBlist_as_lines\fR ?-joinchar char? \fIlinelist\fR +.sp +This simply joines the elements of the list with -joinchar +.sp +It is mainly intended for use in pipelines where the primary argument comes at the end - but it can also be used as a general replacement for join $lines +.sp +The sister function lines_as_list takes a block of text and splits it into lines - but with more options related to trimming the block and/or each line\&. +.TP +\fBlines_as_list\fR ?option value \&.\&.\&.? \fItext\fR +.sp +Returns a list of possibly trimmed lines depeding on options +.sp +The concept of lines is raw lines from splitting on newline after crlf is mapped to lf +.sp +- not console lines which may be entirely different due to control characters such as vertical tabs or ANSI movements +.TP +\fBopts_values\fR ?option value\&.\&.\&.? \fIoptionspecs\fR \fIrawargs\fR +.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) - but with multiline values allowed if properly quoted/braced +.sp +\'info complete' is used to determine if a record spans multiple lines due to multiline values +.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 .SH INTERNAL .SS "NAMESPACE PUNK::LIB::SYSTEM" 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 e6555545..b19894fe 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 @@ -298,7 +298,7 @@ Filesystem path utility functions .PP packages used by punk::path .IP \(bu -\fBTcl 8\&.6\fR +\fBTcl 8\&.6-\fR .PP .SH API .SS "NAMESPACE PUNK::PATH::CLASS" diff --git a/src/embedded/man/files/punk/_module_sshrun-0.1.0.tm.n b/src/embedded/man/files/punk/_module_sshrun-0.1.0.tm.n new file mode 100644 index 00000000..c6415726 --- /dev/null +++ b/src/embedded/man/files/punk/_module_sshrun-0.1.0.tm.n @@ -0,0 +1,482 @@ +'\" +'\" Generated from file '_module_sshrun-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 +'\" +.TH "shellspy_module_punk::sshrun" 0 0\&.1\&.0 doc "punk::sshrun tclssh clone" +.\" 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 +shellspy_module_punk::sshrun \- Tcl procedures to execute tcl scripts in remote hosts +.SH SYNOPSIS +package require \fBpunk::sshrun \fR +.sp +connect \fIargs\fR +.sp +disconnect \fIhost\fR +.sp +push \fIhost\fR \fIscript\fR +.sp +send \fIhost\fR +.sp +send_exit \fIhost\fR +.sp +send_exit \fIhost\fR +.sp +pop_all \fIhost\fR \fIoutput_varname\fR +.sp +pop_read \fIhost\fR \fInumbytes\fR \fIoutput_varname\fR +.sp +hfileevent \fIhost\fR \fIreadable_writable\fR \fIscript\fR +.sp +hconfigure \fIhost\fR \fIargs\fR +.sp +rexec \fIhost\fR \fIscript\fR \fIoutput_varname\fR +.sp +get_filehandle \fIhost\fR +.sp +.BE +.SH DESCRIPTION +.PP +This is a clone of tclssh by Jose F\&. Nieves +.PP +The original repo is at: https://bitbucket\&.org/noaaport/tclssh/src/master/ +.PP +This version is namespaced under punk::sshrun specifically for the Punk shell project - and may lag the original project or diverge\&. +.PP +You are encouraged to use the original Tclssh source from the above URL for your own projects +.SH OVERVIEW +.PP +overview of punk::sshrun +.PP +SYNOPSIS +.PP +package require punk::sshrun +.PP +- +.PP +punk::sshrun::connect [-t ] [-- ] [@] +.PP +Defaults: -t tclsh +.SS CONCEPTS +.PP +- +.SS DEPENDENCIES +.PP +packages used by punk::sshrun +.IP \(bu +\fBTcl 8\&.6\fR +.IP \(bu +\fBcmdline\fR +.PP +.SH API +.SS "NAMESPACE PUNK::SSHRUN::CLASS" +.PP +class definitions +.PP +.SS "NAMESPACE PUNK::SSHRUN" +.PP +Core API functions for punk::sshrun +.TP +connect \fIargs\fR +.sp +Must be called first\&. +.sp +This proc opens an io channel to the tclsh in the remote host (via ssh) that is kept in an internal variable for subsequent use\&. +.sp +The file handle can be retrieved if desired through the command: get_filehandle {host} +.TP +disconnect \fIhost\fR +.sp +Must be called last\&. Closes the filehandle opened by connect\&. +.TP +push \fIhost\fR \fIscript\fR +.sp +