579 lines
14 KiB
Plaintext
579 lines
14 KiB
Plaintext
\input texinfo
|
|
@c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
@setfilename guile-termenv.info
|
|
@settitle Guile-Termenv Reference Manual
|
|
@documentencoding UTF-8
|
|
@documentlanguage en
|
|
@syncodeindex vr fn
|
|
@syncodeindex tp fn
|
|
@c %**end of header
|
|
|
|
@include version.texi
|
|
|
|
@copying
|
|
Copyright @copyright{} 2024 Vivianne Langdon
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
copy of the license is included in the section entitled ``GNU Free
|
|
Documentation License''.
|
|
@end copying
|
|
|
|
@dircategory The Algorithmic Language Scheme
|
|
@direntry
|
|
* Guile-Termenv: (guile-termenv). ANSI style and color support for
|
|
terminal applications.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title The Guile-Termenv Manual
|
|
@author Juliana Rat
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Edition @value{EDITION} @*
|
|
@value{UPDATED} @*
|
|
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@c *********************************************************************
|
|
@node Top
|
|
@top Guile-Termenv
|
|
|
|
This document describes Guile-Termenv version @value{VERSION}.
|
|
Guile-Termenv is a Guile port of the Go library
|
|
@url{https://github.com/muesli/termenv,termenv}. It analyzes
|
|
information about a terminal's ANSI and color support, then uses this
|
|
to provide a convenient interface for coloring and styling output. It
|
|
is incredibly powerful, and also surprisingly simple. This manual
|
|
provides a brief illustrative tutorial followed by API documentation.
|
|
|
|
@menu
|
|
* Tutorial:: An illustrative tutorial
|
|
* API:: Documentation for public procedures
|
|
@end menu
|
|
|
|
@c *********************************************************************
|
|
@node Tutorial
|
|
@chapter Tutorial
|
|
|
|
TODO
|
|
|
|
@c *********************************************************************
|
|
@node API
|
|
@chapter API
|
|
|
|
The @code{guile-termenv} API aims to be simple and approachable while
|
|
allowing functional patterns and composition.
|
|
|
|
@menu
|
|
* Color:: Procedures to colorize text
|
|
* Hyperlink:: Procedures to convert text to hyperlinks
|
|
* Screen:: Procedures for manipulating the terminal screen
|
|
* Style:: Procedures for styling text
|
|
* Unix:: A procedure to determine a terminal's best color profile
|
|
@end menu
|
|
|
|
@node Color
|
|
@section Color
|
|
|
|
The @code{(termenv color)} module provides a record type representing
|
|
colors, and a set of procedures for creating and using that record.
|
|
|
|
Several color-related procedures accept what this documentation refers
|
|
to as a @dfn{hexcode}. Hexcodes are hexadecimal representations of
|
|
binary data associated with color values. Typically, a hexcode
|
|
consists of six hexadecimal digits split into three pairs. The first
|
|
pair represents the red value, the second pair represents the green
|
|
value, and the third pair represents the blue value. It is also
|
|
possible to use a single digit for each value if both digits are the
|
|
same. In this case, only one digit may be used per color.
|
|
|
|
@code{termenv} accepts hexcodes as strings or as numbers, and it
|
|
recommends numbers. If using numbers, it is further recommended to use
|
|
Guile's base formatting prefix @code{#X} before the value for clarity.
|
|
If using strings, prefixes of any kind are optional and may be either
|
|
@code{#} or @code{0x}.
|
|
|
|
@deftp {Record} color r g b type
|
|
|
|
Record representing a color. This record serves as the central data
|
|
type of this module. It has four fields:
|
|
|
|
@itemize
|
|
@item
|
|
@code{r}: Number in the range 0 to 255 representing the red value of
|
|
the color.
|
|
|
|
@item
|
|
@code{g}: Number in the range 0 to 255 representing the green value of
|
|
the color.
|
|
|
|
@item
|
|
@code{b}: Number in the range 0 to 255 representing the blue value of
|
|
the color.
|
|
|
|
@item
|
|
@code{type}: Either @code{'foreground} or @code{'background}.
|
|
|
|
@end itemize
|
|
|
|
@end deftp
|
|
|
|
@deffn {Procedure} color-r color
|
|
|
|
Accessor for the @code{r} field of the record @var{color},
|
|
representing its red value.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} color-g color
|
|
|
|
Accessor for the @code{g} field of the record @var{color},
|
|
representing its green value.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} color-b color
|
|
|
|
Accessor the @code{b} field of the record @var{color}, representing
|
|
its blue value.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} color? arg
|
|
|
|
Predicate for whether or not @var{arg} is a @code{color}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} make-background hex
|
|
|
|
Create a background @code{color} from the hexcode @var{hex}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} make-foreground hex
|
|
|
|
Create a foreground @code{color} from the hexcode @var{hex}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} hex->color hex [type]
|
|
|
|
Return a @code{color} representing the hexcode @var{hex}, optionally
|
|
with the given @var{type} (@code{'foreground} or @code{'background}).
|
|
|
|
@end deffn
|
|
|
|
@defvr {Parameter} current-color-profile
|
|
|
|
Symbol representing the color profile of the current output port. The
|
|
possible values are:
|
|
|
|
@itemize
|
|
@item
|
|
@var{true-color}: Port supports 24-bit ``true color'' representing
|
|
about 16 million colors.
|
|
|
|
@item
|
|
@var{ansi256}: Port supports a 256-color palette consisting of 216
|
|
colors, 16 ANSI colors, and 24 shades of gray. Color values are
|
|
24-bit.
|
|
|
|
@item
|
|
@var{ansi}: Port supports 16 colors, bold, italics, and background
|
|
coloration.
|
|
|
|
@item
|
|
@var{ascii}: Port does not support colors or styles. In practice, this
|
|
means the output port is not a terminal.
|
|
|
|
@end itemize
|
|
|
|
@end defvr
|
|
|
|
@deffn {Procedure} color->sequence color
|
|
|
|
Return a string of terminal control codes representing the
|
|
@code{color} record @var{color}. Uses @code{current-color-profile}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} color->ansi color
|
|
|
|
Convert the 24-bit ``true color'' @var{color} to the nearest ANSI
|
|
color equivalent.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} color->ansi256 color
|
|
|
|
Convert the 24-bit ``true color'' @var{color} to the nearest 256-color
|
|
ANSI equivalent.
|
|
|
|
@end deffn
|
|
|
|
@node Hyperlink
|
|
@section Hyperlink
|
|
|
|
The @code{(termenv hyperlink)} module provides procedures to create
|
|
active hyperlinks in the terminal.
|
|
|
|
@deffn {Procedure} hyperlink link [name]
|
|
|
|
Create a terminal control sequence which displays the optional string
|
|
@var{name} as a hyperlink to @var{link}. If @var{name} is not
|
|
provided, @var{link} is used verbatim.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} format-hyperlink link [name] [port (current-output-port)]
|
|
|
|
Write the string @var{name} to @var{port}, formatted as a hyperlink to
|
|
@var{link}. This is equivalent to:
|
|
|
|
@lisp
|
|
(format port (hyperlink link name))
|
|
@end lisp
|
|
|
|
If @var{name} is not provided, @var{link} is used verbatim. If
|
|
@var{port} is not provided, @code{current-output-port} is used.
|
|
|
|
@end deffn
|
|
|
|
@node Screen
|
|
@section Screen
|
|
|
|
The @code{(termenv screen)} module provides facilities for controlling
|
|
the general state of a terminal.
|
|
|
|
@deffn {Procedure} reset [port (current-output-port)]
|
|
|
|
Reset @var{port} to its default state, removing any active styles.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} set-foreground-color hex [port (current-output-port)]
|
|
|
|
Apply the hexcode @var{hex} as the default foreground color for
|
|
@var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} set-background-color hex [port (current-output-port)]
|
|
|
|
Apply the hexcode @var{hex} as the default background color for
|
|
@var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} set-cursor-color hex [port (current-output-port)]
|
|
|
|
Apply the hexcode @var{hex} as the default cursor color for
|
|
@var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} save-screen [port (current-output-port)]
|
|
|
|
Save the state of @var{port} so that it may be restored later with
|
|
@code{restore-screen}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} restore-screen [port (current-output-port)]
|
|
|
|
Restore @var{port} to a state previously saved with
|
|
@code{save-screen}.
|
|
|
|
@end deffn
|
|
|
|
Terminals provide a facility called an @dfn{alternate screen} which
|
|
allows a program to write to a blank slate which is wiped away when
|
|
the program terminates. The following procedures allow programmers to
|
|
emit control codes entering and exiting this screen.
|
|
|
|
@deffn {Procedure} alt-screen [port (current-output-port)]
|
|
|
|
Switch @var{port} to the alternate screen buffer.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} exit-alt-screen [port (current-output-port)]
|
|
|
|
Switch @var{port} from the alternate screen buffer to the main screen
|
|
buffer.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} hide-cursor [port (current-output-port)]
|
|
|
|
Hide the cursor of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} show-cursor [port (current-output-port)]
|
|
|
|
Show the cursor of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} save-cursor-position [port (current-output-port)]
|
|
|
|
Save the current position of the cursor of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} restore-cursor-position [port (current-output-port)]
|
|
|
|
Restore the saved position of the cursor of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
Terminals have a concept of a @dfn{scrolling region}. This is the
|
|
region of a terminal screen which is actively being controlled, and
|
|
according to whose coordinates the cursor is moved. Most of the
|
|
following procedures operate on the active scrolling region.
|
|
|
|
@deffn {Procedure} change-scrolling-region top bottom [port (current-output-port)]
|
|
|
|
Set the scrolling region of @var{port} to the area from row number
|
|
@var{top} to row number @var{bottom}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} clear-screen [port (current-output-port)]
|
|
|
|
Clear the scrolling region of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} move-cursor y x [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} to row @var{y} and column @var{x}. Note
|
|
that these values are 1-based, so the top left corner is at the
|
|
coordinates @samp{1,1}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} scroll-up [amount 1] [port (current-output-port)]
|
|
|
|
Scroll @var{port} up by @var{amount} rows.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} scroll-down [amount 1] [port (current-output-port)]
|
|
|
|
Scroll @var{port} down by @var{amount} rows.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-up [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} up @var{distance} rows.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-down [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} down @var{distance} rows.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-forward [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} forward @var{distance} columns.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-back [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} backwards @var{distance} columns.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-next-line [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} up @var{distance} rows and place it at
|
|
the beginning of the line.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cursor-prev-line [distance 1] [port (current-output-port)]
|
|
|
|
Move the cursor of @var{port} down @var{distance} rows and place it at
|
|
the beginning of the line.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} clear-line [port (current-output-port)]
|
|
|
|
Clear the current line of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} clear-line-left [port (current-output-port)]
|
|
|
|
Clear the current line of @var{port} left of its cursor.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} clear-line-right [port (current-output-port)]
|
|
|
|
Clear the current line of @var{port} right of its cursor.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} clear-lines n [port (current-output-port)]
|
|
|
|
Clear @var{n} lines of @var{port}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} insert-lines n [port (current-output-port)]
|
|
|
|
Insert @var{n} blank rows at the top of the scrolling region of
|
|
@var{port}, pushing lower rows down.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} delete-lines n [port (current-output-port)]
|
|
|
|
Delete @var{n} rows at the top of the scrolling region of @var{port},
|
|
pulling any rows below up.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} set-window-title title [port (current-output-port)]
|
|
|
|
Set the window title of @var{port} to @var{title}.
|
|
|
|
@end deffn
|
|
|
|
@node Style
|
|
@section Style
|
|
|
|
The @code{(termenv style)} module provides procedures for manipulating
|
|
the style and color (@pxref{Color}) of text.
|
|
|
|
@deffn {Procedure} foreground c s @dots{}
|
|
|
|
Return a string of terminal control codes representing the string or
|
|
strings @var{s} with the foreground color indicated by the hexcode
|
|
@var{c}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} background c s @dots{}
|
|
|
|
Return a string of terminal control codes representing the string or
|
|
strings @var{s} with the background color indicated by the hexcode
|
|
@var{c}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} bold s @dots{}
|
|
|
|
Return a string of terminal control codes to render the string or
|
|
strings @var{s} in boldface.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} faint s @dots{}
|
|
|
|
Return a string of terminal control codes to render the string or
|
|
strings @var{s} faintly.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} italic s @dots{}
|
|
|
|
Return a string of terminal control codes to italicize the string or
|
|
strings @var{s}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} underline s @dots{}
|
|
|
|
Return a string of terminal control codes to underline the string or
|
|
strings @var{s}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} overline s @dots{}
|
|
|
|
Return a string of terminal control codes to overline the string or
|
|
strings @var{s}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} blink s @dots{}
|
|
|
|
Return a string of terminal control codes to render the string or
|
|
strings @var{s} blinking.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} invert s @dots{}
|
|
|
|
Return a string of terminal control codes to reverse the string or
|
|
strings @var{s}.
|
|
|
|
@end deffn
|
|
|
|
@deffn {Procedure} cross-out s @dots{}
|
|
|
|
Return a string of terminal control codes to cross out the string or
|
|
strings @var{s} in boldface.
|
|
|
|
@end deffn
|
|
|
|
@node Unix
|
|
@section Unix
|
|
|
|
The @code{(termenv unix)} module provides a single procedure for
|
|
determining the color and control code support of a terminal.
|
|
|
|
@deffn {Procedure} color-profile port
|
|
|
|
Test the characteristics of the terminal indicated by @code{port} and
|
|
return a symbol indicating its highest-bit color profile. Returns one
|
|
of:
|
|
|
|
@itemize
|
|
@item
|
|
@var{true-color}: Port supports 24-bit ``true color'' representing
|
|
about 16 million colors.
|
|
|
|
@item
|
|
@var{ansi256}: Port supports a 256-color palette consisting of 216
|
|
colors, 16 ANSI colors, and 24 shades of gray. Color values are
|
|
24-bit.
|
|
|
|
@item
|
|
@var{ansi}: Port supports 16 colors, bold, italics, and background
|
|
coloration.
|
|
|
|
@item
|
|
@var{ascii}: Port does not support colors or styles. In practice, this
|
|
means the output port is not a terminal.
|
|
|
|
@end itemize
|
|
|
|
@end deffn
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex fn
|
|
|
|
@bye
|