The cl-ansi-text Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-ansi-text Reference Manual

This is the cl-ansi-text Reference Manual, version 1.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:05:59 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-ansi-text

Because color in your terminal is nice. Build Status

Installation: (ql:quickload :cl-ansi-text)

Usage example -

The main macro is with-color, which creates an enviroment where everything that is put on stream gets colored according to color.

Color options comes in several forms.

Keyword Symbol

Basic 8 colors in the 3-bit color mode are supported, which are :black, :red, :green, :yellow, :blue, :magenta, :cyan and :white.

* (with-color (:red)
    (princ "Gets printed red...")
    (princ "and this too!"))
; Gets printed red...and this too!
; => "and this too!"

CL-COLORS:RGB and CL-COLORS:HSV object

These are color structures from CL-COLORS2 (a maintained fork of CL-COLORS). CL-COLORS2 has several constants e.g. cl-colors:+red+ that holds the corresponding color values. CL-COLORS2 also supports useful blending operations on colors. Note that CL-COLORS2 library provides a package CL-COLORS, not CL-COLORS2.

Hex representation

These are CSS-style color strings such as "#FF0000".

Integer as a 24-bit color

It treats an integer as a hex string. The bottom 8 bit is used for the blue, the 8th to 16th bits are used for green, the 16th to 24th bits are used for red. Remaining bits are ignored.

List of numbers as a 24-bit color

It takes a list of three numbers (RGB) between 0 and 256.

Function interface for printing in specific colors

We provide shorthand functions for generating a colored strings:

* (yellow "Yellow string")
; => "Yellow string"
* (princ (yellow "String with yellow background" :style :background))
; "String with yellow background"
; => "String with yellow background"
* (princ
   (concatenate
    'string
    (yellow "Five") " test results went " (red "terribly wrong") "!"))
; Five test results went terribly wrong!
; => "Five test results went terribly wrong!"

You can bind the *enabled* special variable to nil to control the colorization:

* (let (cl-ansi-text:*enabled*)
    (princ (red "This string is printed normally")))

API

Type color-specifier

(or unsigned-byte
    (cons (real 0 256)
          (cons (real 0 256)
                (cons (real 0 256)
                      nil)))
    cl-colors:rgb
    cl-colors:hsv
    term-colors
    color-string)

Type term-colors

(member :black :red :green :yellow :blue :magenta :cyan :white)

Type color-string

A string of length 3, 4, 6, or 7, that optionally starts with a #, and the rest consists of 3 or 6 hexademical alphadigits (case-insensitive).

Macro with-color

with-color (color &key (stream t) (effect :unset) (style :foreground)) &body body

Writes out the ANSI escape code string denoting effect, style, and a switch to color, then executes body, then writes out the string that resets the decoration.

Function make-color-string

make-color-string color &key (effect :unset) (style :foreground) enabled

Takes an object of color-specifier and returns a string sufficient to change to the given color.

Colorization is controlled by enabled unless manually specified otherwise by :enabled keyword.

Function black, red, green, yellow, blue, magenta, cyan, white

Shortcut functions that takes a single argument, string, and returns a string decorated by the corresponding color.

Special variable *enabled*

Turns on/off the colorization.

Special variable *color-mode*

Controls the way make-color-string emits the color code.

It should be one of the following keyword symbols: :3bit, :8bit, :24bit. The specified color is converted to the nearest color in the color space. The default value is :8bit.

Note that the actual appearance of the screen in the :3bit mode may be affected by the terminal setting -- For example, many terminals do not use FF0000 for the red.

Constant +reset-color-string+

A constant string that resets the color state of the terminal.

Running test

Run ./testscr.ros with Roswell. You can also manually run the test with (ql:quickload :cl-ansi-text.test) (fiveam:run! :cl-ansi-text).

Note

Note that your terminal MUST be ANSI-compliant to show these colors.

SLIME REPL does not display these colors by default (2019.12.13). To make it understand the ANSI escape sequence, install slime-repl-ansi-color package available from MELPA using package-install and add the following in .emacs:

(with-eval-after-load 'slime-repl
  (require 'slime-repl-ansi-color))
(add-hook 'slime-repl-mode-hook 'slime-repl-ansi-color-mode)

You can view the list of lisp implementation this library is tested on Travis-CI. The testing environment is Linux, but we believe this should work also on OSX.

License: LLGPL


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-ansi-text

Maintainer

Paul Nathan

Author

Paul Nathan

License

LLGPL

Description

ANSI control string characters, focused on color

Long Description

ANSI control string management, specializing in
colors. Sometimes it is nice to have text output in colors

Version

1.1

Dependencies
Source

cl-ansi-text.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-ansi-text.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-ansi-text-20200218-git/cl-ansi-text.asd

Systems

cl-ansi-text (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-ansi-text/cl-ansi-text.lisp

Parent

cl-ansi-text (system)

Location

cl-ansi-text.lisp

Packages

cl-ansi-text

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-ansi-text/define-colors.lisp

Dependency

cl-ansi-text.lisp (file)

Parent

cl-ansi-text (system)

Location

define-colors.lisp

Exported Definitions
Internal Definitions

define-colors (macro)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-ansi-text

Source

cl-ansi-text.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *color-mode*

Controls the way ‘make-color-string‘ emits the color code.

It should be one of the following keyword symbols: ‘:3bit‘, ‘:8bit‘, ‘:24bit‘. The specified color is converted to the nearest color in the color space.

Note that the actual appearance of the screen in the ‘:3bit‘ mode may be affected by the terminal setting – For example, many terminals do not use ‘FF0000‘ for the red.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Special Variable: *enabled*

Turns on/off the colorization.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Special Variable: +reset-color-string+

A constant string that resets the color state of the terminal.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-color (COLOR &key STREAM EFFECT STYLE) &body BODY

Writes out the ANSI escape code string
denoting ‘effect‘, ‘style‘, and a switch to ‘color‘, then executes ‘body‘, then writes out the string that resets the decoration.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: black STRING &key EFFECT STYLE

Returns a string decorated in black.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: blue STRING &key EFFECT STYLE

Returns a string decorated in blue.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: cyan STRING &key EFFECT STYLE

Returns a string decorated in cyan.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: green STRING &key EFFECT STYLE

Returns a string decorated in green.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: magenta STRING &key EFFECT STYLE

Returns a string decorated in magenta.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: make-color-string COLOR &key EFFECT STYLE (ENABLED *ENABLED*)

Takes an object of ‘color-specifier‘ and returns a string sufficient to change to the given color.

Colorization is controlled by *enabled* unless manually specified otherwise by ‘:enabled‘ keyword.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: red STRING &key EFFECT STYLE

Returns a string decorated in red.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: white STRING &key EFFECT STYLE

Returns a string decorated in white.

Package

cl-ansi-text

Source

define-colors.lisp (file)

Function: yellow STRING &key EFFECT STYLE

Returns a string decorated in yellow.

Package

cl-ansi-text

Source

define-colors.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Types

Type: color-specifier ()
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Type: color-string ()
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: +cl-colors-basic-colors+

CL-COLORS2 basic colors

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Special Variable: +term-colors+

Basic colors

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Special Variable: +term-effects+

ANSI terminal effects

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Special Variable: +text-style+

One or the other. Not an ANSI effect

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: define-colors ()
Package

cl-ansi-text

Source

define-colors.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: code-from-rgb COLOR STYLE
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: color-string-p STRING
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: find-effect-code EFFECT

Returns the number for the text effect OR t if no effect should be used OR
nil if the effect is unknown.

effect should be a member of +term-effects+

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: find-style-code STYLE
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: rgb-to-ansi-3bit COLOR

find the closest color from +cl-colors-basic-colors+

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Function: rgb-to-ansi-8bit COLOR

http://www.frexx.de/xterm-256-notes/

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: rgb-color-code COLOR &optional STYLE

Returns a list of codes suitable for the current color mode.

Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)

Methods
Method: rgb-color-code (COLOR symbol) &optional STYLE
Method: rgb-color-code (COLOR hsv) &optional STYLE
Method: rgb-color-code (COLOR rgb) &optional STYLE
Method: rgb-color-code (COLOR string) &optional STYLE

Takes RGB integer ala Web integers

Method: rgb-color-code (COLOR integer) &optional STYLE

Takes RGB integer ala Web integers

Method: rgb-color-code (COLOR list) &optional STYLE

Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Types

Type: term-colors ()
Package

cl-ansi-text

Source

cl-ansi-text.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-ansi-text.asd: The cl-ansi-text․asd file
cl-ansi-text/cl-ansi-text.lisp: The cl-ansi-text/cl-ansi-text․lisp file
cl-ansi-text/define-colors.lisp: The cl-ansi-text/define-colors․lisp file

F
File, Lisp, cl-ansi-text.asd: The cl-ansi-text․asd file
File, Lisp, cl-ansi-text/cl-ansi-text.lisp: The cl-ansi-text/cl-ansi-text․lisp file
File, Lisp, cl-ansi-text/define-colors.lisp: The cl-ansi-text/define-colors․lisp file

L
Lisp File, cl-ansi-text.asd: The cl-ansi-text․asd file
Lisp File, cl-ansi-text/cl-ansi-text.lisp: The cl-ansi-text/cl-ansi-text․lisp file
Lisp File, cl-ansi-text/define-colors.lisp: The cl-ansi-text/define-colors․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   D   F   G   M   R   W   Y  
Index Entry  Section

B
black: Exported functions
blue: Exported functions

C
code-from-rgb: Internal functions
color-string-p: Internal functions
cyan: Exported functions

D
define-colors: Internal macros

F
find-effect-code: Internal functions
find-style-code: Internal functions
Function, black: Exported functions
Function, blue: Exported functions
Function, code-from-rgb: Internal functions
Function, color-string-p: Internal functions
Function, cyan: Exported functions
Function, find-effect-code: Internal functions
Function, find-style-code: Internal functions
Function, green: Exported functions
Function, magenta: Exported functions
Function, make-color-string: Exported functions
Function, red: Exported functions
Function, rgb-to-ansi-3bit: Internal functions
Function, rgb-to-ansi-8bit: Internal functions
Function, white: Exported functions
Function, yellow: Exported functions

G
Generic Function, rgb-color-code: Internal generic functions
green: Exported functions

M
Macro, define-colors: Internal macros
Macro, with-color: Exported macros
magenta: Exported functions
make-color-string: Exported functions
Method, rgb-color-code: Internal generic functions
Method, rgb-color-code: Internal generic functions
Method, rgb-color-code: Internal generic functions
Method, rgb-color-code: Internal generic functions
Method, rgb-color-code: Internal generic functions
Method, rgb-color-code: Internal generic functions

R
red: Exported functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-color-code: Internal generic functions
rgb-to-ansi-3bit: Internal functions
rgb-to-ansi-8bit: Internal functions

W
white: Exported functions
with-color: Exported macros

Y
yellow: Exported functions

Jump to:   B   C   D   F   G   M   R   W   Y  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*color-mode*: Exported special variables
*enabled*: Exported special variables

+
+cl-colors-basic-colors+: Internal special variables
+reset-color-string+: Exported special variables
+term-colors+: Internal special variables
+term-effects+: Internal special variables
+text-style+: Internal special variables

S
Special Variable, *color-mode*: Exported special variables
Special Variable, *enabled*: Exported special variables
Special Variable, +cl-colors-basic-colors+: Internal special variables
Special Variable, +reset-color-string+: Exported special variables
Special Variable, +term-colors+: Internal special variables
Special Variable, +term-effects+: Internal special variables
Special Variable, +text-style+: Internal special variables

Jump to:   *   +  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   T  
Index Entry  Section

C
cl-ansi-text: The cl-ansi-text system
cl-ansi-text: The cl-ansi-text package
color-specifier: Exported types
color-string: Exported types

P
Package, cl-ansi-text: The cl-ansi-text package

S
System, cl-ansi-text: The cl-ansi-text system

T
term-colors: Internal types
Type, color-specifier: Exported types
Type, color-string: Exported types
Type, term-colors: Internal types

Jump to:   C   P   S   T