Add basic documentation
This commit is contained in:
parent
43b2f86d88
commit
b0fc09e3ad
2 changed files with 567 additions and 9 deletions
40
README.org
40
README.org
|
|
@ -2,3 +2,43 @@
|
|||
|
||||
#+TITLE: README for Guile-Termenv
|
||||
|
||||
~guile-termenv~ is a port of [[https://github.com/muesli/termenv][termenv]] to Guile. It provides a convenient
|
||||
interface to ANSI control sequences so you can color and style output without
|
||||
need to bother with arcane symbols, all to the height of your terminal's
|
||||
capabilities.
|
||||
|
||||
While ~guile-termenv~ is not a 1:1 port of ~termenv~, it does provide much of
|
||||
the same functionality, and it aims to fill the same niche in the Guile
|
||||
ecosystem that ~termenv~ does in the Go ecosystem.
|
||||
|
||||
* Building
|
||||
|
||||
~guile-termenv~ is developed using [[https://guix.gnu.org][Guix]] and the simplest way to build it is with
|
||||
Guix. Running ~guix build -f guix.scm~ will build and test the project, placing
|
||||
it in the store. Instead using ~guix shell -f guix.scm~ will create an
|
||||
environment with the project, and ~guix profile -if guix.scm~ will install it.
|
||||
|
||||
If you wish to use a more manual build methodology, you can replicate the build
|
||||
steps like so:
|
||||
|
||||
#+BEGIN_SRC shell
|
||||
guix shell -Df guix.scm
|
||||
hall build -x
|
||||
autoreconf -vif
|
||||
./configure
|
||||
make -j
|
||||
#+END_SRC
|
||||
|
||||
Note that it is not advised to install the project this way.
|
||||
|
||||
If you don't have or don't want to use Guix, ~guile-termenv~ requires the
|
||||
following dependencies to build:
|
||||
|
||||
- autoconf
|
||||
- automake
|
||||
- guile-hall
|
||||
- pkg-config
|
||||
- texinfo
|
||||
|
||||
With those dependencies installed, the same build commands as above will work,
|
||||
although the ~guix~ command becomes redundant.
|
||||
|
|
|
|||
|
|
@ -3,14 +3,17 @@
|
|||
|
||||
@c %**start of header
|
||||
@setfilename guile-termenv.info
|
||||
@documentencoding UTF-8
|
||||
@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
|
||||
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
|
||||
|
|
@ -22,12 +25,13 @@ Documentation License''.
|
|||
|
||||
@dircategory The Algorithmic Language Scheme
|
||||
@direntry
|
||||
* Guile-Termenv: (guile-termenv).
|
||||
* Guile-Termenv: (guile-termenv). ANSI style and color support for
|
||||
terminal applications.
|
||||
@end direntry
|
||||
|
||||
@titlepage
|
||||
@title The Guile-Termenv Manual
|
||||
@author
|
||||
@author Juliana Rat
|
||||
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
|
|
@ -44,17 +48,531 @@ Edition @value{EDITION} @*
|
|||
@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
|
||||
* Introduction:: Why Guile-Termenv?
|
||||
* Tutorial:: An illustrative tutorial
|
||||
* API:: Documentation for public procedures
|
||||
@end menu
|
||||
|
||||
@c *********************************************************************
|
||||
@node Introduction
|
||||
@chapter Introduction
|
||||
@node Tutorial
|
||||
@chapter Tutorial
|
||||
|
||||
INTRODUCTION HERE
|
||||
TODO
|
||||
|
||||
This documentation is a stub.
|
||||
@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
|
||||
|
|
|
|||
Loading…
Reference in a new issue