1 Introduction

cl-ansi-term

cl-ansi-term allows to print various primitives on ANSI-complaint
terminals. It also supports coloration and effects. cl-ansi-term is not
something like ncurses, because it works with primitives that you can
output in your terminal, as well as redirect to a file. In other words, it's
more about good ol' textual interface than emulation of GUI in terminal.
An example of user interface created with cl-ansi-term
is here.

The library is capable of detecting whether output goes to a terminal or a
file. If the latter case takes place, no escape sequences will be outputted.
It's also possible to disable all effects and coloration.

Installation

Via Quicklisp (recommended):

(ql:quickload "cl-ansi-term")

Documentation

See contents of the directory doc. Documentation is also available online:

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.

5.1.2 Functions

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.

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.

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

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.

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.

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.

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
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.
MARGIN, COLUMN-WIDTH (list desginator, may be used to set different width
for every column), and ALIGN can also be specified. Valid values of ALIGN
are: :LEFT (default value), :CENTER, and :RIGHT. Output goes to 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. BULLET must
be a string designator, it will be converted to string if needed and its
characters will be used as bullets: zeroth character will be the bullet for
top level of the list, first character is the bullet for sublist, etc. If
there are more levels of nesting than characters in the string, it will be
cycled. 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.

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.

5.2 Internal definitions

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

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.

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.

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.

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.