You are looking at historical revision 45082 of this page. It may differ significantly from its current revision.
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
[procedure] (black-escape)[procedure] (red-escape)
[procedure] (green-escape)
[procedure] (yellow-escape)
[procedure] (blue-escape)
[procedure] (magenta-escape)
[procedure] (cyan-escape)
[procedure] (white-escape)
Return a string consisting of an ANSI escape code to select the specified text color.
rgb-escape
[procedure] (rgb-escape red-level green-level blue-level)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
[procedure] (gray-escape gray-level)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
[procedure] (rgb24-escape red-level green-level blue-level)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
[constant] (reset-color-escape)Return a string consisting of an ANSI escape code to select the default text color.
Standard 8-color foreground format procedures
[procedure] (black str)[procedure] (red str)
[procedure] (green str)
[procedure] (yellow str)
[procedure] (blue str)
[procedure] (magenta str)
[procedure] (cyan str)
[procedure] (white str)
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
[procedure] (rgb red-level green-level blue-level)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
[procedure] (gray gray-level)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
[procedure] (rgb24 red-level green-level blue-level)The true-color equivalent of rbg, extending the ranges to [0, 255].
Background colors
Standard 8-color background escape strings
[procedure] (black-background-escape)[procedure] (red-background-escape)
[procedure] (green-background-escape)
[procedure] (yellow-background-escape)
[procedure] (blue-background-escape)
[procedure] (magenta-background-escape)
[procedure] (cyan-background-escape)
[procedure] (white-background-escape)
Return a string consisting of an ANSI escape code to select the specified background color.
rgb-background-escape
[procedure] (rgb-background-escape red-level green-level blue-level)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
[procedure] (gray-background-escape gray-level)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
[procedure] (rgb24-background-escape red-level green-level blue-level)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
[constant] (reset-background-color-escape)Return a string consisting of an ANSI escape code to select the default background color.
Standard 8-color background format procedures
[procedure] (black-background)[procedure] (red-background)
[procedure] (green-background)
[procedure] (yellow-background)
[procedure] (blue-background)
[procedure] (magenta-background)
[procedure] (cyan-background)
[procedure] (white-background)
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
[procedure] (rgb-background red-level green-level blue-level)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
[procedure] (gray-background gray-level)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
[procedure] (rgb24-background red-level green-level blue-level)The true-color equivalent of rbg-background, extending the ranges to [0, 255].
Other properties
bold-escape
[procedure] (bold-escape)Return a string consisting of an ANSI escape code to select bold style.
reset-bold-escape
[procedure] (reset-bold-escape)Return a string consisting of an ANSI escape code to select non-bold style.
bold
[procedure] (bold str)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
[procedure] (underline-escape)Return a string consisting of an ANSI escape code to select underlined style.
reset-underline-escape
[procedure] (reset-underline-escape)Return a string consisting of an ANSI escape code to select non-underlined style.
underline
[procedure] (underline str)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
[procedure] (italic-escape)Return a string consisting of an ANSI escape code to select italic style.
reset-italic-escape
[procedure] (reset-italic-escape)Return a string consisting of an ANSI escape code to select non-italic style.
italic
[constant] (italic str)Returns str optionally wrapped in italic escapes.
strikethrough-escape
[procedure] (strikethrough-escape)Return a string consisting of an ANSI escape code to select strikethrough style.
reset-strike-through-escape
[procedure] (reset-strike-through-escape)Return a string consisting of an ANSI escape code to select non-strikethrough style.
strikethrough
[procedure] (strikethrough str)Returns str optionally wrapped in strikethrough escapes.
negative-escape
[procedure] (negative-escape)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
[procedure] (reset-negative-escape)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
[procedure] (negative str)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?
[parameter] (ansi-escapes-enabled? #!optional value)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.