chickadee » chibi-term

chibi-term

Chibi Scheme's term library

Module: (chibi term ansi)

A library to use ANSI escape codes to format text and background color, font weight, and underlining.

Foreground colors

Standard 8-color foreground escape strings

black-escapeprocedure

red-escapeprocedure

green-escapeprocedure

yellow-escapeprocedure

blue-escapeprocedure

magenta-escapeprocedure

cyan-escapeprocedure

white-escapeprocedure

Return a string consisting of an ANSI escape code to select the specified text color.

rgb-escape

rgb-escape red-level green-level blue-levelprocedure

Return a string consisting of an ANSI escape code to select the text color specified by the red-level, green-level, and blue-level arguments, each of which must be an exact integer in the range [0, 5].

The caller is resonsible for verifying that the terminal supports 256 colors.

gray-escape

gray-escape gray-levelprocedure

Return a string consisting of an ANSI escape code to select the text color specified by the gray-level argument, which must be an exact integer in the range [0, 23].

The caller is resonsible for verifying that the terminal supports 256 colors.

rgb24-escape

rgb24-escape red-level green-level blue-levelprocedure

The true-color equivalent of rgb-escape. Return a string consisting of an ANSI escape code to select the text color specified by the red-level,green-level, and blue-level arguments, each of which must be an exact integer in the range [0, 255].

reset-color-escape

reset-color-escapeconstant

Return a string consisting of an ANSI escape code to select the default text color.

Standard 8-color foreground format procedures

black strprocedure

red strprocedure

green strprocedure

yellow strprocedure

blue strprocedure

magenta strprocedure

cyan strprocedure

white strprocedure

If ANSI escapes are enabled, return a string consisting of the string str with a prefix that selects specified text color and a suffix that selects the default text color.

If ANSI escapes are not enabled, return str.

rgb

rgb red-level green-level blue-levelprocedure

Returns a procedure which takes a single argument, a string, and which when called behaves as follows.

If ANSI escapes are enabled, the procedure returns a string consisting of its argument with a prefix that selects specified text color (obtained by calling the rgb-escape procedure with the values of the red-level, green-level, and blue-level arguments) and a suffix that selects the default text color.

If ANSI escapes are not enabled, the procedure returns its argument.

The caller is resonsible for verifying that the terminal supports 256 colors.

gray

gray gray-levelprocedure

Returns a procedure which takes a single argument, a string, and which when called behaves as follows.

If ANSI escapes are enabled, the procedure returns a string consisting of its argument with a prefix that selects specified text color (obtained by calling the gray-escape procedure with the values of the gray-level argument) and a suffix that selects the default text color.

If ANSI escapes are not enabled, the procedure returns its argument.

The caller is resonsible for verifying that the terminal supports 256 colors.

rgb24

rgb24 red-level green-level blue-levelprocedure

The true-color equivalent of rbg, extending the ranges to [0, 255].

Background colors

Standard 8-color background escape strings

black-background-escapeprocedure

red-background-escapeprocedure

green-background-escapeprocedure

yellow-background-escapeprocedure

blue-background-escapeprocedure

magenta-background-escapeprocedure

cyan-background-escapeprocedure

white-background-escapeprocedure

Return a string consisting of an ANSI escape code to select the specified background color.

rgb-background-escape

rgb-background-escape red-level green-level blue-levelprocedure

Return a string consisting of an ANSI escape code to select the background color specified by the red-level, green-level, and blue-level arguments, each of which must be an exact integer in the range [0, 5].

The caller is resonsible for verifying that the terminal supports 256 colors.

gray-background-escape

gray-background-escape gray-levelprocedure

Return a string consisting of an ANSI escape code to select the background color specified by the gray-level argument, which must be an exact integer in the range [0, 23].

The caller is resonsible for verifying that the terminal supports 256 colors.

rgb24-background-escape

rgb24-background-escape red-level green-level blue-levelprocedure

The true-color equivalent of rgb-background-escape. Return a string consisting of an ANSI escape code to select the text color specified by the red-level, green-level,and blue-level arguments, each of which must be an exact integer in the range [0, 255].

reset-background-color-escape

reset-background-color-escapeconstant

Return a string consisting of an ANSI escape code to select the default background color.

Standard 8-color background format procedures

black-backgroundprocedure

red-backgroundprocedure

green-backgroundprocedure

yellow-backgroundprocedure

blue-backgroundprocedure

magenta-backgroundprocedure

cyan-backgroundprocedure

white-backgroundprocedure

If ANSI escapes are enabled, return a string consisting of the string str with a prefix that selects specified background color and a suffix that selects the default background color.

If ANSI escapes are not enabled, return str.

rgb-background

rgb-background red-level green-level blue-levelprocedure

Returns a procedure which takes a single argument, a string, and which when called behaves as follows.

If ANSI escapes are enabled, the procedure returns a string consisting of its argument with a prefix that selects specified background color (obtained by calling the rgb-background-escape procedure with the values of the red-level, green-level,and blue-level arguments) and a suffix that selects the default background color.

If ANSI escapes are not enabled, the procedure returns its argument.

The caller is resonsible for verifying that the terminal supports 256 colors.

gray-background

gray-background gray-levelprocedure

