The cl-ansi-term Reference Manual

This is the cl-ansi-term Reference Manual, version 0.1.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 03:42:40 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-ansi-term

library to output formatted text on ANSI-compliant terminals

Author

Mark Karpov

License

GNU GPL, version 3

Version

0.1.3

Dependencies
  • alexandria (system).
  • anaphora (system).
  • str (system).
Source

cl-ansi-term.asd.

Child Component

cl-ansi-term.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 cl-ansi-term/cl-ansi-term.asd

Source

cl-ansi-term.asd.

Parent Component

cl-ansi-term (system).

ASDF Systems

cl-ansi-term.


3.1.2 cl-ansi-term/cl-ansi-term.lisp

Source

cl-ansi-term.asd.

Parent Component

cl-ansi-term (system).

Packages

cl-ansi-term.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 cl-ansi-term

Source

cl-ansi-term.lisp.

Nickname

term

Use List
  • alexandria.
  • anaphora.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *effects-enabled*

If this variable is bound to non-NIL value, graphic rendition
effects (and other terminal-dependent effects) are enabled, otherwise they are disabled.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: *terminal-width*

Many functions use this value to output text nicely. The default value is 80. If you want to dynamically change this variable, write and register :BEFORE-PRINTING hook and reassign terminal width before printing takes place.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.


5.1.2 Ordinary functions

Function: cat-print (objects &key base-style margin fill-column align stream)

Concatenate OBJECTS and print them. OBJECTS must be a list designator that consists of printable objects and lists where CAR is a printable object and CADR is a keyword that denotes style of the object. Unspecified styles default to BASE-STYLE. MARGIN, FILL-COLUMN, and ALIGN control corresponding parameters of output. Valid values for ALIGN are :LEFT (default), :CENTER, and :RIGHT. Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: hr (&key filler style width align stream)

Print a horizontal line. Characters in the line are created by repeating given FILLER until WIDTH characters accumulated. If WIDTH is not a positive number, ‘*terminal-width*’ will be added to it to get positive WIDTH. STYLE controls graphic rendition. ALIGN should be a keyword: :LEFT, :RIGHT, or :CENTER. Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: o-list (tree &key index delimiter mark-suffix index-style item-style mark-style margin level-margin fill-column stream)

Print an ordered list according to TREE. If we consider TREE a list, every element must be either a printable object to print as a list item or a list where CAR is list item and CDR is sublist of the item.

Example:

(term:o-list ’((:one one-a (:one-b :one-b-1 :one-b-2)) :two))
1. ONE
1. ONE-A
2. ONE-B
1. ONE-B-1
2. ONE-B-2
2. TWO

INDEX must be a
list designator, its elements should be keywords that denote how to represent numeration. Acceptable values are:

:ARABIC—indexes will be printed as arabic numerals (default value) :ROMAN—indexes will be printed as roman numerals
:LETTER—indexes will be printed as letters of Latin alphabet :CAPITAL—the same as :LETTER, but capital letters are used

If there are more levels of nesting than elements in the list, it will be cycled. The same applies to DELIMITER, which must be a string designator.

INDEX-STYLE is used for indexes. It can be also list, in this case it’s possible to specify different styles for different levels of nesting.

ITEM-STYLE is used to render the list items.

MARK-STYLE is used for items
that end with MARK-SUFFIX (it can be any printable object). LEVEL-MARGIN must be a positive integer that specifies how to increase margin for every level of nesting, you can also use plain MARGIN.

FILL-COLUMN is used to
split long items, if it’s not a positive number, ‘*terminal-output*’ will be added to it to get positive FILL-COLUMN.

Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: print (control-string &key args base-style margin fill-column align stream)

Insert arguments from ARGS (list designator) into CONTROL-STRING substituting tildes. Any region of text in CONTROL-STRING can be printed in specified style following this pattern: [text](NAME-OF-STYLE). Where NAME-OF-STYLE is downcased name of symbol (keyword) in style sheet. Style of the rest of the output defaults to BASE-STYLE. MARGIN, FILL-COLUMN, and ALIGN control corresponding parameters of output. Valid values for ALIGN are :LEFT (default), :CENTER, and :RIGHT. Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: progress-bar (label progress &key margin label-style filler bar-style num-style bar-width stream)

Print a progress bar. If PROGRESS is less than 100, move cursor to the beginning of current line, so next invocation of ‘progress-bar’ will rewrite it. This function doesn’t print anything if PROGRESS is less than 100 and output stream is not interactive or ‘*effects-enabled*’ is NIL. Insert MARGIN spaces, then LABEL (style for the label is set with LABEL-STYLE). Size of progress bar is set by BAR-WIDTH. If BAR-WIDTH is not a positive number, ‘*terminal-width*’ will be added to it to get positive BAR-WIDTH. BAR-STYLE is the style that will be used for the bar itself, while NUM-STYLE will be used for number of percents and some additional elements. Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: register-hook (event function)

