diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..2df441c --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,46 @@ + + +# 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 +``` diff --git a/INSTALL.org b/INSTALL.org deleted file mode 100644 index 20663b6..0000000 --- a/INSTALL.org +++ /dev/null @@ -1,53 +0,0 @@ -# -# Copyright (C) 2020 CismonX -# -# 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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..c982141 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ + + +# 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. diff --git a/README.org b/README.org deleted file mode 100644 index 001c0b8..0000000 --- a/README.org +++ /dev/null @@ -1,35 +0,0 @@ -# -# Copyright (C) 2020 CismonX -# -# 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. diff --git a/man/ctlseqs.7 b/man/ctlseqs.7 index c4bc9e8..94eb90b 100644 --- a/man/ctlseqs.7 +++ b/man/ctlseqs.7 @@ -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 diff --git a/man/ctlseqs_matcher_config.3 b/man/ctlseqs_matcher_config.3 index 73b046b..c4f59ab 100644 --- a/man/ctlseqs_matcher_config.3 +++ b/man/ctlseqs_matcher_config.3 @@ -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) . diff --git a/man/ctlseqs_purge.3 b/man/ctlseqs_purge.3 index f147a43..cd82296 100644 --- a/man/ctlseqs_purge.3 +++ b/man/ctlseqs_purge.3 @@ -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 diff --git a/man/ctlseqs_read.3 b/man/ctlseqs_read.3 index 39f789e..bf5a445 100644 --- a/man/ctlseqs_read.3 +++ b/man/ctlseqs_read.3 @@ -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) diff --git a/man/ctlseqs_reader_config.3 b/man/ctlseqs_reader_config.3 index 3c5261a..d47d1a4 100644 --- a/man/ctlseqs_reader_config.3 +++ b/man/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