Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Started to fill in the documentation for packages 'ask', 'color', 'tty', and 'pager' |
---|---|
Timelines: | family | ancestors | descendants | both | doc-expansion |
Files: | files | file ages | folders |
SHA1: |
912d9503509fedb62de50cc3461040e1 |
User & Date: | andreask 2015-04-17 01:10:41.548 |
Context
2015-04-17
| ||
01:51 | Completed new docs check-in: 57fc520fe4 user: andreask tags: doc-expansion | |
01:10 | Started to fill in the documentation for packages 'ask', 'color', 'tty', and 'pager' check-in: 912d950350 user: andreask tags: doc-expansion | |
2015-03-06
| ||
20:44 | Fix bug in history mgmt for a save-file in a directory. Ensure that the directory exists before writing/creating the file itself. check-in: 06c0827602 user: andreask tags: trunk | |
Changes
Added doc/cmdr_ask.man.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | [comment {-*- tcl -*- doctools manpage}] [include parts/definitions.inc] [manpage_begin [vset LABEL_ASK] [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [require cmdr::color] [require linenoise] [require struct::matrix] [require textutil::adjust] [require try] [require cmdr::ask] [titledesc [vset TITLE_ASK]] [description] [include parts/welcome.inc] This package provides a few utility commands implementing a few simple terminal-based interactions with the user. [section API] [list_begin definitions] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method string] [arg query] [opt [arg default]]] When invoked this command prompts the user with [arg query] for a string. If the [arg default] is specified and not the empty string it is also shown as part of the prompt. Note that [arg default] defaults to the empty string. [para] The interactively entered string is returned as the result of the command. The [arg default] is returned as the result if the user entered an empty string and the [arg default] is not empty. [list_begin arguments] [arg_def string query] The prompt to show to the user before interaction begins. [arg_def string default] The default to return if the user enters nothing. [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method string/extended] [arg query] [opt options...]] This command is similar to [cmd {::cmdr::ask string}], except it allows for more customization of the interaction through options. [para] The accepted options are [list_begin options] [opt_def -history boolean] If [const true], save user input into [package linenoise]'s in-memory history. Default is [const false]. [opt_def -hidden boolean] If [const true], input is hidden. Default is [const false], visible echo. [opt_def -complete cmdprefix] If not empty, installed as completion callback. [opt_def -default string] If not empty the string to return if the user enters the empty string. [list_end] [list_begin arguments] [arg_def string query] The prompt to show to the user before interaction begins. [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method string*] [arg query]] Behaves like [cmd {::cmdr::ask string}] without a default, except that the user's input is not echoed back to the terminal. This command is for the entry of hidden strings, i.e. passwords, and the like. [list_begin arguments] [arg_def string query] The prompt to show to the user before interaction begins. [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method yn] [arg query] [opt [arg default]]] When invoked this command prompts the user with [arg query] for a [emph boolean] value/string. If the [arg default] is specified and not the empty string it is also shown as part of the prompt. Note that [arg default] defaults to the empty string. [para] The interactively entered boolean is returned as the result of the command. The [arg default] boolean is returned as the result if the user entered an empty string and the [arg default] is not empty. [para] Note that the command will not return until the user entered a valid boolean value. Entering a non-boolean string causes the command to loop internally and re-prompt. [list_begin arguments] [arg_def string query] The prompt to show to the user before interaction begins. [arg_def string default] The default boolean to return if the user enters nothing. [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method choose] [arg query] [arg choices] [opt [arg default]] When invoked this command prompts the user with [arg query] for one of the [arg choices], entered as string. Prompt and input happen on a single line. [para] The interactively entered choice is returned as the result of the command. The [arg default] choice is returned as the result if the user entered an empty string and the [arg default] is not empty. [para] Note that the command will not return until the user entered a valid choice. Entering a non-choice causes the command to loop internally and re-prompt. The user is supported in entry by an internal completion callback. [list_begin arguments] [arg_def string query] The prompt to show to the user before interaction begins. [arg_def string default] The default boolean to return if the user enters nothing. [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::ask] [method menu] [arg header] [arg prompt] [arg choices] [opt [arg default]] Similar to [cmd {::cmdr::ask choice}], except that the [arg choices] are shown as an enumerated menu, one per line, with a leading [arg header]. Furthermore the command accepts not only the choices as input, but also their numeric indices in the menu. The result however is always the relevant chosen string. [list_end] [include parts/feedback.inc] [manpage_end] |
Added doc/cmdr_color.man.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | [comment {-*- tcl -*- doctools manpage}] [include parts/definitions.inc] [manpage_begin [vset LABEL_COLOR] [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [require cmdr::tty] [require cmdr::color] [titledesc [vset TITLE_COLOR]] [description] [include parts/welcome.inc] This package provides a few utility commands implementing the management of terminal colors. [section API] [list_begin definitions] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] When invoked this command [para] The ... is returned as the result of the command. [list_begin arguments] [arg_def list list] ... [list_end] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::color] [method ...] ...] [list_end] [include parts/feedback.inc] [manpage_end] |
Added doc/cmdr_pager.man.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 | [comment {-*- tcl -*- doctools manpage}] [include parts/definitions.inc] [manpage_begin [vset LABEL_PAGER] [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [require linenoise] [require cmdr::tty] [require cmdr::pager] [titledesc [vset TITLE_PAGER]] [description] [include parts/welcome.inc] This package provides a single utility command to manage the automatic paging of long output, like [vset PROJECT]'s automatic help. [section API] [list_begin definitions] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::pager] [method text]] When invoked this command either simply prints the [arg text] to stdout, or invokes an external pager application to manage the output. [para] The pager is only invoked when [list_begin enumerated] [enum] Stdout is a terminal, and [enum] The text does not fit into the height of the terminal, and [enum] a pager application could be found. [list_end] [para] If any of the above conditions fail the text is simply printed. [para] When the command comes to the third condition above it will look for the pager specified in the environment variable [const PAGER] first, and then [const less] and [const more], in this order. [list_begin arguments] [arg_def string text] The text to print or page. [list_end] [para] The result of the command is the empty string. [list_end] [include parts/feedback.inc] [manpage_end] |
Added doc/cmdr_tty.man.
> > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | [comment {-*- tcl -*- doctools manpage}] [include parts/definitions.inc] [manpage_begin [vset LABEL_TTY] [vset MAN_SECTION] [vset VERSION]] [include parts/module.inc] [require Tclx] [require cmdr::tty] [titledesc [vset TITLE_TTY]] [description] [include parts/welcome.inc] This package provides a single utility command testing if the [const stdout] [term channel] is a tty or not, and reporting the result. [section API] [list_begin definitions] [comment {- - -- --- ----- -------- -------------}] [call [cmd ::cmdr::tty] [method stdout]] When invoked this command returns a boolean value indicating if the [const stdout] [term channel] is a tty ([const true]), or not ([const false]). [list_end] [include parts/feedback.inc] [manpage_end] |
Changes to doc/parts/definitions.inc.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | [include configuration.inc] [vset TITLE_INTRO "[vset PTITLE] - Introduction to the project"] [vset TITLE_LICENSE "[vset PTITLE] - License" ] [vset TITLE_CHANGES "[vset PTITLE] - Log of Changes" ] [vset TITLE_SOURCES "[vset PTITLE] - How To Get The Sources" ] [vset TITLE_INSTALL "[vset PTITLE] - The Installer's Guide" ] [vset TITLE_DEV "[vset PTITLE] - The Developer's Guide" ] [comment {- Custom documents & titles - - -- --- ----- --------}] [vset TITLE_MAIN "[vset PTITLE] - Main package and API"] [vset TITLE_ACTOR "[vset PTITLE] - (Internal) Base class for officers and privates"] [vset TITLE_CONFIG "[vset PTITLE] - (Partially internal) Collection of parameters for privates"] [vset TITLE_DEV_COMPLETE "[vset PTITLE] - Internals of command line completion"] [vset TITLE_DEV_DSL "[vset PTITLE] - Internals of DSL handling"] [vset TITLE_DEV_HF "[vset PTITLE] - Writing custom help formats"] [vset TITLE_DEV_VT "[vset PTITLE] - Writing custom validation types"] [vset TITLE_DSL "[vset PTITLE] - Introduction to the Specification Language"] [vset TITLE_DSL_OFFICER "[vset PTITLE] - Officer Specification Language"] [vset TITLE_DSL_PRIVATE "[vset PTITLE] - Private Specification Language"] [vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"] [vset TITLE_HELP "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"] [vset TITLE_HELP_JSON "[vset PTITLE] - Formatting help as JSON object"] [vset TITLE_HELP_SQL "[vset PTITLE] - Formatting help as series of SQL commands"] [vset TITLE_HELP_TCL "[vset PTITLE] - Formatting help as Tcl data structure"] [vset TITLE_OFFICER "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."] [vset TITLE_PARAMETER "[vset PTITLE] - (Partially internal) Command parameters"] [vset TITLE_PRIVATE "[vset PTITLE] - (Internal) Single command handling, options, and arguments"] [vset TITLE_UTIL "[vset PTITLE] - (Internal) General Utilities"] [vset TITLE_VALIDATE "[vset PTITLE] - Standard validation types for parameters"] [vset TITLE_VCOMMON "[vset PTITLE] - Utilities for Validation Types"] [vset TITLE_FLOW "[vset PTITLE] - Runtime Processing Flow"] [comment {- Miscellanea ............. - - -- --- ----- --------}] [vset LABEL_INTRO [vset PROJECT]-introduction] [vset LABEL_LICENSE [vset PROJECT]-license] [vset LABEL_CHANGES [vset PROJECT]-changes] [vset LABEL_SOURCES [vset PROJECT]-howto-get-sources] [vset LABEL_INSTALL [vset PROJECT]-installation] [vset LABEL_DEV [vset PROJECT]_development] [vset LABEL_MAIN [vset PROJECT]] [vset LABEL_ACTOR [vset PROJECT]::actor] [vset LABEL_CONFIG [vset PROJECT]::config] [vset LABEL_DEV_COMPLETE [vset PROJECT]_dev~completion] [vset LABEL_DEV_DSL [vset PROJECT]_dev~dsl] [vset LABEL_HELPFORMATS [vset PROJECT]-user-helpformats] [vset LABEL_VTYPES [vset PROJECT]-user-vtypes] [vset LABEL_DSL [vset PROJECT]-spec-dsl] [vset LABEL_DSL_OFFICER [vset PROJECT]-spec-dsl-officer] [vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter] [vset LABEL_DSL_PRIVATE [vset PROJECT]-spec-dsl-private] [vset LABEL_HELP [vset PROJECT]::help] [vset LABEL_HELP_JSON [vset PROJECT]::help::json] [vset LABEL_HELP_SQL [vset PROJECT]::help::sql] [vset LABEL_HELP_TCL [vset PROJECT]::help::tcl] [vset LABEL_OFFICER [vset PROJECT]::officer] [vset LABEL_PARAMETER [vset PROJECT]::parameter] [vset LABEL_PRIVATE [vset PROJECT]::private] [vset LABEL_UTIL [vset PROJECT]::util] [vset LABEL_VALIDATE [vset PROJECT]::validate] [vset LABEL_VCOMMON [vset PROJECT]::validate::common] [vset LABEL_FLOW [vset PROJECT]-spec-flow] | > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | [include configuration.inc] [vset TITLE_INTRO "[vset PTITLE] - Introduction to the project"] [vset TITLE_LICENSE "[vset PTITLE] - License" ] [vset TITLE_CHANGES "[vset PTITLE] - Log of Changes" ] [vset TITLE_SOURCES "[vset PTITLE] - How To Get The Sources" ] [vset TITLE_INSTALL "[vset PTITLE] - The Installer's Guide" ] [vset TITLE_DEV "[vset PTITLE] - The Developer's Guide" ] [comment {- Custom documents & titles - - -- --- ----- --------}] [vset TITLE_MAIN "[vset PTITLE] - Main package and API"] [vset TITLE_ACTOR "[vset PTITLE] - (Internal) Base class for officers and privates"] [vset TITLE_ASK "[vset PTITLE] - Terminal-based simple user interactions"] [vset TITLE_COLOR "[vset PTITLE] - Terminal colors"] [vset TITLE_CONFIG "[vset PTITLE] - (Partially internal) Collection of parameters for privates"] [vset TITLE_DEV_COMPLETE "[vset PTITLE] - Internals of command line completion"] [vset TITLE_DEV_DSL "[vset PTITLE] - Internals of DSL handling"] [vset TITLE_DEV_HF "[vset PTITLE] - Writing custom help formats"] [vset TITLE_DEV_VT "[vset PTITLE] - Writing custom validation types"] [vset TITLE_DSL "[vset PTITLE] - Introduction to the Specification Language"] [vset TITLE_DSL_OFFICER "[vset PTITLE] - Officer Specification Language"] [vset TITLE_DSL_PRIVATE "[vset PTITLE] - Private Specification Language"] [vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"] [vset TITLE_HELP "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"] [vset TITLE_HELP_JSON "[vset PTITLE] - Formatting help as JSON object"] [vset TITLE_HELP_SQL "[vset PTITLE] - Formatting help as series of SQL commands"] [vset TITLE_HELP_TCL "[vset PTITLE] - Formatting help as Tcl data structure"] [vset TITLE_OFFICER "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."] [vset TITLE_PAGER "[vset PTITLE] - Paging long output"] [vset TITLE_PARAMETER "[vset PTITLE] - (Partially internal) Command parameters"] [vset TITLE_PRIVATE "[vset PTITLE] - (Internal) Single command handling, options, and arguments"] [vset TITLE_TTY "[vset PTITLE] - Check if stdin is a tty, i.e. terminal"] [vset TITLE_UTIL "[vset PTITLE] - (Internal) General Utilities"] [vset TITLE_VALIDATE "[vset PTITLE] - Standard validation types for parameters"] [vset TITLE_VCOMMON "[vset PTITLE] - Utilities for Validation Types"] [vset TITLE_FLOW "[vset PTITLE] - Runtime Processing Flow"] [comment {- Miscellanea ............. - - -- --- ----- --------}] [vset LABEL_INTRO [vset PROJECT]-introduction] [vset LABEL_LICENSE [vset PROJECT]-license] [vset LABEL_CHANGES [vset PROJECT]-changes] [vset LABEL_SOURCES [vset PROJECT]-howto-get-sources] [vset LABEL_INSTALL [vset PROJECT]-installation] [vset LABEL_DEV [vset PROJECT]_development] [vset LABEL_MAIN [vset PROJECT]] [vset LABEL_ACTOR [vset PROJECT]::actor] [vset LABEL_ASK [vset PROJECT]::ask] [vset LABEL_COLOR [vset PROJECT]::color] [vset LABEL_CONFIG [vset PROJECT]::config] [vset LABEL_DEV_COMPLETE [vset PROJECT]_dev~completion] [vset LABEL_DEV_DSL [vset PROJECT]_dev~dsl] [vset LABEL_HELPFORMATS [vset PROJECT]-user-helpformats] [vset LABEL_VTYPES [vset PROJECT]-user-vtypes] [vset LABEL_DSL [vset PROJECT]-spec-dsl] [vset LABEL_DSL_OFFICER [vset PROJECT]-spec-dsl-officer] [vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter] [vset LABEL_DSL_PRIVATE [vset PROJECT]-spec-dsl-private] [vset LABEL_HELP [vset PROJECT]::help] [vset LABEL_HELP_JSON [vset PROJECT]::help::json] [vset LABEL_HELP_SQL [vset PROJECT]::help::sql] [vset LABEL_HELP_TCL [vset PROJECT]::help::tcl] [vset LABEL_OFFICER [vset PROJECT]::officer] [vset LABEL_PAGER [vset PROJECT]::pager] [vset LABEL_PARAMETER [vset PROJECT]::parameter] [vset LABEL_PRIVATE [vset PROJECT]::private] [vset LABEL_TTY [vset PROJECT]::tty] [vset LABEL_UTIL [vset PROJECT]::util] [vset LABEL_VALIDATE [vset PROJECT]::validate] [vset LABEL_VCOMMON [vset PROJECT]::validate::common] [vset LABEL_FLOW [vset PROJECT]-spec-flow] |