diff --git a/README.md b/README.md index b7e5fbb..f49f11a 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,7 @@ ctlseqs ======= The ctlseqs library provides C API for handling ECMA-35/ECMA-48 compatible - control functions, which is commonly used for communication between terminal - emulators and text-based programs. + control functions. ctlseqs is free software, licensed under the terms of the GNU General Public License, either version 3, or any later version of the license. See COPYING @@ -19,8 +18,10 @@ ctlseqs See INSTALL.md for instructions on how to build and install ctlseqs. - Visit the [project homepage] for documentation, mailing lists, releases, - and everything else about ctlseqs. + See `info ctlseqs` for documentation. + + Visit the [project homepage] for online documentation, mailing lists, + releases, and everything else about ctlseqs. diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index 0fb61b6..a5c90c9 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -419,16 +419,18 @@ ctlseqs, but can also be considered as a crude alternative of @node API Reference @appendix API Reference -This section contains a complete list of functions exposed by ctlseqs, which is -meant for a TL;DR purpose. See the corresponding man(3) pages for details. +@set url-man-pages https://nongnu.org/ctlseqs/man-pages/man3 -Initialize matcher: +This section contains a complete list of functions exposed by ctlseqs. See the +corresponding man pages for details. + +@url{@value{url-man-pages}/ctlseqs_matcher_init.3.html, Initialize matcher}: @example struct ctlseqs_matcher *ctlseqs_matcher_init(void); @end example -Configure matcher: +@url{@value{url-man-pages}/ctlseqs_matcher_config.3.html, Configure matcher}: @example int ctlseqs_matcher_config( @@ -437,7 +439,7 @@ int ctlseqs_matcher_config( ); @end example -Match string: +@url{@value{url-man-pages}/ctlseqs_match.3.html, Match string}: @example ssize_t ctlseqs_match( @@ -448,7 +450,7 @@ ssize_t ctlseqs_match( ); @end example -Destroy matcher: +@url{@value{url-man-pages}/ctlseqs_matcher_free.3.html, Destroy matcher}: @example void ctlseqs_matcher_free( @@ -456,13 +458,13 @@ void ctlseqs_matcher_free( ); @end example -Initialize reader: +@url{@value{url-man-pages}/ctlseqs_reader_init.3.html, Initialize reader}: @example struct ctlseqs_reader *ctlseqs_reader_init(void); @end example -Configure reader: +@url{@value{url-man-pages}/ctlseqs_reader_config.3.html, Configure reader}: @example int ctlseqs_reader_config( @@ -471,7 +473,7 @@ int ctlseqs_reader_config( ); @end example -Read and match: +@url{@value{url-man-pages}/ctlseqs_read.3.html, Read and match}: @example ssize_t ctlseqs_read( @@ -481,7 +483,7 @@ ssize_t ctlseqs_read( ); @end example -Purge reader: +@url{@value{url-man-pages}/ctlseqs_purge.3.html, Purge reader}: @example void ctlseqs_purge( @@ -490,7 +492,7 @@ void ctlseqs_purge( ); @end example -Destroy reader: +@url{@value{url-man-pages}/ctlseqs_reader_free.3.html, Destroy reader}: @example void ctlseqs_reader_free( diff --git a/include/ctlseqs.h b/include/ctlseqs.h index 9762664..cedfa3f 100644 --- a/include/ctlseqs.h +++ b/include/ctlseqs.h @@ -327,8 +327,8 @@ // Restore DEC Private Mode Values #define CTLSEQS_XTRESTORE(is) CTLSEQS_CSI "?" is "r" // Change Attributes in Rectangular Area -#define CTLSEQS_DECCARA(t, l, b, r, i) \ - CTLSEQS_CSI t ";" l ";" b ";" r ";" i "$r" +#define CTLSEQS_DECCARA(t, l, b, r, is) \ + CTLSEQS_CSI t ";" l ";" b ";" r ";" is "$r" // Save cursor #define CTLSEQS_SCOSC() CTLSEQS_CSI "s" // Set left and right margins @@ -342,8 +342,8 @@ // Set warning-bell volume #define CTLSEQS_DECSWBV(i) CTLSEQS_CSI i " t" // Reverse Attributes in Rectangular Area -#define CTLSEQS_DECRARA(t, l, b, r, i) \ - CTLSEQS_CSI t ";" l ";" b ";" r ";" i "$t" +#define CTLSEQS_DECRARA(t, l, b, r, is) \ + CTLSEQS_CSI t ";" l ";" b ";" r ";" is "$t" // Restore cursor #define CTLSEQS_SCORC() CTLSEQS_CSI "u" // Set margin-bell volume diff --git a/man/ctlseqs_match.3 b/man/ctlseqs_match.3 index 13d1bef..9dba0e4 100644 --- a/man/ctlseqs_match.3 +++ b/man/ctlseqs_match.3 @@ -35,7 +35,8 @@ Argument is the buffer where the function stores match results. If .I str -contains a control sequence (or part of a control sequence), the length of the sequence is stored in +contains a control sequence (or part of a control sequence), the length of the +sequence is stored in .I buffer at offset 0, and the pointer to the starting ESC character at offset 1. Otherwise, @@ -44,11 +45,13 @@ value at offset 0 and 1 is unspecified. .SS Match results If the control sequence matches a pattern in .IR matcher , -a group of values is extracted from the sequence for each placeholder, and stored into +a group of values is extracted from the sequence for each placeholder, and +stored into .I result sequentially, starting at offset 2. .PP -An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in +An extracted value can be either a string (not guaranteed to be +NUL-terminated), or an unsigned integer, as in .BR "union ctlseqs_value" : .PP .nf @@ -63,7 +66,8 @@ union ctlseqs_value { .in .fi .PP -A group can contain one or multiple values, depending on different placeholders: +A group can contain one or multiple values, depending on different +placeholders: .TP .BR CTLSEQS_PH_NUM ", " CTLSEQS_PH_HEXNUM The integer is stored in field @@ -75,7 +79,8 @@ The number of integers is stored in field followed by that many integers stored in field .IR num . .TP -.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR +.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " \ + CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR The length of the string is stored in field .IR len , followed by a pointer to the first character of the string stored in field @@ -95,7 +100,8 @@ A valid control sequence is found, but fails to match any pattern in .IR matcher . .TP .B CTLSEQS_PARTIAL -The string can be recognized as part of a control sequence, but is not yet terminated. +The string can be recognized as part of a control sequence, but is not yet +terminated. .TP .B CTLSEQS_NOSEQ No valid control sequence is found in the given string. @@ -103,8 +109,9 @@ No valid control sequence is found in the given string. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_matcher_config (3) diff --git a/man/ctlseqs_matcher_config.3 b/man/ctlseqs_matcher_config.3 index 2a29671..8854902 100644 --- a/man/ctlseqs_matcher_config.3 +++ b/man/ctlseqs_matcher_config.3 @@ -36,7 +36,8 @@ struct ctlseqs_matcher_options { .PP Field .I patterns -is an array of pointers to NUL-terminated strings, each of which represents a pattern of control sequences. +is an array of pointers to NUL-terminated strings, each of which represents a +pattern of control sequences. .PP Field .I npatterns @@ -47,7 +48,9 @@ Multiple calls on the same .I matcher will discard all data from previous calls. .SS Placeholders -A pattern may contain zero to multiple placeholders, where a placeholder indicates that when matching a string against the pattern, the value at the placeholder's location should conform to its rules. +A pattern may contain zero to multiple placeholders, where a placeholder +indicates that when matching a string against the pattern, the value at the +placeholder's location should conform to its rules. .PP Currently supported placeholders: .TP @@ -55,7 +58,8 @@ Currently supported placeholders: An unsigned integer. .TP .B CTLSEQS_PH_NUMS -Multiple unsigned integers separated with the semicolon ASCII character (value 0x3b). +Multiple unsigned integers separated with the semicolon ASCII character +(value 0x3b). .TP .B CTLSEQS_PH_STR A string of printable characters. @@ -86,16 +90,18 @@ 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. +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. +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. +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. @@ -106,8 +112,9 @@ Character string can be any bit combination which does not represent SOS or ST. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_match (3), diff --git a/man/ctlseqs_matcher_free.3 b/man/ctlseqs_matcher_free.3 index 174de8f..fd62efa 100644 --- a/man/ctlseqs_matcher_free.3 +++ b/man/ctlseqs_matcher_free.3 @@ -29,8 +29,9 @@ This function has no return values. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_matcher_init (3) diff --git a/man/ctlseqs_matcher_init.3 b/man/ctlseqs_matcher_init.3 index 72bc020..8ac3333 100644 --- a/man/ctlseqs_matcher_init.3 +++ b/man/ctlseqs_matcher_init.3 @@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_matcher_config (3), diff --git a/man/ctlseqs_purge.3 b/man/ctlseqs_purge.3 index 0c2b785..72d5432 100644 --- a/man/ctlseqs_purge.3 +++ b/man/ctlseqs_purge.3 @@ -35,8 +35,9 @@ whose future completion is not desired. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_read (3) diff --git a/man/ctlseqs_read.3 b/man/ctlseqs_read.3 index 5d1752f..84e0ee0 100644 --- a/man/ctlseqs_read.3 +++ b/man/ctlseqs_read.3 @@ -33,7 +33,8 @@ is enabled, also save those values when the match is successful. .PP Argument .I timeout -is the maximum duration of time (in milliseconds) to wait until any data can be read. +is the maximum duration of time (in milliseconds) to wait until any data can be +read. If .I timeout is -1, the function blocks indefinitely. If option @@ -60,11 +61,13 @@ A control sequence is successfully read, but fails to match any pattern in .IR matcher . .TP .B CTLSEQS_PARTIAL -Data is read successfully and can be recognized as part of a control sequence, but is not yet terminated. -Partial sequence is not consumed from the read buffer. +Data is read successfully and can be recognized as part of a control sequence, +but is not yet terminated. Partial sequence is not consumed from the read +buffer. .TP .B CTLSEQS_NOSEQ -Data is read successfully, but cannot be recognized as a valid control sequence. +Data is read successfully, but cannot be recognized as a valid control +sequence. .TP .B CTLSEQS_TIMEOUT The specified @@ -83,13 +86,15 @@ End-of-file is encountered, and no data is read. An unexpected error occurs during a system call within the function. .TP .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 COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_match (3), diff --git a/man/ctlseqs_reader_config.3 b/man/ctlseqs_reader_config.3 index 3d633bf..1c87268 100644 --- a/man/ctlseqs_reader_config.3 +++ b/man/ctlseqs_reader_config.3 @@ -38,13 +38,15 @@ struct ctlseqs_reader_options { .PP Field .I result -is the pointer to the buffer where the values extracted from the matching sequence of +is the pointer to the buffer where the values extracted from the matching +sequence of .B ctlseqs_read will be stored. .PP Field .I maxlen -specifies the maximum possible length (in bytes) of control sequence to be read. +specifies the maximum possible length (in bytes) of control sequence to be +read. .PP Field .I fd @@ -84,13 +86,15 @@ Fails to allocate sufficient memory. .B CTLSEQS_ERROR Attempts to change .I maxlen -value, but data in the internal read buffer will be lost due to truncation, if done so. +value, but data in the internal read buffer will be lost due to truncation, if +done so. . .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_match (3), diff --git a/man/ctlseqs_reader_free.3 b/man/ctlseqs_reader_free.3 index 95d83e8..df20193 100644 --- a/man/ctlseqs_reader_free.3 +++ b/man/ctlseqs_reader_free.3 @@ -29,8 +29,9 @@ This function has no return values. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_reader_init (3) diff --git a/man/ctlseqs_reader_init.3 b/man/ctlseqs_reader_init.3 index bd90b6d..df7e672 100644 --- a/man/ctlseqs_reader_init.3 +++ b/man/ctlseqs_reader_init.3 @@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL. .SH COPYRIGHT Copyright (c) 2020,2021 CismonX .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. +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. . .SH SEE ALSO .BR ctlseqs_reader_config (3),