cmdr
Check-in [57fc520fe4]
Not logged in
Myself Home DocumentationDownloads Tickets | Timeline Branches Tags Wiki Login
Bounty program for improvements to Tcl and certain Tcl packages.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Completed new docs
Timelines: family | ancestors | descendants | both | doc-expansion
Files: files | file ages | folders
SHA1: 57fc520fe478d1c3fc22ba4588d6d6b7498f3439
User & Date: andreask 2015-04-17 01:51:43
Context
2015-04-17
05:44
Regenerated embedded docs. Closed-Leaf check-in: db133a5866 user: aku tags: doc-expansion
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
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to color.tcl. 

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

    # Note, the -unknown option ensures that all unknown methods are
    # treated as (list of) color codes to apply to some text,
    # effectively creating the virtual command
    #
    #    ::cmdr::color <codelist> <text>
    #
    # The -prefix 0 option ensures that we canuse the 'name'
    # color-code, without it will go to 'names' and then fail with
    # wrong#args due to the different expected syntax.
    ##

    namespace import ::cmdr::tty
}

................................................................................
# # ## ### ##### ######## ############# #####################
## TODO multi-def aka bulk-def aka load
## TODO officer and private for std commands (show, define).

proc ::cmdr::color::activate {{flag 1}} {
    debug.cmdr/color {}
    variable active $flag
    return
}

proc ::cmdr::color::active {} {
    debug.cmdr/color {}
    variable active
    return  $active
}







|







 







|








41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

    # Note, the -unknown option ensures that all unknown methods are
    # treated as (list of) color codes to apply to some text,
    # effectively creating the virtual command
    #
    #    ::cmdr::color <codelist> <text>
    #
    # The -prefix 0 option ensures that we can use the 'name'
    # color-code, without it will go to 'names' and then fail with
    # wrong#args due to the different expected syntax.
    ##

    namespace import ::cmdr::tty
}

................................................................................
# # ## ### ##### ######## ############# #####################
## TODO multi-def aka bulk-def aka load
## TODO officer and private for std commands (show, define).

proc ::cmdr::color::activate {{flag 1}} {
    debug.cmdr/color {}
    variable active $flag
    return $active
}

proc ::cmdr::color::active {} {
    debug.cmdr/color {}
    variable active
    return  $active
}

Changes to doc/cmdr_ask.man. 

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
...
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

[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.
................................................................................
[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]







|







 







|

|









82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
...
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

[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.
................................................................................
[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 choose}], 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]

Changes to doc/cmdr_color.man. 

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

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]







|

|
>
>

|

>
>
>
>

<
>



|

>
>
>
>
>
>
>

|

>
>
>

|

>
>
>
>

|

>
>
>
>

|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

|

>
>
>
>

|

>
>
>
>
>

|

>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

This package provides a few utility commands implementing
the management of terminal colors.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method activate] [opt [arg enable]]]

When invoked this command enables or disables color handling,
as per the boolean flag [arg enable]. If [arg enable] is not
specified the action defaults to activation.

[para] The result of the command is the new activation state.

[para] The default activation state of the package after loading
depends on [const stdout]. The package is active if [const stdout]
is a terminal, and inactive otherwise.

[list_begin arguments]

[arg_def boolean enable] If set, enable color handling, else disable it.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method active]]

The result of this command is the current activation state
of the package.

[para] The default activation state of the package after loading
depends on [const stdout]. The package is active if [const stdout]
is a terminal, and inactive otherwise.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method names]]

When invoked this command returns a list of the symbolic color
names known to the package.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method get] [arg name]]

When invoked this command returns the character sequence
associated with the symbolic color [arg name]. An error
is thrown if [arg name] is not a known symbol.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method get-def] [arg name]]

When invoked this command returns the specification
associated with the symbolic color [arg name]. An error
is thrown if [arg name] is not a known symbol.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method define] [arg name] [arg spec]]

When invoked this command defines the color [arg name]. If [arg name]
exists already its previous specification is overwritten.

The command accepts four forms of [arg spec]ifications, namely:

[list_begin definitions]
[def "=[var rname]"]
The [arg rname] must be the name of a known color.
The [arg name] itself is not allowed, i.e. self-references are forbidden.

[def "%[var R],[var G],[var B]"]

The [arg R], [arg G], and [arg B] values are integers in the range
[const 0]...[const 5] directly specifying the chosen color. These
specifications may not work if the terminal is not configured to
support 256 colors.

[def "[lb]Ee[rb][var code](,...)"]
The value is a comma-separated list of ANSI color control characters.

[def "*"]
Any other string is acceptable too, and used as is.

[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method exists] [arg name]]

When invoked this command tests if the symbolic color [arg name]
is known, returns the boolean value [const true] if so, and
[const false] else.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method unset] [arg name]]

When invoked this command deletes the symbolic color [arg name].
An error is thrown if [arg name] is not a known symbol.

The command returns the empty string as its result.

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] [arg text]]

When [cmd ::cmdr::color] is invoked with an unknown method name
then this name is expected to be and treated as a list of known
symbolic color names. These colors are applied to the [arg text]
and the modified text is returned as the result of the command.

[para] An error is thrown if any of the specified color symbols
are not known.

[list_end]

[section {Predefined colors}]

The following colors are defined by the package itself:

[list_begin definitions]
[def black  ] e30
[def red    ] e31
[def green  ] e32
[def yellow ] e33
[def blue   ] e34
[def magenta] e35
[def cyan   ] e36
[def white  ] e37
[def default] e39

[def bg-black  ] e40
[def bg-red    ] e41
[def bg-green  ] e42
[def bg-yellow ] e43
[def bg-blue   ] e44
[def bg-magenta] e45
[def bg-cyan   ] e46
[def bg-white  ] e47
[def bg-default] e49

[def bold     ] e1
[def dim      ] e2
[def italic   ] e3
[def underline] e4
[def blink    ] e5
[def revers   ] e7
[def hidden   ] e8
[def strike   ] e9

[def no-bold     ] e21
[def no-dim      ] e22
[def no-italic   ] e23
[def no-underline] e24
[def no-blink    ] e25
[def no-revers   ] e27
[def no-hidden   ] e28
[def no-strike   ] e29

[def reset] e0

[def advisory] =yellow
[def bad     ] =red
[def confirm ] =red
[def error   ] =magenta
[def good    ] =green
[def name    ] =blue
[def neutral ] =blue
[def no      ] =red
[def note    ] =blue
[def number  ] =green
[def prompt  ] =blue
[def unknown ] =cyan
[def warning ] =yellow
[def yes     ] =green
[list_end]

[include parts/feedback.inc]
[manpage_end]

This page was generated in about 0.018s by Fossil 2.10 [eb804dc674] 2019-09-19 14:14:14