[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

cmdr::color(n) 1.0.2 doc "Cmdr, a framework for command line parsing and dispatch"

Name

cmdr::color - Cmdr - Terminal colors

Table Of Contents

Synopsis

Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

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

API

::cmdr::color activate ?enable?

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

The result of the command is the new activation state.

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

boolean enable

If set, enable color handling, else disable it.

::cmdr::color active

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

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

::cmdr::color names

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

::cmdr::color get name

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

::cmdr::color get-def name

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

::cmdr::color define name spec

When invoked this command defines the color name. If name exists already its previous specification is overwritten. The command accepts four forms of specifications, namely:

=rname

The rname must be the name of a known color. The name itself is not allowed, i.e. self-references are forbidden.

%R,G,B

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

[Ee]code(,...)

The value is a comma-separated list of ANSI color control characters.

*

Any other string is acceptable too, and used as is.

::cmdr::color exists name

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

::cmdr::color unset name

When invoked this command deletes the symbolic color name. An error is thrown if name is not a known symbol. The command returns the empty string as its result.

::cmdr::color ... ?text?

When ::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 text, with a return to base after, and the modified text is returned as the result of the command.

Note however, if the text is the empty string, then that string is returned, as the colorization would a no-op, i.e. superfluous.

If the text is not specified at all then the method returns just the application of the colors (without return to base).

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

Predefined colors

The following colors are defined by the package itself:

black

e30

red

e31

green

e32

yellow

e33

blue

e34

magenta

e35

cyan

e36

white

e37

default

e39

bg-black

e40

bg-red

e41

bg-green

e42

bg-yellow

e43

bg-blue

e44

bg-magenta

e45

bg-cyan

e46

bg-white

e47

bg-default

e49

bold

e1

dim

e2

italic

e3

underline

e4

blink

e5

revers

e7

hidden

e8

strike

e9

no-bold

e21

no-dim

e22

no-italic

e23

no-underline

e24

no-blink

e25

no-revers

e27

no-hidden

e28

no-strike

e29

reset

e0

advisory

=yellow

bad

=red

confirm

=red

error

=magenta

good

=green

name

=blue

neutral

=blue

no

=red

note

=blue

number

=green

prompt

=blue

unknown

=cyan

warning

=yellow

yes

=green

heading

=bold

Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

Keywords

arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands