The cl-ansi-text Reference Manual

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

The cl-ansi-text Reference Manual

This is the cl-ansi-text Reference Manual, version 2.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 03:27:49 2022 GMT+0.

Table of Contents


1 Introduction

cl-ansi-text

Because color in your terminal is nice. CI

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).

CI tests

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

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)

License: LLGPL


2 Systems

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


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

2.1 cl-ansi-text

ANSI control string characters, focused on color

Maintainer

Paul Nathan

Author

Paul Nathan

License

LLGPL

Long Description

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

Version

2.0.1

Dependencies
  • cl-colors2 (system).
  • alexandria (system).
Source

cl-ansi-text.asd.

Child Components

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

3.1.1 cl-ansi-text/cl-ansi-text.asd

Source

cl-ansi-text.asd.

Parent Component

cl-ansi-text (system).

ASDF Systems

cl-ansi-text.


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

Source

cl-ansi-text.asd.

Parent Component

cl-ansi-text (system).

Packages

cl-ansi-text.

Public Interface
Internals

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

Dependency

cl-ansi-text.lisp (file).

Source

cl-ansi-text.asd.

Parent Component

cl-ansi-text (system).

Public Interface
Internals

define-colors (macro).


4 Packages

Packages are listed by definition order.


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

4.1 cl-ansi-text

Source

cl-ansi-text.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [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.

Special Variable: *enabled*

Turns on/off the colorization.

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

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.


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.


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: black (string &key effect style)

Returns a string decorated in black.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: blue (string &key effect style)

Returns a string decorated in blue.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: cyan (string &key effect style)

Returns a string decorated in cyan.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: green (string &key effect style)

Returns a string decorated in green.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: magenta (string &key effect style)

Returns a string decorated in magenta.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: make-color-string (color &key effect style 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.

Function: red (string &key effect style)

Returns a string decorated in red.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: white (string &key effect style)

Returns a string decorated in white.

Package

cl-ansi-text.

Source

define-colors.lisp.

Function: yellow (string &key effect style)

Returns a string decorated in yellow.

Package

cl-ansi-text.

Source

define-colors.lisp.


5.1.4 Types

Type: color-specifier ()
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Type: color-string ()
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [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.

Special Variable: +term-colors+

Basic colors

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Special Variable: +term-effects+

ANSI terminal effects

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Special Variable: +text-style+

One or the other. Not an ANSI effect

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.


5.2.2 Macros

Macro: define-colors ()
Package

cl-ansi-text.

Source

define-colors.lisp.


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

5.2.3 Ordinary functions

Function: code-from-rgb (color style)
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Function: color-string-p (string)
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

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.

Function: find-style-code (style)
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Function: rgb-to-ansi-3bit (color)

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

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.

Function: rgb-to-ansi-8bit (color)

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

Package

cl-ansi-text.

Source

cl-ansi-text.lisp.


Next: , Previous: , Up: Internals   [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.

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: Internals   [Contents][Index]

5.2.5 Types

Type: term-colors ()
Package

cl-ansi-text.

Source

cl-ansi-text.lisp.


Appendix A Indexes


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

A.1 Concepts


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: Public ordinary functions
blue: Public ordinary functions

C
code-from-rgb: Private ordinary functions
color-string-p: Private ordinary functions
cyan: Public ordinary functions

D
define-colors: Private macros

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

G
Generic Function, rgb-color-code: Private generic functions
green: Public ordinary functions

M
Macro, define-colors: Private macros
Macro, with-color: Public macros
magenta: Public ordinary functions
make-color-string: Public ordinary functions
Method, rgb-color-code: Private generic functions
Method, rgb-color-code: Private generic functions
Method, rgb-color-code: Private generic functions
Method, rgb-color-code: Private generic functions
Method, rgb-color-code: Private generic functions
Method, rgb-color-code: Private generic functions

R
red: Public ordinary functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-color-code: Private generic functions
rgb-to-ansi-3bit: Private ordinary functions
rgb-to-ansi-8bit: Private ordinary functions

W
white: Public ordinary functions
with-color: Public macros

Y
yellow: Public ordinary functions

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