Returns a procedure which takes a single argument, a string, and which when called behaves as follows.

If ANSI escapes are enabled, the procedure returns a string consisting of its argument with a prefix that selects specified background color (obtained by calling the gray-background-escape procedure with the values of the gray-level argument) and a suffix that selects the default background color.

If ANSI escapes are not enabled, the procedure returns its argument.

The caller is resonsible for verifying that the terminal supports 256 colors.

rgb24-background

rgb24-background red-level green-level blue-levelprocedure

The true-color equivalent of rbg-background, extending the ranges to [0, 255].

Other properties

bold-escape

bold-escapeprocedure

Return a string consisting of an ANSI escape code to select bold style.

reset-bold-escape

reset-bold-escapeprocedure

Return a string consisting of an ANSI escape code to select non-bold style.

bold

bold strprocedure

If ANSI escapes are enabled, return a string consisting of the string str with a prefix that selects bold style and a suffix that selects non-bold style.

If ANSI escapes are not enabled, return str.

underline-escape

underline-escapeprocedure

Return a string consisting of an ANSI escape code to select underlined style.

reset-underline-escape

reset-underline-escapeprocedure

Return a string consisting of an ANSI escape code to select non-underlined style.

underline

underline strprocedure

If ANSI escapes are enabled, return a string consisting of the string str with a prefix that selects underlined style and a suffix that selects non-underlined style.

If ANSI escapes are not enabled, return str.

italic-escape

italic-escapeprocedure

Return a string consisting of an ANSI escape code to select italic style.

reset-italic-escape

reset-italic-escapeprocedure

Return a string consisting of an ANSI escape code to select non-italic style.

italic

italic strconstant

Returns str optionally wrapped in italic escapes.

strikethrough-escape

strikethrough-escapeprocedure

Return a string consisting of an ANSI escape code to select strikethrough style.

reset-strike-through-escape

reset-strike-through-escapeprocedure

Return a string consisting of an ANSI escape code to select non-strikethrough style.

strikethrough

strikethrough strprocedure

Returns str optionally wrapped in strikethrough escapes.

negative-escape

negative-escapeprocedure

Return a string consisting of an ANSI escape code to select negative style (text in the background color and background in the text color).

reset-negative-escape

reset-negative-escapeprocedure

Return a string consisting of an ANSI escape code to select positive style (text in the text color and background in the background color).

negative

negative strprocedure

If ANSI escapes are enabled, return a string consisting of the string str with a prefix that selects negative style (text in the background color and background in the text color) and a suffix that selects positive style (text in the text color and background in the background color).

If ANSI escapes are not enabled, return str.

Enabling or disabling ANSI escapes

ansi-escapes-enabled?

ansi-escapes-enabled? #!optional valueparameter

A parameter object that determines whether ANSI escapes are enabled in some of the preceding procedures. They are disabled if (ansi-escapes-enabled?) returns #f, and otherwise they are enabled.

The initial value returned by (ansi-escapes-enabled?) is determined by the environment.

If the environment variable NO_COLOR is set, the initial value is #f

If the environment variable ANSI_ESCAPES_ENABLED is set, its value determines the initial value returned by (ansi-escapes-enabled?). If the value of ANSI_ESCAPES_ENABLED is "0", the initial value is #f,otherwise the initial value is #t.

If the environment variable ANSI_ESCAPES_ENABLED is not set and the environment variable TERM is set to dumb, the initial value is #f.

If neither of the environment variables NO_COLOR, ANSI_ESCAPES_ENABLED are set and TERM is not dumb, the initial value returned by (ansi-escapes-enabled?) is #t.

Note: The initial value logic has been modifien in the CHICKEN implementation. Chibi's original library did not support NO_COLOR and used a hard-coded list of known TERM values to set the initial value to #t and otherwise default to #f.

Notes

It is important to remember that the formatting procedures apply a prefix to set a particular graphics parameter and a suffix to reset the parameter to its default value. This can lead to surprises. For example, on an ANSI terminal, one might mistakenly expect the following to display GREEN in green text and then RED in red text:

(display (red (string-append (green "GREEN") "RED")))

However, it will actually display GREEN in green text and then RED in the default text color. This is a limitation of ANSI control codes; graphics attributes are not saved to and restored from a stack, but instead are simply set. One way to display GREEN in green text and then RED in red text is:

(display (string-append (green "GREEN") (red "RED")))

On the other hand, text color, background color, font weight (bold or default), underline (on or off), image (positive or negative) are orthogonal. So, for example, on an ANSI terminal the following should display GREEN in green text and then RED in red text, with both in bold and GREEN underlined.

(display (bold (string-append (underline (green "GREEN")) (red "RED"))))

Maintainer

Diego A. Mundo

Author

Alex Shinn

Version History

0.1.0

Initial library port

License

BSD

Copyright (c) 2009-2021 Alex Shinn 
All rights reserved. 
 
Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 
1. Redistributions of source code must retain the above copyright 
   notice, this list of conditions and the following disclaimer. 
2. Redistributions in binary form must reproduce the above copyright 
   notice, this list of conditions and the following disclaimer in the 
   documentation and/or other materials provided with the distribution. 
3. The name of the author may not be used to endorse or promote products 
   derived from this software without specific prior written permission. 
 
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.