Update README and documentation.
This commit is contained in:
parent
823544151e
commit
67d48ebc09
|
@ -0,0 +1,46 @@
|
||||||
|
<!--
|
||||||
|
Copyright (C) 2020 CismonX <admin@cismon.net>
|
||||||
|
|
||||||
|
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.
|
||||||
|
-->
|
||||||
|
|
||||||
|
# INSTALL
|
||||||
|
|
||||||
|
## Copy Library Code to Your Project
|
||||||
|
|
||||||
|
This is the recommended way to use this library.
|
||||||
|
|
||||||
|
Copy [ctlseqs.h](src/ctlseqs.h) and [ctlseqs.c](src/ctlseqs.c) to your project and build it alongside with other code. Requires an ISO C99 and POSIX.1-2008 compliant C implementation.
|
||||||
|
|
||||||
|
## Build and Install From Source
|
||||||
|
|
||||||
|
Helper scripts are provided to build ctlseqs as a shared/static library. Requires GNU Autoconf, Automake, Libtool and Autoconf Archive.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
autoreconf --install
|
||||||
|
./configure --prefix=$HOME CFLAGS='-O0 -g'
|
||||||
|
make
|
||||||
|
```
|
||||||
|
|
||||||
|
Optionally, you can run tests (requires DejaGnu), install the binary and man pages.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
make check && make install
|
||||||
|
```
|
||||||
|
|
||||||
|
Finally, link it to your project with the `-lctlseqs` flag (or something similar).
|
||||||
|
|
||||||
|
## Install From a Package Manager
|
||||||
|
|
||||||
|
We maintain unofficial repositories for a few package managers, so that the ctlseqs library can be installed from them.
|
||||||
|
|
||||||
|
However, there is no guarantee that any of those repositories will be actively maintained in the future.
|
||||||
|
|
||||||
|
### Homebrew
|
||||||
|
|
||||||
|
```shell
|
||||||
|
brew tap CismonX/repos
|
||||||
|
brew install ctlseqs
|
||||||
|
```
|
53
INSTALL.org
53
INSTALL.org
|
@ -1,53 +0,0 @@
|
||||||
#
|
|
||||||
# Copyright (C) 2020 CismonX <admin@cismon.net>
|
|
||||||
#
|
|
||||||
# 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.
|
|
||||||
#
|
|
||||||
|
|
||||||
#+TITLE: Installation Guidelines
|
|
||||||
|
|
||||||
** Copy Library Code to Your Project
|
|
||||||
|
|
||||||
This is the recommended way to use this library. Just copy [[file:src/ctlseqs.h][ctlseqs.h]] and
|
|
||||||
[[file:src/ctlseqs.c][ctlseqs.c]] to your project and build it alongside with other code.
|
|
||||||
|
|
||||||
Requires an ISO C99 and POSIX.1-2008 compliant C implementation.
|
|
||||||
|
|
||||||
** Build and Install From Source
|
|
||||||
|
|
||||||
Alternatively, You may want a systemwide installation of the library and
|
|
||||||
link it to your project. Some scripts are provided to help you with that.
|
|
||||||
|
|
||||||
Requires GNU Autoconf, Automake, Libtool and Autoconf Archive.
|
|
||||||
|
|
||||||
#+BEGIN_SRC shell
|
|
||||||
autoreconf --install
|
|
||||||
./configure --prefix=$HOME CFLAGS='-O0 -g'
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
Compile the library source code, as well as [[file:examples][examples]] and test suites.
|
|
||||||
Optionally, you can run the test suite (requires DejaGnu), install the
|
|
||||||
binary and man pages.
|
|
||||||
|
|
||||||
#+BEGIN_SRC shell
|
|
||||||
make && make check && make install
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
Finally, link it to your project with the ~-lctlseqs~ (or similar) flag.
|
|
||||||
|
|
||||||
** Install From a Package Manager
|
|
||||||
|
|
||||||
We maintain unofficial repositories for a few package managers, so that the
|
|
||||||
ctlseqs library can be installed from them.
|
|
||||||
|
|
||||||
However, there is no guarantee that any of those repositories will be
|
|
||||||
actively maintained in the future.
|
|
||||||
|
|
||||||
*** Homebrew
|
|
||||||
|
|
||||||
#+BEGIN_SRC shell
|
|
||||||
brew tap CismonX/repos
|
|
||||||
brew install ctlseqs
|
|
||||||
#+END_SRC
|
|
|
@ -0,0 +1,28 @@
|
||||||
|
<!--
|
||||||
|
Copyright (C) 2020 CismonX <admin@cismon.net>
|
||||||
|
|
||||||
|
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.
|
||||||
|
-->
|
||||||
|
|
||||||
|
# README
|
||||||
|
|
||||||
|
[![Travis CI](https://travis-ci.com/CismonX/ctlseqs.svg)](https://travis-ci.com/CismonX/ctlseqs)
|
||||||
|
[![LICENSE](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](COPYING)
|
||||||
|
|
||||||
|
ctlseqs - helper library for terminal control sequences
|
||||||
|
|
||||||
|
# Description
|
||||||
|
|
||||||
|
The ctlseqs library provides C API for manipulating terminal emulators with control sequences.
|
||||||
|
|
||||||
|
Ctlseqs is free software. you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|
||||||
|
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
To install and use the library, see [INSTALL.md](INSTALL.md) for details.
|
||||||
|
|
||||||
|
For documentation, see the [**ctlseqs**(7)](man/ctlseqs.7) man page, and also [*XTerm Control Sequences*](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) if you're unfamiliar with them.
|
||||||
|
|
||||||
|
Some [examples](examples) are provided to demonstrate the basic usage of this library.
|
35
README.org
35
README.org
|
@ -1,35 +0,0 @@
|
||||||
#
|
|
||||||
# Copyright (C) 2020 CismonX <admin@cismon.net>
|
|
||||||
#
|
|
||||||
# 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.
|
|
||||||
#
|
|
||||||
|
|
||||||
#+TITLE: README
|
|
||||||
|
|
||||||
[[https://travis-ci.com/CismonX/ctlseqs][https://travis-ci.com/CismonX/ctlseqs.svg]]
|
|
||||||
[[file:COPYING][https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg]]
|
|
||||||
|
|
||||||
ctlseqs - helper library for terminal control sequences
|
|
||||||
|
|
||||||
** Description
|
|
||||||
|
|
||||||
The ctlseqs library provides low-level C API for manipulating terminal
|
|
||||||
emulators with control sequences.
|
|
||||||
|
|
||||||
Ctlseqs is free software. you can redistribute it and/or modify it
|
|
||||||
under the terms of the GNU General Public License as published by the
|
|
||||||
Free Software Foundation, either version 3 of the License, or (at your
|
|
||||||
option) any later version.
|
|
||||||
|
|
||||||
** Getting Started
|
|
||||||
|
|
||||||
Build from source or install from a package manager. See [[file:INSTALL.org][INSTALL.org]]
|
|
||||||
for details.
|
|
||||||
|
|
||||||
For documentation, see the [[man/ctlseqs.7][ctlseqs(7)]] man page, and also
|
|
||||||
[[https://invisible-island.net/xterm/ctlseqs/ctlseqs.html][XTerm Control Sequences]] if you're unfamiliar with them.
|
|
||||||
|
|
||||||
Some [[file:examples][examples]] are provided to demonstrate the basic usage of this
|
|
||||||
library.
|
|
|
@ -9,7 +9,7 @@ ctlseqs - helper library for terminal control sequences
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
The ctlseqs library provides low-level API for manipulating terminal emulators with control sequences.
|
The ctlseqs library provides C API for manipulating terminal emulators with control sequences.
|
||||||
.SS Terminal escape 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.
|
Terminals and hosts exchange control information regarding colors, font styles, cursor position, etc., using escape sequences embedded in normal text.
|
||||||
.PP
|
.PP
|
||||||
|
@ -39,7 +39,7 @@ For helper macro details, see the source code of the
|
||||||
.I ctlseqs.h
|
.I ctlseqs.h
|
||||||
header.
|
header.
|
||||||
.
|
.
|
||||||
.SH BUGS
|
.SH NOTES
|
||||||
C1 (8-bit) control characters are not supported.
|
C1 (8-bit) control characters are not supported.
|
||||||
.
|
.
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
|
|
|
@ -53,6 +53,26 @@ Success.
|
||||||
.B CTLSEQS_NOMEM
|
.B CTLSEQS_NOMEM
|
||||||
Fails to allocate sufficient memory.
|
Fails to allocate sufficient memory.
|
||||||
.
|
.
|
||||||
|
.SH NOTES
|
||||||
|
Any value in
|
||||||
|
.I patterns
|
||||||
|
must correspond to an ECMA-35/ECMA-48 conformant escape sequence, and should also be supported by the matcher.
|
||||||
|
Otherwise, function behaviour is undefined.
|
||||||
|
.PP
|
||||||
|
Currently supported escape sequences:
|
||||||
|
.TP
|
||||||
|
.B CSI [param...] [intmd...] final
|
||||||
|
Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and final byte 0x40\(ti0x7e.
|
||||||
|
.TP
|
||||||
|
.B (APC|DCS|OSC|PM) [cmdstr] ST
|
||||||
|
Command string consists of bytes of printable characters and characters of range 0x08\(ti0x0d.
|
||||||
|
.TP
|
||||||
|
.B (SS2|SS3) ch
|
||||||
|
The byte following a single-shift should be a printable character.
|
||||||
|
.TP
|
||||||
|
.B SOS [chrstr] ST
|
||||||
|
Character string can be any bit combination which does not represent SOS or ST.
|
||||||
|
.
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
.BR ctlseqs (7)
|
.BR ctlseqs (7)
|
||||||
.
|
.
|
||||||
|
|
|
@ -25,8 +25,8 @@ is zero, this function has no effect.
|
||||||
This function has no return values.
|
This function has no return values.
|
||||||
.
|
.
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
This function is useful when dealing with partial sequences returned by
|
The function is useful when dealing with partial sequences returned by
|
||||||
.BR ctlseqs_read ()
|
.BR ctlseqs_read (),
|
||||||
whose future completion is not desired.
|
whose future completion is not desired.
|
||||||
.
|
.
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
|
|
|
@ -41,7 +41,7 @@ is enabled, this argument has no effect.
|
||||||
.SH RETURN VALUE
|
.SH RETURN VALUE
|
||||||
If a control sequence is successfully read, and matches at least one pattern in
|
If a control sequence is successfully read, and matches at least one pattern in
|
||||||
.IR matcher ,
|
.IR matcher ,
|
||||||
returns a non-negative integer representing the offset of one of the matching patterns.
|
returns a non-negative integer representing the offset of a matching pattern.
|
||||||
.PP
|
.PP
|
||||||
Otherwise, returns a negative value:
|
Otherwise, returns a negative value:
|
||||||
.TP
|
.TP
|
||||||
|
@ -75,25 +75,6 @@ An unexpected error occurs during a system call within the function.
|
||||||
.B CTLSEQS_INTR
|
.B CTLSEQS_INTR
|
||||||
A system call within the function is interrupted by a signal, and no data is read.
|
A system call within the function is interrupted by a signal, and no data is read.
|
||||||
.
|
.
|
||||||
.SH NOTES
|
|
||||||
Any pattern in
|
|
||||||
.I matcher
|
|
||||||
must be a ECMA-35/ECMA-48 conformant escape sequence, and should also be recognizable by the matcher.
|
|
||||||
Otherwise, function behaviour is undefined.
|
|
||||||
.PP
|
|
||||||
Currently supported escape sequences:
|
|
||||||
.TP
|
|
||||||
.B CSI [param...] [intmd...] final
|
|
||||||
Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and final byte 0x40\(ti0x7e.
|
|
||||||
.TP
|
|
||||||
.B (APC|DCS|OSC|PM) [cmdstr] ST
|
|
||||||
Command string consists of bytes of printable characters and characters of range 0x08\(ti0x0d.
|
|
||||||
.TP
|
|
||||||
.B (SS2|SS3) ch
|
|
||||||
The byte following a single-shift should be a printable character.
|
|
||||||
.TP
|
|
||||||
.B SOS [chrstr] ST
|
|
||||||
Character string can be any bit combination which does not represent SOS or ST.
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
.BR ctlseqs_matcher_config (3),
|
.BR ctlseqs_matcher_config (3),
|
||||||
.BR ctlseqs_reader_config (3)
|
.BR ctlseqs_reader_config (3)
|
||||||
|
|
|
@ -12,9 +12,7 @@ ctlseqs_reader_config - configure control sequence reader
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Function
|
Changes the properties of the given
|
||||||
.BR ctlseqs_reader_config ()
|
|
||||||
changes the properties of the given
|
|
||||||
.IR reader .
|
.IR reader .
|
||||||
.PP
|
.PP
|
||||||
The
|
The
|
||||||
|
@ -53,7 +51,7 @@ is the file descriptor to read from.
|
||||||
Field
|
Field
|
||||||
.I flags
|
.I flags
|
||||||
is the bit mask of multiple boolean options.
|
is the bit mask of multiple boolean options.
|
||||||
.SS Buffer Values
|
.SS Buffer values
|
||||||
A
|
A
|
||||||
.I buffer
|
.I buffer
|
||||||
is an array of
|
is an array of
|
||||||
|
@ -110,6 +108,11 @@ or
|
||||||
.BR CTLSEQS_NOMEM ,
|
.BR CTLSEQS_NOMEM ,
|
||||||
the length of the entire string followed by the string itself will be stored into the buffer.
|
the length of the entire string followed by the string itself will be stored into the buffer.
|
||||||
.SS Flags
|
.SS Flags
|
||||||
|
Flags are boolean switches which can be combined as a bitmask for the
|
||||||
|
.I flags
|
||||||
|
option.
|
||||||
|
.PP
|
||||||
|
Currently supported flags:
|
||||||
.TP
|
.TP
|
||||||
.B CTLSEQS_READER_NO_POLL
|
.B CTLSEQS_READER_NO_POLL
|
||||||
In a
|
In a
|
||||||
|
|
Loading…
Reference in New Issue