[ 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

- package require cmdr::tty
- package require cmdr::color

- ::cmdr::color activate ?enable?
- ::cmdr::color active
- ::cmdr::color names
- ::cmdr::color get name
- ::cmdr::color get-def name
- ::cmdr::color define name spec
- ::cmdr::color exists name
- ::cmdr::color unset name
- ::cmdr::color ... ?text?

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

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries