cmdr
Check-in [912d950350]
Not logged in

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.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
Unified Diff Ignore Whitespace Patch
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]