Register a hook. When predefined EVENT occurs FUNCTION will be called. You can register many functions to call on the same event.

Acceptable values of EVENT:

:BEFORE-PRINTING—FUNCTION is invoked just before printing takes place, no argument is passed to the function
:AFTER-PRINTING—FUNCTION is invoked after printing, no argument is passed to the function
:ON-STYLE-CHANGE—FUNCTION is invoked before style changing escape sequence in printed. One argument is passed to FUNCTION, name of the style, which is a keyword.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: remove-hook (event)

Remove all registered functions that are called on EVENT. Returns T if there were any functions associated with EVENT and NIL otherwise.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: table (objects &key mark-suffix border-chars border-style header-style cell-style mark-style col-header margin column-width align stream)

Print a table filling cells with OBJECTS. OBJECTS must be a list of list
designators with equal lengths.

If BORDER-STYLE is NIL, no border will be
printed, otherwise BORDER-STYLE is expected to be a keyword that denotes
the style in which borders of the table should be printed.

HEADER-STYLE will be
applied to the first row of the table (also to the first column if
COL-HEADER is not NIL) and CELL-STYLE will be applied to all other rows. If
CELL-STYLE is a list, its elements will be used to differently render every
column.

Objects that end with MARK-SUFFIX will be printed using MARK-STYLE.

COLUMN-WIDTH is 10 by default (see ‘*column-width*’). It can be an integer that applies to
all columns, or a list designator to set a different
width for every column. A cell content is truncated to fit the width. See ‘str:*ellipsis*’
for the ellusion string, ‘(…)’ by default.

ALIGN controls the alignmet inside a cell. It can take the values :LEFT (default value), :CENTER, and :RIGHT.

MARGIN, an integer, is the left margin of the whole table.

Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: u-list (tree &key bullet mark-suffix bullet-style item-style mark-style margin level-margin fill-column stream)

Print an unordered list according to TREE. If we consider TREE a list, every element must be either a printable object to print as a list item or a list where CAR is the list item and CDR is sublist of the item.

Example:

(term:u-list ’((:one one-a (:one-b :one-b-1 :one-b-2)) :two))

* ONE
- ONE-A
- ONE-B
~ ONE-B-1
~ ONE-B-2
* TWO

BULLET is a string. Each character will be used, each time in a row,
as the list bullet. They can be cycled over.

Example:

(term:u-list ’((:one one-a (:one-b :one-b-1 :one-b-2)) :two)
:bullet #+)
+ ONE
+ ONE-A
+ ONE-B
+ ONE-B-1
+ ONE-B-2
+ TWO

(term:u-list ’((:one one-a (:one-b :one-b-1 :one-b-2)) :two)
:bullet "+-")
+ ONE
- ONE-A
- ONE-B
+ ONE-B-1
+ ONE-B-2
+ TWO

BULLET-STYLE is used for bullets. It can be also a list, in this
case it’s possible to specify different styles for different levels of nesting.

ITEM-STYLE is used to render the list items. MARK-STYLE is used for items that end with MARK-SUFFIX (it can be any printable object).

LEVEL-MARGIN must be a positive integer that specifies how to increase margin for every level of nesting, you can also use plain MARGIN.

FILL-COLUMN is used to split long items, if it’s not a positive number, ‘*terminal-width*’ will be added to it to get positive FILL-COLUMN.

Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: update-style-sheet (alist)

Update style sheet used by the application. Every item of ALIST must be a list with CAR denoting name of style sheet entry and CDR representing collection of tokens that define terminal rendition. Tokens can represent various things: foreground color, background color, and effects. Every type of token has its default value, so you can omit some tokens. However, if there are more than one token of the same type (for example :RED
and :GREEN—both tokens represent foreground color), result is unpredictable and depends on internal workings of Common Lisp implementation used. You cannot redefine :DEFAULT style, it always represents default parameters of rendition.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *coloration*

Alist where CARs are indexes at which to insert ANSI escape sequences to change graphical rendition and CDRs are keywords that denote style of the rendition. This special variable can be used to affect ‘print-partially’.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: *column-width*

The maximum table cells’ width.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: *hooks*

This variable is bound to a hash table that provides access to lists of functions by given key. We use keywords as keys. Arguments for the functions depend entirely on EVENT on which every function is called.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: *style*

This variable is bound to currently set style. Styles are set with ‘set-style’ function.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: *style-sheet*

This hash table contains strings for various styles of terminal output, defined with ‘update-style-sheet’.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: +background-colors+

These are the basic background terminal colors. Colors that are denoted by keywords ending with an asterisk are not in ANSI standard (high intensity variants of 8 basic colors).

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: +effects+

All supported rendition effects. Some of them are hardly ever supported by real-world terminals.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Special Variable: +foreground-colors+

These are the basic foreground terminal colors. Colors that are denoted by keywords ending with an asterisk are not in the ANSI standard (high intensity variants of 8 basic colors).

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.


5.2.2 Macros

Macro: with-reasonable-width (var &body body)

Rebind variable VAR, correcting its value in BODY. If VAR is not a positive number, ‘*terminal-width*’ will be added to it to get positive value that will be used.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.


5.2.3 Ordinary functions

Function: align-object (width align &optional stream)

Print white-space to STREAM so object occupying WIDTH columns will be aligned according to ALIGN if printed immediately after the white space.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: ansi-escape-seq (&optional tokens)

Convert list of rendition tokens into an ANSI escape sequence that will select appropriate parameters of rendition if “printed” on an ANSI-compatible terminal. If TOKENS is empty, escape sequence that resets all rendition parameters will be returned.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: effects-p (stream)

Evaluates to T if STREAM has support for the effects and ‘*effects-enabled*’ is not NIL.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: ensure-circular-list (object)
Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: largest-elt (lines)

Return the largest element of the given strings.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: largest-length (lines)

Return the largest length of the given strings.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: parse-control-string (string args)

Parse control string STRING according to the format described in documentation for PRINT function. Return a list, suitable for passing to ‘cat-print’.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: perform-hook (event &rest args)

Execute functions corresponding to given EVENT. We use this function to perform the hooks, so it’s for internal use. Return T if there is at least one function associated with EVENT and NIL otherwise.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: print-filler (filler width style &optional stream)

Print WIDTH symbols of FILLER to STREAM. Use STYLE for graphic rendition.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: print-partially (text start end &optional stream)

Partially print given TEXT starting from START character until END character is reached. Output will be colorized if ‘*coloration*’ is bound to alist that describes how to colorize the output, see ‘*coloration*’. All output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: print-white-space (width &optional stream)

Print WIDTH white-spaces to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: print-words (objects &key base-style margin fill-column align stream)

Print concatenation of OBJECTS using FILL-COLUMN so that line breaks don’t happen inside words, only between them. OBJECTS must be a list designator. It can consist of printable objects and lists where CAR is a printable object and CADR is a keyword that denotes style of the string designator. Unspecified styles default to BASE-STYLE. MARGIN is not applied for the first line. If FILL-COLUMN is not a positive number, ‘*terminal-width*’ will be added to it to get positive FILL-COLUMN. Output can be aligned with ALIGN parameter. Output goes to STREAM.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: set-style (style &optional stream)

Sets terminal rendition according to defined STYLE. It does nothing if ‘*effects-enabled*’ is NIL or output stream is not interactive (e.g. redirected to a file).

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.

Function: string* (object)

Converts printable object OBJECT to its aesthetic string representation.

Package

cl-ansi-term.

Source

cl-ansi-term.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   E   F   H   L   M   O   P   R   S   T   U   W  
Index Entry  Section

A
align-object: Private ordinary functions
ansi-escape-seq: Private ordinary functions

C
cat-print: Public ordinary functions

E
effects-p: Private ordinary functions
ensure-circular-list: Private ordinary functions

F
Function, align-object: Private ordinary functions
Function, ansi-escape-seq: Private ordinary functions
Function, cat-print: Public ordinary functions
Function, effects-p: Private ordinary functions
Function, ensure-circular-list: Private ordinary functions
Function, hr: Public ordinary functions
Function, largest-elt: Private ordinary functions
Function, largest-length: Private ordinary functions
Function, o-list: Public ordinary functions
Function, parse-control-string: Private ordinary functions
Function, perform-hook: Private ordinary functions
Function, print: Public ordinary functions
Function, print-filler: Private ordinary functions
Function, print-partially: Private ordinary functions
Function, print-white-space: Private ordinary functions
Function, print-words: Private ordinary functions
Function, progress-bar: Public ordinary functions
Function, register-hook: Public ordinary functions
Function, remove-hook: Public ordinary functions
Function, set-style: Private ordinary functions
Function, string*: Private ordinary functions
Function, table: Public ordinary functions
Function, u-list: Public ordinary functions
Function, update-style-sheet: Public ordinary functions

H
hr: Public ordinary functions

L
largest-elt: Private ordinary functions
largest-length: Private ordinary functions

M
Macro, with-reasonable-width: Private macros

O
o-list: Public ordinary functions

P
parse-control-string: Private ordinary functions
perform-hook: Private ordinary functions
print: Public ordinary functions
print-filler: Private ordinary functions
print-partially: Private ordinary functions
print-white-space: Private ordinary functions
print-words: Private ordinary functions
progress-bar: Public ordinary functions

R
register-hook: Public ordinary functions
remove-hook: Public ordinary functions

S
set-style: Private ordinary functions
string*: Private ordinary functions

T
table: Public ordinary functions

U
u-list: Public ordinary functions
update-style-sheet: Public ordinary functions

W
with-reasonable-width: Private macros