cmdr
Check-in [57fc520fe4]
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: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 Side-by-Side Diffs Ignore Whitespace Patch

Changes to color.tcl.

    41     41   
    42     42       # Note, the -unknown option ensures that all unknown methods are
    43     43       # treated as (list of) color codes to apply to some text,
    44     44       # effectively creating the virtual command
    45     45       #
    46     46       #    ::cmdr::color <codelist> <text>
    47     47       #
    48         -    # The -prefix 0 option ensures that we canuse the 'name'
           48  +    # The -prefix 0 option ensures that we can use the 'name'
    49     49       # color-code, without it will go to 'names' and then fail with
    50     50       # wrong#args due to the different expected syntax.
    51     51       ##
    52     52   
    53     53       namespace import ::cmdr::tty
    54     54   }
    55     55   
................................................................................
    62     62   # # ## ### ##### ######## ############# #####################
    63     63   ## TODO multi-def aka bulk-def aka load
    64     64   ## TODO officer and private for std commands (show, define).
    65     65   
    66     66   proc ::cmdr::color::activate {{flag 1}} {
    67     67       debug.cmdr/color {}
    68     68       variable active $flag
    69         -    return
           69  +    return $active
    70     70   }
    71     71   
    72     72   proc ::cmdr::color::active {} {
    73     73       debug.cmdr/color {}
    74     74       variable active
    75     75       return  $active
    76     76   }

