# 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
}

# # ## ### ##### ######## ############# #####################

debug define cmdr/color
debug level  cmdr/color
debug prefix cmdr/color {[debug caller] | }

# # ## ### ##### ######## ############# #####################
## 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
}

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

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]