The cl-ansi-term Reference Manual

Table of Contents

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

The cl-ansi-term Reference Manual

This is the cl-ansi-term Reference Manual, version 0.1.2, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:57:48 2018 GMT+0.


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

1 Introduction

cl-ansi-term

License GPL 3 Build Status Quicklisp

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.

cl-ansi-term can print the following things:

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

https://vindarel.github.io/cl-ansi-term

License

Copyright © 2015–2018 Mark Karpov

Distributed under GNU GPL, version


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

Author

Mark Karpov

License

GNU GPL, version 3

Description

library to output formatted text on ANSI-compliant terminals

Version

0.1.2

Dependencies
Source

cl-ansi-term.asd (file)

Component

cl-ansi-term.lisp (file)


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

Location

cl-ansi-term.asd

Systems

cl-ansi-term (system)


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

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

Parent

cl-ansi-term (system)

Location

cl-ansi-term.lisp

Packages

cl-ansi-term

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-ansi-term

Source

cl-ansi-term.lisp (file)

Nickname

term

Use List
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: *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 (file)

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 (file)


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

5.1.2 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 (file)

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 (file)

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

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 (file)

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 (file)

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 (file)

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 (file)

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

Package

cl-ansi-term

Source

cl-ansi-term.lisp (file)

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

Package

cl-ansi-term

Source

cl-ansi-term.lisp (file)

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 (file)


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

5.2 Internal definitions


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

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


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

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 (file)


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

5.2.3 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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: print-white-space WIDTH &optional STREAM

Print WIDTH white-spaces to STREAM.

Package

cl-ansi-term

Source

cl-ansi-term.lisp (file)

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 (file)

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 (file)

Function: string* OBJECT

Converts printable object OBJECT to its aesthetic string representation.

Package

cl-ansi-term

Source

cl-ansi-term.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-term.asd: The cl-ansi-term<dot>asd file
cl-ansi-term/cl-ansi-term.lisp: The cl-ansi-term/cl-ansi-term<dot>lisp file

F
File, Lisp, cl-ansi-term.asd: The cl-ansi-term<dot>asd file
File, Lisp, cl-ansi-term/cl-ansi-term.lisp: The cl-ansi-term/cl-ansi-term<dot>lisp file

L
Lisp File, cl-ansi-term.asd: The cl-ansi-term<dot>asd file
Lisp File, cl-ansi-term/cl-ansi-term.lisp: The cl-ansi-term/cl-ansi-term<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

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

A
align-object: Internal functions
ansi-escape-seq: Internal functions

C
cat-print: Exported functions

E
effects-p: Internal functions

F
Function, align-object: Internal functions
Function, ansi-escape-seq: Internal functions
Function, cat-print: Exported functions
Function, effects-p: Internal functions
Function, hr: Exported functions
Function, o-list: Exported functions
Function, parse-control-string: Internal functions
Function, perform-hook: Internal functions
Function, print: Exported functions
Function, print-filler: Internal functions
Function, print-partially: Internal functions
Function, print-white-space: Internal functions
Function, print-words: Internal functions
Function, progress-bar: Exported functions
Function, register-hook: Exported functions
Function, remove-hook: Exported functions
Function, set-style: Internal functions
Function, string*: Internal functions
Function, table: Exported functions
Function, u-list: Exported functions
Function, update-style-sheet: Exported functions

H
hr: Exported functions

M
Macro, with-reasonable-width: Internal macros

O
o-list: Exported functions

P
parse-control-string: Internal functions
perform-hook: Internal functions
print: Exported functions
print-filler: Internal functions
print-partially: Internal functions
print-white-space: Internal functions
print-words: Internal functions
progress-bar: Exported functions

R
register-hook: Exported functions
remove-hook: Exported functions

S
set-style: Internal functions
string*: Internal functions

T
table: Exported functions

U
u-list: Exported functions
update-style-sheet: Exported functions

W
with-reasonable-width: Internal macros

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

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

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*coloration*: Internal special variables
*effects-enabled*: Exported special variables
*hooks*: Internal special variables
*style*: Internal special variables
*style-sheet*: Internal special variables
*terminal-width*: Exported special variables

+
+background-colors+: Internal special variables
+effects+: Internal special variables
+foreground-colors+: Internal special variables

S
Special Variable, *coloration*: Internal special variables
Special Variable, *effects-enabled*: Exported special variables
Special Variable, *hooks*: Internal special variables
Special Variable, *style*: Internal special variables
Special Variable, *style-sheet*: Internal special variables
Special Variable, *terminal-width*: Exported special variables
Special Variable, +background-colors+: Internal special variables
Special Variable, +effects+: Internal special variables
Special Variable, +foreground-colors+: Internal special variables

Jump to:   *   +  
S  

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

A.4 Data types

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