cmdr
Check-in [912d950350]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

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:912d9503509fedb62de50cc3461040e10c3aba98
User & Date: andreask 2015-04-17 01:10:41
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
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Added doc/cmdr_ask.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset LABEL_ASK] [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require cmdr::color]
            6  +[require linenoise]
            7  +[require struct::matrix]
            8  +[require textutil::adjust]
            9  +[require try]
           10  +[require cmdr::ask]
           11  +[titledesc [vset TITLE_ASK]]
           12  +[description]
           13  +[include parts/welcome.inc]
           14  +
           15  +This package provides a few utility commands implementing a few simple
           16  +terminal-based interactions with the user.
           17  +
           18  +[section API]
           19  +[list_begin definitions]
           20  +[comment {- - -- --- ----- -------- -------------}]
           21  +[call [cmd ::cmdr::ask] [method string] [arg query] [opt [arg default]]]
           22  +
           23  +When invoked this command prompts the user with [arg query] for a string.
           24  +If the [arg default] is specified and not the empty string it is also
           25  +shown as part of the prompt. Note that [arg default] defaults to the
           26  +empty string.
           27  +
           28  +[para] The interactively entered string is returned as the result of the
           29  +command. The [arg default] is returned as the result if the user entered
           30  +an empty string and the [arg default] is not empty.
           31  +
           32  +[list_begin arguments]
           33  +[arg_def string query] The prompt to show to the user before interaction begins.
           34  +[arg_def string default] The default to return if the user enters nothing.
           35  +[list_end]
           36  +
           37  +[comment {- - -- --- ----- -------- -------------}]
           38  +[call [cmd ::cmdr::ask] [method string/extended] [arg query] [opt options...]]
           39  +
           40  +This command is similar to [cmd {::cmdr::ask string}], except it allows for
           41  +more customization of the interaction through options.
           42  +
           43  +[para] The accepted options are
           44  +[list_begin options]
           45  +[opt_def -history  boolean]   If [const true], save user input into [package linenoise]'s in-memory history. Default is [const false].
           46  +[opt_def -hidden   boolean]   If [const true], input is hidden. Default is [const false], visible echo.
           47  +[opt_def -complete cmdprefix] If not empty, installed as completion callback.
           48  +[opt_def -default  string]    If not empty the string to return if the user enters the empty string.
           49  +[list_end]
           50  +
           51  +[list_begin arguments]
           52  +[arg_def string query] The prompt to show to the user before interaction begins.
           53  +[list_end]
           54  +
           55  +
           56  +[comment {- - -- --- ----- -------- -------------}]
           57  +[call [cmd ::cmdr::ask] [method string*] [arg query]]
           58  +
           59  +Behaves like [cmd {::cmdr::ask string}] without a default, except that the user's
           60  +input is not echoed back to the terminal. This command is for the entry of hidden
           61  +strings, i.e. passwords, and the like.
           62  +
           63  +[list_begin arguments]
           64  +[arg_def string query] The prompt to show to the user before interaction begins.
           65  +[list_end]
           66  +
           67  +[comment {- - -- --- ----- -------- -------------}]
           68  +[call [cmd ::cmdr::ask] [method yn] [arg query] [opt [arg default]]]
           69  +
           70  +When invoked this command prompts the user with [arg query] for a [emph boolean]
           71  +value/string. If the [arg default] is specified and not the empty string it is
           72  +also shown as part of the prompt. Note that [arg default] defaults to the empty
           73  +string.
           74  +
           75  +[para] The interactively entered boolean is returned as the result of the command.
           76  +The [arg default] boolean is returned as the result if the user entered an empty
           77  +string and the [arg default] is not empty.
           78  +
           79  +[para] Note that the command will not return until the user entered a valid
           80  +boolean value. Entering a non-boolean string causes the command to loop internally
           81  +and re-prompt.
           82  +
           83  +[list_begin arguments]
           84  +[arg_def string query] The prompt to show to the user before interaction begins.
           85  +[arg_def string default] The default boolean to return if the user enters nothing.
           86  +[list_end]
           87  +
           88  +[comment {- - -- --- ----- -------- -------------}]
           89  +[call [cmd ::cmdr::ask] [method choose] [arg query] [arg choices] [opt [arg default]]
           90  +
           91  +When invoked this command prompts the user with [arg query] for one of the
           92  +[arg choices], entered as string. Prompt and input happen on a single line.
           93  +
           94  +[para] The interactively entered choice is returned as the result of the command.
           95  +The [arg default] choice is returned as the result if the user entered an empty
           96  +string and the [arg default] is not empty.
           97  +
           98  +[para] Note that the command will not return until the user entered a valid
           99  +choice. Entering a non-choice causes the command to loop internally and re-prompt.
          100  +The user is supported in entry by an internal completion callback.
          101  +
          102  +[list_begin arguments]
          103  +[arg_def string query] The prompt to show to the user before interaction begins.
          104  +[arg_def string default] The default boolean to return if the user enters nothing.
          105  +[list_end]
          106  +
          107  +
          108  +[comment {- - -- --- ----- -------- -------------}]
          109  +[call [cmd ::cmdr::ask] [method menu] [arg header] [arg prompt] [arg choices] [opt [arg default]]
          110  +
          111  +Similar to [cmd {::cmdr::ask choice}], except that the [arg choices] are shown
          112  +as an enumerated menu, one per line, with a leading [arg header].
          113  +
          114  +Furthermore the command accepts not only the choices as input, but also their
          115  +numeric indices in the menu. The result however is always the relevant chosen string.
          116  +
          117  +[list_end]
          118  +[include parts/feedback.inc]
          119  +[manpage_end]

Added doc/cmdr_color.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset LABEL_COLOR] [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require cmdr::tty]
            6  +[require cmdr::color]
            7  +[titledesc [vset TITLE_COLOR]]
            8  +[description]
            9  +[include parts/welcome.inc]
           10  +
           11  +This package provides a few utility commands implementing
           12  +the management of terminal colors.
           13  +
           14  +[section API]
           15  +[list_begin definitions]
           16  +[comment {- - -- --- ----- -------- -------------}]
           17  +[call [cmd ::cmdr::color] [method ...] ...]
           18  +
           19  +When invoked this command 
           20  +
           21  +[para] The ... is returned as the result of the command.
           22  +
           23  +[list_begin arguments]
           24  +[arg_def list list] ...
           25  +[list_end]
           26  +
           27  +[comment {- - -- --- ----- -------- -------------}]
           28  +[call [cmd ::cmdr::color] [method ...] ...]
           29  +
           30  +[comment {- - -- --- ----- -------- -------------}]
           31  +[call [cmd ::cmdr::color] [method ...] ...]
           32  +
           33  +[comment {- - -- --- ----- -------- -------------}]
           34  +[call [cmd ::cmdr::color] [method ...] ...]
           35  +
           36  +[comment {- - -- --- ----- -------- -------------}]
           37  +[call [cmd ::cmdr::color] [method ...] ...]
           38  +
           39  +[comment {- - -- --- ----- -------- -------------}]
           40  +[call [cmd ::cmdr::color] [method ...] ...]
           41  +
           42  +[comment {- - -- --- ----- -------- -------------}]
           43  +[call [cmd ::cmdr::color] [method ...] ...]
           44  +
           45  +[comment {- - -- --- ----- -------- -------------}]
           46  +[call [cmd ::cmdr::color] [method ...] ...]
           47  +
           48  +[comment {- - -- --- ----- -------- -------------}]
           49  +[call [cmd ::cmdr::color] [method ...] ...]
           50  +
           51  +[list_end]
           52  +[include parts/feedback.inc]
           53  +[manpage_end]

Added doc/cmdr_pager.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset LABEL_PAGER] [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require linenoise]
            6  +[require cmdr::tty]
            7  +[require cmdr::pager]
            8  +[titledesc [vset TITLE_PAGER]]
            9  +[description]
           10  +[include parts/welcome.inc]
           11  +
           12  +This package provides a single utility command to manage the automatic
           13  +paging of long output, like [vset PROJECT]'s automatic help.
           14  +
           15  +[section API]
           16  +[list_begin definitions]
           17  +[comment {- - -- --- ----- -------- -------------}]
           18  +[call [cmd ::cmdr::pager] [method text]]
           19  +
           20  +When invoked this command either simply prints the [arg text] to stdout,
           21  +or invokes an external pager application to manage the output.
           22  +
           23  +[para] The pager is only invoked when
           24  +
           25  +[list_begin enumerated]
           26  +[enum] Stdout is a terminal, and
           27  +[enum] The text does not fit into the height of the terminal, and
           28  +[enum] a pager application could be found.
           29  +[list_end]
           30  +
           31  +[para] If any of the above conditions fail the text is simply printed.
           32  +
           33  +[para] When the command comes to the third condition above it will look
           34  +for the pager specified in the environment variable [const PAGER] first,
           35  +and then [const less] and [const more], in this order.
           36  +
           37  +[list_begin arguments]
           38  +[arg_def string text]
           39  +The text to print or page.
           40  +[list_end]
           41  +
           42  +[para] The result of the command is the empty string.
           43  +
           44  +[list_end]
           45  +[include parts/feedback.inc]
           46  +[manpage_end]

