Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-ansi-term Reference Manual, version 0.1.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:30:14 2021 GMT+0.
| • Introduction | What cl-ansi-term is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
cl-ansi-term allows to print various primitives on ANSI-compliant
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.
cl-ansi-term uses the concept of style sheet to manage coloration of output. Define styles, give them names, specify foreground colors, background colors, and effects for every style.
The library is capable of detecting whether the 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.
cl-ansi-term can print the following things:
Via Quicklisp (recommended):
(ql:quickload "cl-ansi-term")
Then you can use the term nickname.
See the doc directory. The documentation is also available online:
https://vindarel.github.io/cl-ansi-term
Quick snippets:
(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
(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:table (list '("name" "age")
'("me" "7")))
+---------+---------+
|name |age |
+---------+---------+
|me |7 |
+---------+---------+
;; A long cell is truncated to :column-width, 10 by default.
(term:table '(("name" "age" "email")
("me" 7 "some@blah")
("me" 7 "some@with-some-longer.email")))
+---------+---------+---------+
|name |age |email |
+---------+---------+---------+
|me |7 |some@blah|
+---------+---------+---------+
|me |7 |some@w(…)|
+---------+---------+---------+
;; Each column can have a different length.
(term:table '(("name" "age" "email")
("me" 7 "some@blah")
("me" 7 "some@with-some-longer.email"))
:column-width '(10 4 20))
+---------+---+-------------------+
|name |age|email |
+---------+---+-------------------+
|me |7 |some@blah |
+---------+---+-------------------+
|me |7 |some@with-some-l(…)|
+---------+---+-------------------+
(term:hr :filler "=")
================================================================================
(term:cat-print '(:abc :def :ghi) :align :center)
ABCDEFGHI
tablePrint 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. 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.
Blog posts:
Copyright © 2015–2018 Mark Karpov Copyright © 2018–2020 Vindarel
Distributed under GNU GPL,
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-ansi-term system |
Mark Karpov
GNU GPL, version 3
library to output formatted text on ANSI-compliant terminals
0.1.3
cl-ansi-term.asd (file)
cl-ansi-term.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-ansi-term.asd file | ||
| • The cl-ansi-term/cl-ansi-term.lisp file |
Next: The cl-ansi-term/cl-ansi-term․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-ansi-term.asd
cl-ansi-term (system)
Previous: The cl-ansi-term․asd file, Up: Lisp files [Contents][Index]
cl-ansi-term (system)
cl-ansi-term.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-ansi-term package |
cl-ansi-term.lisp (file)
term
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported functions |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
If this variable is bound to non-NIL value, graphic rendition
effects (and other terminal-dependent effects) are enabled, otherwise they
are disabled.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Previous: Exported special variables, Up: Exported definitions [Contents][Index]
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Remove all registered functions that are called on EVENT. Returns T if there were any functions associated with EVENT and NIL otherwise.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
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’.
cl-ansi-term.lisp (file)
The maximum table cells’ width.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
This variable is bound to currently set style. Styles are set with ‘set-style’ function.
cl-ansi-term.lisp (file)
This hash table contains strings for various styles of terminal output, defined with ‘update-style-sheet’.
cl-ansi-term.lisp (file)
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).
cl-ansi-term.lisp (file)
All supported rendition effects. Some of them are hardly ever supported by real-world terminals.
cl-ansi-term.lisp (file)
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).
cl-ansi-term.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
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.
cl-ansi-term.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
Print white-space to STREAM so object occupying WIDTH columns will be aligned according to ALIGN if printed immediately after the white space.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Evaluates to T if STREAM has support for the effects and ‘*effects-enabled*’ is not NIL.
cl-ansi-term.lisp (file)
cl-ansi-term.lisp (file)
Return the largest element of the given strings.
cl-ansi-term.lisp (file)
Return the largest length of the given strings.
cl-ansi-term.lisp (file)
Parse control string STRING according to the format described in documentation for PRINT function. Return a list, suitable for passing to ‘cat-print’.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Print WIDTH symbols of FILLER to STREAM. Use STYLE for graphic rendition.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
Print WIDTH white-spaces to STREAM.
cl-ansi-term.lisp (file)
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.
cl-ansi-term.lisp (file)
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).
cl-ansi-term.lisp (file)
Converts printable object OBJECT to its aesthetic string representation.
cl-ansi-term.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A C E F H L M O P R S T U W |
|---|
| Jump to: | A C E F H L M O P R S T U W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
S |
|---|
| Jump to: | *
+
S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C P S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| C | |||
cl-ansi-term: | The cl-ansi-term system | ||
cl-ansi-term: | The cl-ansi-term package | ||
| | |||
| P | |||
Package, cl-ansi-term: | The cl-ansi-term package | ||
| | |||
| S | |||
System, cl-ansi-term: | The cl-ansi-term system | ||
| | |||
| Jump to: | C P S |
|---|