update documentation
continuous-integration/drone/push Build is passing
Details
continuous-integration/drone/push Build is passing
Details
This commit is contained in:
parent
76d0f779d8
commit
3447a058a7
GPG Key ID:
3094873E29A482FB
|
|
@ -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.
|
||||
|
||||
|
||||
<!-- Reference Links -->
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <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.
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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 <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.
|
||||
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),
|
||||
|
|
|
|||
|
|
@ -29,8 +29,9 @@ This function has no return values.
|
|||
.SH COPYRIGHT
|
||||
Copyright (c) 2020,2021 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.
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL.
|
|||
.SH COPYRIGHT
|
||||
Copyright (c) 2020,2021 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.
|
||||
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),
|
||||
|
|
|
|||
|
|
@ -35,8 +35,9 @@ whose future completion is not desired.
|
|||
.SH COPYRIGHT
|
||||
Copyright (c) 2020,2021 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.
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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 <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.
|
||||
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),
|
||||
|
|
|
|||
|
|
@ -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 <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.
|
||||
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),
|
||||
|
|
|
|||
|
|
@ -29,8 +29,9 @@ This function has no return values.
|
|||
.SH COPYRIGHT
|
||||
Copyright (c) 2020,2021 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.
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL.
|
|||
.SH COPYRIGHT
|
||||
Copyright (c) 2020,2021 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.
|
||||
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),
|
||||
|
|
|
|||
Loading…
Reference in New Issue