Added doc/cmdr_tty.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset LABEL_TTY] [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require Tclx]
            6  +[require cmdr::tty]
            7  +[titledesc [vset TITLE_TTY]]
            8  +[description]
            9  +[include parts/welcome.inc]
           10  +
           11  +This package provides a single utility command testing if the
           12  +[const stdout] [term channel] is a tty or not, and reporting
           13  +the result.
           14  +
           15  +[section API]
           16  +[list_begin definitions]
           17  +[comment {- - -- --- ----- -------- -------------}]
           18  +[call [cmd ::cmdr::tty] [method stdout]]
           19  +
           20  +When invoked this command returns a boolean value indicating
           21  +if the [const stdout] [term channel] is a tty ([const true]),
           22  +or not ([const false]).
           23  +
           24  +[list_end]
           25  +[include parts/feedback.inc]
           26  +[manpage_end]

Changes to doc/parts/definitions.inc.

     5      5   [vset TITLE_SOURCES  "[vset PTITLE] - How To Get The Sources"	 ]
     6      6   [vset TITLE_INSTALL  "[vset PTITLE] - The Installer's Guide"	 ]
     7      7   [vset TITLE_DEV      "[vset PTITLE] - The Developer's Guide"	 ]
     8      8   
     9      9   [comment {- Custom documents & titles - - -- --- ----- --------}]
    10     10   [vset TITLE_MAIN          "[vset PTITLE] - Main package and API"]
    11     11   [vset TITLE_ACTOR         "[vset PTITLE] - (Internal) Base class for officers and privates"]
           12  +[vset TITLE_ASK           "[vset PTITLE] - Terminal-based simple user interactions"]
           13  +[vset TITLE_COLOR         "[vset PTITLE] - Terminal colors"]
    12     14   [vset TITLE_CONFIG        "[vset PTITLE] - (Partially internal) Collection of parameters for privates"]
    13     15   [vset TITLE_DEV_COMPLETE  "[vset PTITLE] - Internals of command line completion"]
    14     16   [vset TITLE_DEV_DSL       "[vset PTITLE] - Internals of DSL handling"]
    15     17   [vset TITLE_DEV_HF        "[vset PTITLE] - Writing custom help formats"]
    16     18   [vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
    17     19   [vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
    18     20   [vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
................................................................................
    19     21   [vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
    20     22   [vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
    21     23   [vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
    22     24   [vset TITLE_HELP_JSON     "[vset PTITLE] - Formatting help as JSON object"]
    23     25   [vset TITLE_HELP_SQL      "[vset PTITLE] - Formatting help as series of SQL commands"]
    24     26   [vset TITLE_HELP_TCL      "[vset PTITLE] - Formatting help as Tcl data structure"]
    25     27   [vset TITLE_OFFICER       "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."]
           28  +[vset TITLE_PAGER         "[vset PTITLE] - Paging long output"]
    26     29   [vset TITLE_PARAMETER     "[vset PTITLE] - (Partially internal) Command parameters"]
    27     30   [vset TITLE_PRIVATE       "[vset PTITLE] - (Internal) Single command handling, options, and arguments"]
           31  +[vset TITLE_TTY           "[vset PTITLE] - Check if stdin is a tty, i.e. terminal"]
    28     32   [vset TITLE_UTIL          "[vset PTITLE] - (Internal) General Utilities"]
    29     33   [vset TITLE_VALIDATE      "[vset PTITLE] - Standard validation types for parameters"]
    30     34   [vset TITLE_VCOMMON       "[vset PTITLE] - Utilities for Validation Types"]
    31     35   [vset TITLE_FLOW          "[vset PTITLE] - Runtime Processing Flow"]
    32     36   
    33     37   [comment {- Miscellanea ............. - - -- --- ----- --------}]
    34     38   [vset LABEL_INTRO         [vset PROJECT]-introduction]
................................................................................
    36     40   [vset LABEL_CHANGES       [vset PROJECT]-changes]
    37     41   [vset LABEL_SOURCES       [vset PROJECT]-howto-get-sources]
    38     42   [vset LABEL_INSTALL       [vset PROJECT]-installation]
    39     43   [vset LABEL_DEV           [vset PROJECT]_development]
    40     44   
    41     45   [vset LABEL_MAIN          [vset PROJECT]]
    42     46   [vset LABEL_ACTOR         [vset PROJECT]::actor]
           47  +[vset LABEL_ASK           [vset PROJECT]::ask]
           48  +[vset LABEL_COLOR         [vset PROJECT]::color]
    43     49   [vset LABEL_CONFIG        [vset PROJECT]::config]
    44     50   [vset LABEL_DEV_COMPLETE  [vset PROJECT]_dev~completion]
    45     51   [vset LABEL_DEV_DSL       [vset PROJECT]_dev~dsl]
    46     52   [vset LABEL_HELPFORMATS   [vset PROJECT]-user-helpformats]
    47     53   [vset LABEL_VTYPES        [vset PROJECT]-user-vtypes]
    48     54   [vset LABEL_DSL           [vset PROJECT]-spec-dsl]
    49     55   [vset LABEL_DSL_OFFICER   [vset PROJECT]-spec-dsl-officer]
................................................................................
    50     56   [vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter]
    51     57   [vset LABEL_DSL_PRIVATE   [vset PROJECT]-spec-dsl-private]
    52     58   [vset LABEL_HELP          [vset PROJECT]::help]
    53     59   [vset LABEL_HELP_JSON     [vset PROJECT]::help::json]
    54     60   [vset LABEL_HELP_SQL      [vset PROJECT]::help::sql]
    55     61   [vset LABEL_HELP_TCL      [vset PROJECT]::help::tcl]
    56     62   [vset LABEL_OFFICER       [vset PROJECT]::officer]
           63  +[vset LABEL_PAGER         [vset PROJECT]::pager]
    57     64   [vset LABEL_PARAMETER     [vset PROJECT]::parameter]
    58     65   [vset LABEL_PRIVATE       [vset PROJECT]::private]
           66  +[vset LABEL_TTY           [vset PROJECT]::tty]
    59     67   [vset LABEL_UTIL          [vset PROJECT]::util]
    60     68   [vset LABEL_VALIDATE      [vset PROJECT]::validate]
    61     69   [vset LABEL_VCOMMON       [vset PROJECT]::validate::common]
    62     70   [vset LABEL_FLOW          [vset PROJECT]-spec-flow]