Update README and documentation.
This commit is contained in:
parent
823544151e
commit
67d48ebc09
GPG Key ID:
3094873E29A482FB
|
|
@ -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
|
||||
|
||||
[](https://travis-ci.com/CismonX/ctlseqs)
|
||||
[](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
|
||||
.
|
||||
.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
|
||||
Terminals and hosts exchange control information regarding colors, font styles, cursor position, etc., using escape sequences embedded in normal text.
|
||||
.PP
|
||||
|
|
@ -39,7 +39,7 @@ For helper macro details, see the source code of the
|
|||
.I ctlseqs.h
|
||||
header.
|
||||
.
|
||||
.SH BUGS
|
||||
.SH NOTES
|
||||
C1 (8-bit) control characters are not supported.
|
||||
.
|
||||
.SH SEE ALSO
|
||||
|
|
|
|||
|
|
@ -53,6 +53,26 @@ Success.
|
|||
.B CTLSEQS_NOMEM
|
||||
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
|
||||
.BR ctlseqs (7)
|
||||
.
|
||||
|
|
|
|||
|
|
@ -25,8 +25,8 @@ is zero, this function has no effect.
|
|||
This function has no return values.
|
||||
.
|
||||
.SH NOTES
|
||||
This function is useful when dealing with partial sequences returned by
|
||||
.BR ctlseqs_read ()
|
||||
The function is useful when dealing with partial sequences returned by
|
||||
.BR ctlseqs_read (),
|
||||
whose future completion is not desired.
|
||||
.
|
||||
.SH SEE ALSO
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ is enabled, this argument has no effect.
|
|||
.SH RETURN VALUE
|
||||
If a control sequence is successfully read, and matches at least one pattern in
|
||||
.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
|
||||
Otherwise, returns a negative value:
|
||||
.TP
|
||||
|
|
@ -75,25 +75,6 @@ An unexpected error occurs during a system call within the function.
|
|||
.B CTLSEQS_INTR
|
||||
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
|
||||
.BR ctlseqs_matcher_config (3),
|
||||
.BR ctlseqs_reader_config (3)
|
||||
|
|
|
|||
|
|
@ -12,9 +12,7 @@ ctlseqs_reader_config - configure control sequence reader
|
|||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
Function
|
||||
.BR ctlseqs_reader_config ()
|
||||
changes the properties of the given
|
||||
Changes the properties of the given
|
||||
.IR reader .
|
||||
.PP
|
||||
The
|
||||
|
|
@ -53,7 +51,7 @@ is the file descriptor to read from.
|
|||
Field
|
||||
.I flags
|
||||
is the bit mask of multiple boolean options.
|
||||
.SS Buffer Values
|
||||
.SS Buffer values
|
||||
A
|
||||
.I buffer
|
||||
is an array of
|
||||
|
|
@ -110,6 +108,11 @@ or
|
|||
.BR CTLSEQS_NOMEM ,
|
||||
the length of the entire string followed by the string itself will be stored into the buffer.
|
||||
.SS Flags
|
||||
Flags are boolean switches which can be combined as a bitmask for the
|
||||
.I flags
|
||||
option.
|
||||
.PP
|
||||
Currently supported flags:
|
||||
.TP
|
||||
.B CTLSEQS_READER_NO_POLL
|
||||
In a
|
||||
|
|
|
|||
Loading…
Reference in New Issue