Changes to doc/cmdr_ask.man.

    82     82   
    83     83   [list_begin arguments]
    84     84   [arg_def string query] The prompt to show to the user before interaction begins.
    85     85   [arg_def string default] The default boolean to return if the user enters nothing.
    86     86   [list_end]
    87     87   
    88     88   [comment {- - -- --- ----- -------- -------------}]
    89         -[call [cmd ::cmdr::ask] [method choose] [arg query] [arg choices] [opt [arg default]]
           89  +[call [cmd ::cmdr::ask] [method choose] [arg query] [arg choices] [opt [arg default]]]
    90     90   
    91     91   When invoked this command prompts the user with [arg query] for one of the
    92     92   [arg choices], entered as string. Prompt and input happen on a single line.
    93     93   
    94     94   [para] The interactively entered choice is returned as the result of the command.
    95     95   The [arg default] choice is returned as the result if the user entered an empty
    96     96   string and the [arg default] is not empty.
................................................................................
   102    102   [list_begin arguments]
   103    103   [arg_def string query] The prompt to show to the user before interaction begins.
   104    104   [arg_def string default] The default boolean to return if the user enters nothing.
   105    105   [list_end]
   106    106   
   107    107   
   108    108   [comment {- - -- --- ----- -------- -------------}]
   109         -[call [cmd ::cmdr::ask] [method menu] [arg header] [arg prompt] [arg choices] [opt [arg default]]
          109  +[call [cmd ::cmdr::ask] [method menu] [arg header] [arg prompt] [arg choices] [opt [arg default]]]
   110    110   
   111         -Similar to [cmd {::cmdr::ask choice}], except that the [arg choices] are shown
          111  +Similar to [cmd {::cmdr::ask choose}], except that the [arg choices] are shown
   112    112   as an enumerated menu, one per line, with a leading [arg header].
   113    113   
   114    114   Furthermore the command accepts not only the choices as input, but also their
   115    115   numeric indices in the menu. The result however is always the relevant chosen string.
   116    116   
   117    117   [list_end]
   118    118   [include parts/feedback.inc]
   119    119   [manpage_end]

Changes to doc/cmdr_color.man.

    10     10   
    11     11   This package provides a few utility commands implementing
    12     12   the management of terminal colors.
    13     13   
    14     14   [section API]
    15     15   [list_begin definitions]
    16     16   [comment {- - -- --- ----- -------- -------------}]
    17         -[call [cmd ::cmdr::color] [method ...] ...]
           17  +[call [cmd ::cmdr::color] [method activate] [opt [arg enable]]]
    18     18   
    19         -When invoked this command 
           19  +When invoked this command enables or disables color handling,
           20  +as per the boolean flag [arg enable]. If [arg enable] is not
           21  +specified the action defaults to activation.
    20     22   
    21         -[para] The ... is returned as the result of the command.
           23  +[para] The result of the command is the new activation state.
           24  +
           25  +[para] The default activation state of the package after loading
           26  +depends on [const stdout]. The package is active if [const stdout]
           27  +is a terminal, and inactive otherwise.
    22     28   
    23     29   [list_begin arguments]
    24         -[arg_def list list] ...
           30  +[arg_def boolean enable] If set, enable color handling, else disable it.
           31  +[list_end]
           32  +
           33  +[comment {- - -- --- ----- -------- -------------}]
           34  +[call [cmd ::cmdr::color] [method active]]
           35  +
           36  +The result of this command is the current activation state
           37  +of the package.
           38  +
           39  +[para] The default activation state of the package after loading
           40  +depends on [const stdout]. The package is active if [const stdout]
           41  +is a terminal, and inactive otherwise.
           42  +
           43  +[comment {- - -- --- ----- -------- -------------}]
           44  +[call [cmd ::cmdr::color] [method names]]
           45  +
           46  +When invoked this command returns a list of the symbolic color
           47  +names known to the package.
           48  +
           49  +[comment {- - -- --- ----- -------- -------------}]
           50  +[call [cmd ::cmdr::color] [method get] [arg name]]
           51  +
           52  +When invoked this command returns the character sequence
           53  +associated with the symbolic color [arg name]. An error
           54  +is thrown if [arg name] is not a known symbol.
           55  +
           56  +[comment {- - -- --- ----- -------- -------------}]
           57  +[call [cmd ::cmdr::color] [method get-def] [arg name]]
           58  +
           59  +When invoked this command returns the specification
           60  +associated with the symbolic color [arg name]. An error
           61  +is thrown if [arg name] is not a known symbol.
           62  +
           63  +[comment {- - -- --- ----- -------- -------------}]
           64  +[call [cmd ::cmdr::color] [method define] [arg name] [arg spec]]
           65  +
           66  +When invoked this command defines the color [arg name]. If [arg name]
           67  +exists already its previous specification is overwritten.
           68  +
           69  +The command accepts four forms of [arg spec]ifications, namely:
           70  +
           71  +[list_begin definitions]
           72  +[def "=[var rname]"]
           73  +The [arg rname] must be the name of a known color.
           74  +The [arg name] itself is not allowed, i.e. self-references are forbidden.
           75  +
           76  +[def "%[var R],[var G],[var B]"]
           77  +
           78  +The [arg R], [arg G], and [arg B] values are integers in the range
           79  +[const 0]...[const 5] directly specifying the chosen color. These
           80  +specifications may not work if the terminal is not configured to
           81  +support 256 colors.
           82  +
           83  +[def "[lb]Ee[rb][var code](,...)"]
           84  +The value is a comma-separated list of ANSI color control characters.
           85  +
           86  +[def "*"]
           87  +Any other string is acceptable too, and used as is.
           88  +
    25     89   [list_end]
    26     90   
    27     91   [comment {- - -- --- ----- -------- -------------}]
    28         -[call [cmd ::cmdr::color] [method ...] ...]
           92  +[call [cmd ::cmdr::color] [method exists] [arg name]]
    29     93   
    30         -[comment {- - -- --- ----- -------- -------------}]
    31         -[call [cmd ::cmdr::color] [method ...] ...]
           94  +When invoked this command tests if the symbolic color [arg name]
           95  +is known, returns the boolean value [const true] if so, and
           96  +[const false] else.
    32     97   
    33     98   [comment {- - -- --- ----- -------- -------------}]
    34         -[call [cmd ::cmdr::color] [method ...] ...]
           99  +[call [cmd ::cmdr::color] [method unset] [arg name]]
    35    100   
    36         -[comment {- - -- --- ----- -------- -------------}]
    37         -[call [cmd ::cmdr::color] [method ...] ...]
          101  +When invoked this command deletes the symbolic color [arg name].
          102  +An error is thrown if [arg name] is not a known symbol.
          103  +
          104  +The command returns the empty string as its result.
    38    105   
    39    106   [comment {- - -- --- ----- -------- -------------}]
    40         -[call [cmd ::cmdr::color] [method ...] ...]
          107  +[call [cmd ::cmdr::color] [method ...] [arg text]]
          108  +
          109  +When [cmd ::cmdr::color] is invoked with an unknown method name
          110  +then this name is expected to be and treated as a list of known
          111  +symbolic color names. These colors are applied to the [arg text]
          112  +and the modified text is returned as the result of the command.
          113  +
          114  +[para] An error is thrown if any of the specified color symbols
          115  +are not known.
          116  +
          117  +[list_end]
          118  +
          119  +[section {Predefined colors}]
          120  +
          121  +The following colors are defined by the package itself:
          122  +
          123  +[list_begin definitions]
          124  +[def black  ] e30
          125  +[def red    ] e31
          126  +[def green  ] e32
          127  +[def yellow ] e33
          128  +[def blue   ] e34
          129  +[def magenta] e35
          130  +[def cyan   ] e36
          131  +[def white  ] e37
          132  +[def default] e39
          133  +
          134  +[def bg-black  ] e40
          135  +[def bg-red    ] e41
          136  +[def bg-green  ] e42
          137  +[def bg-yellow ] e43
          138  +[def bg-blue   ] e44
          139  +[def bg-magenta] e45
          140  +[def bg-cyan   ] e46
          141  +[def bg-white  ] e47
          142  +[def bg-default] e49
          143  +
          144  +[def bold     ] e1
          145  +[def dim      ] e2
          146  +[def italic   ] e3
          147  +[def underline] e4
          148  +[def blink    ] e5
          149  +[def revers   ] e7
          150  +[def hidden   ] e8
          151  +[def strike   ] e9
    41    152   
    42         -[comment {- - -- --- ----- -------- -------------}]
    43         -[call [cmd ::cmdr::color] [method ...] ...]
          153  +[def no-bold     ] e21
          154  +[def no-dim      ] e22
          155  +[def no-italic   ] e23
          156  +[def no-underline] e24
          157  +[def no-blink    ] e25
          158  +[def no-revers   ] e27
          159  +[def no-hidden   ] e28
          160  +[def no-strike   ] e29
    44    161   
    45         -[comment {- - -- --- ----- -------- -------------}]
    46         -[call [cmd ::cmdr::color] [method ...] ...]
          162  +[def reset] e0
    47    163   
    48         -[comment {- - -- --- ----- -------- -------------}]
    49         -[call [cmd ::cmdr::color] [method ...] ...]
    50         -
          164  +[def advisory] =yellow
          165  +[def bad     ] =red
          166  +[def confirm ] =red
          167  +[def error   ] =magenta
          168  +[def good    ] =green
          169  +[def name    ] =blue
          170  +[def neutral ] =blue
          171  +[def no      ] =red
          172  +[def note    ] =blue
          173  +[def number  ] =green
          174  +[def prompt  ] =blue
          175  +[def unknown ] =cyan
          176  +[def warning ] =yellow
          177  +[def yes     ] =green
    51    178   [list_end]
          179  +
    52    180   [include parts/feedback.inc]
    53    181   [manpage_end]