67 lines
2.9 KiB
Groff
67 lines
2.9 KiB
Groff
.TH CTLSEQS 7 "Sep 01, 2020" 0.1.0 "Ctlseqs Library Manual"
|
|
.
|
|
.SH NAME
|
|
ctlseqs - helper library for terminal control sequences
|
|
.
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <ctlseqs.h>
|
|
.PP
|
|
.B #define __cplusplus 201103L
|
|
.BR "#include <ctlseqs.hh>" " /* C++ Wrapper */"
|
|
.fi
|
|
.
|
|
.SH DESCRIPTION
|
|
The ctlseqs library provides low-level API for manipulating terminal emulators with control sequences.
|
|
.SS Terminal escape sequences
|
|
Terminals and hosts exchange control information regarding colors, font styles, cursor position, etc., using escape sequences embedded in normal text.
|
|
.PP
|
|
In distant past, when there are no standard protocols to apply, those escape sequences are largely vendor-specific.
|
|
We can assume that most, if not all modern terminal emulators recognize ANSI-compliant escape sequences, as well as supporting popular control functions like the ones shipped with DEC VT100 series.
|
|
However, this is not guaranteed, and using raw escape sequences is prone to broken compatibility.
|
|
.PP
|
|
While most text-based applications should stick to terminfo/ncurses, there are occasions when dealing with raw escape sequences is inevitable.
|
|
For example, when trying to make use of proprietary features provided by a specific terminal emulator.
|
|
Or perhaps, when implementing one's own terminal emulator.
|
|
.PP
|
|
Writing escape sequences is pretty straightforward, but reading and processing them could be tricky, and not trivial to implement.
|
|
.SS The ctlseqs library
|
|
The ctlseqs library tries to make your life easier when dealing with raw escape sequences.
|
|
There are three major concepts in the library, the reader, the matcher, and the helper macros.
|
|
.PP
|
|
The reader is responsible to read arbitrary data from a file descriptor, buffer it, and check whether it (or part of it) is a valid terminal control sequence.
|
|
.PP
|
|
The matcher is configured with patterns describing a terminal control sequence.
|
|
After a sequence is successfully read, it can be matched against the patterns, and according to which, values can be extracted.
|
|
.PP
|
|
The helper macros include C0 (7-bit) control characters, commonly used control sequences (mostly CSI sequences) from DEC VTxxx series and XTerm, and placeholders.
|
|
Helper macros always expand to string literals.
|
|
.PP
|
|
For reader/matcher details, see the corresponding man page in section 3.
|
|
For helper macro details, see the source code of the
|
|
.I ctlseqs.h
|
|
header.
|
|
.
|
|
.SH BUGS
|
|
C1 (8-bit) control characters are not supported.
|
|
.
|
|
.SH SEE ALSO
|
|
.BR terminfo (5),
|
|
.BR ncurses (3X)
|
|
.PP
|
|
.BR ctlseqs_matcher_init (3),
|
|
.BR ctlseqs_matcher_setopt (3),
|
|
.BR ctlseqs_matcher_free (3)
|
|
.PP
|
|
.BR ctlseqs_reader_init (3),
|
|
.BR ctlseqs_reader_setopt (3),
|
|
.BR ctlseqs_reader_free (3)
|
|
.PP
|
|
.BR ctlseqs_read (3)
|
|
.
|
|
.SH COPYRIGHT
|
|
Copyright (c) 2020 CismonX <admin@cismon.net>
|
|
.PP
|
|
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
|
|
This file is offered as-is, without any warranty.
|