cl-ansi-term Library

This document describes cl-ansi-term library, utility that aids to print various primitives on ANSI-compliant terminals. This program is distributed under GNU General Public License, version 3.

All symbols described in this document live in cl-ansi-term package, it has the following nicknames: term.

1. Graphic Rendition

This chapter describes variables and functions that allow to control graphic rendition on ANSI-complaint terminals.

cl-ansi-term uses the concept of style sheets for graphic rendition. This means that the programmer doesn’t need to specify all rendition parameters every time he/she wants to use specific graphical effects. Instead, the programmer is provided with the tools to define styles of output, and then use abstract names of the styles to specify how output should be rendered. This allows to reduce repetition of rendition parameters in code and avoid associated errors.

Note that cl-ansi-term is able to detect when the output goes to a file instead of a terminal. In this case, it does not print escape sequences.

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.

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’s always represent default parameters of rendition.

Example:

(update-style-sheet
 '((:header :cyan   :underline)
   (:mark   :red    :reverse)
   (:term   :yellow :bold)))

Foreground colors are (default value is :default):

• :default
• :black
• :red
• :green
• :yellow
• :blue
• :magneta
• :cyan
• :white*
• :black*
• :red*
• :green*
• :yellow*
• :blue*
• :magneta*
• :cyan*
• :white*

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

Background colors are (default value is :b-default):

• :b-default
• :b-black
• :b-red
• :b-green
• :b-yellow
• :b-blue
• :b-magneta
• :b-cyan
• :b-white*
• :b-black*
• :b-red*
• :b-green*
• :b-yellow*
• :b-blue*
• :b-magneta*
• :b-cyan*
• :b-white*

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

Rendition effects are (default value is :normal):

• :bold – bold or increased intensity
• :faint – decreased intensity (not widely supported)
• :italic – not widely supported, sometimes treated as inverse
• :underline – single underline
• :blink – less than 150 per minute
• :bad-blink – MS-DOS ANSI.SYS, 150+ per minute, not widely supported
• :inverse – swap foreground and background colors, reverse video
• :hide – not widely supported
• :fraktur – hardly ever supported
• :normal – normal color and intensity
• :framed
• :encircled
• :overlined

2. Primitives

This chapter describes a variable and functions to print various primitives on ANSI-complaint terminals. All the functions take many keyword parameters so the programmer has great control over them.

Variable: *terminal-width*

Many functions use this value to output text nicely. Default value is 80. If you want to dynamically change this value, write and register :before-printing hook and reassign terminal width before printing takes place (see section Hooks).

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.

Example:

(term:cat-print '(:abc :def :ghi)) ABCDEFGHI (term:cat-print '(:abc :def :ghi) :align :center) ABCDEFGHI

Function: print-styled 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.

Example:

(term:print-styled "~ and ~" :args '("foo" "bar")) ;; "foo and bar"

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.

Example:

(term:hr :filler "=") ================================================================================

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.

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.

Example:

(term:u-list '((:one one-a :one-b) :two)) * ONE - ONE-A - ONE-B * TWO

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

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

Example:

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

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

Example:

(term:table (list '("name" "age") '("me" "7"))) +---------+---------+ |name |age | +---------+---------+ |me |7 | +---------+---------+

3. Hooks

This chapter describes functions that allow to register custom hooks that will be invoked on specific predefined events.

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 is printed. One argument is passed to function, name of the style, which is a keyword.

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.

Concept Index

Function and Variable Index

Table of Contents

About This Document

This document was generated by vince on May 1, 2020 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by vince on May 1, 2020 using texi2html 1.82.