Update documentation.
continuous-integration/drone/push Build is failing
Details
continuous-integration/drone/push Build is failing
Details
This commit is contained in:
parent
471825b0ac
commit
da11b51814
169
doc/ctlseqs.texi
169
doc/ctlseqs.texi
|
@ -43,13 +43,13 @@ license is included in the section entitled ``GNU Free Documentation License''.
|
||||||
|
|
||||||
This manual is for ctlseqs, a helper library for control sequences.
|
This manual is for ctlseqs, a helper library for control sequences.
|
||||||
|
|
||||||
Permission is granted to copy, distribute and/or modify this document under the
|
Permission is granted to copy, distribute and/or modify this document under
|
||||||
terms of the @pxref{GNU Free Documentation License}, Version 1.3 or any later
|
the terms of the @pxref{GNU Free Documentation License}, Version 1.3 or
|
||||||
version published by the Free Software Foundation; with no Invariant Sections,
|
any later version published by the Free Software Foundation; with no
|
||||||
with no Front-Cover Texts, and with no Back-Cover Texts.
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
|
||||||
|
|
||||||
ctlseqs is free software. You can redistribute it and/or modify it under the
|
ctlseqs is free software. You can redistribute it and/or modify it under
|
||||||
terms of the GNU General Public License as published by the Free Software
|
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
|
Foundation, either version 3 of the License, or (at your option) any later
|
||||||
version.
|
version.
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
@ -93,33 +93,14 @@ them can be used separatedly or combined, after including the header file
|
||||||
@node Contributing
|
@node Contributing
|
||||||
@section Contributing
|
@section Contributing
|
||||||
|
|
||||||
|
@set ctlseqs-repo-url https://savannah.nongnu.org/projects/ctlseqs
|
||||||
|
|
||||||
We welcome any form of contribution to ctlseqs (as well as this manual),
|
We welcome any form of contribution to ctlseqs (as well as this manual),
|
||||||
including bug reports, patches, etc.
|
including bug reports, patches, etc.
|
||||||
|
|
||||||
As ctlseqs is primarily @url{https://sv.gnu.org/p/ctlseqs, hosted on Savannah},
|
Source code of ctlseqs is @url{@value{ctlseqs-repo-url}, hosted on Savannah}.
|
||||||
it is recommended to contribute using the bug tracker and patch manager.
|
You can contribute to ctlseqs using the bug tracker and patch manager,
|
||||||
Sending an email to @email{bug-report@@cismon.net} is also a viable option.
|
or discuss with the community using the mailing lists.
|
||||||
|
|
||||||
@cindex Checklist for bug reports
|
|
||||||
An effective bug report should contain enough information to reproduce the bug,
|
|
||||||
which may contain:
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
@item The version number of ctlseqs involved.
|
|
||||||
@item A minimal code snippet to reproduce the bug.
|
|
||||||
@item Expected and actual behaviour of the program.
|
|
||||||
@item A core file for the crashed program.
|
|
||||||
@item Name of the operating system and hardware.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@cindex Checklist for patch submission
|
|
||||||
Before you submit a patch for ctlseqs, it is recommended to:
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
@item Follow the existing coding style.
|
|
||||||
@item Discuss with the community about new features or breaking changes.
|
|
||||||
@item Write test cases, documentation and changelogs for your code.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
|
|
||||||
@node Use Scenarios
|
@node Use Scenarios
|
||||||
|
@ -132,15 +113,15 @@ embedded in normal text. Such physical terminals are no longer used today,
|
||||||
however, popular ones like DEC VT100 are widely emulated by modern terminal
|
however, popular ones like DEC VT100 are widely emulated by modern terminal
|
||||||
emulators.
|
emulators.
|
||||||
|
|
||||||
The primary purpose of the ctlseqs library is to provide developers with a set
|
The primary purpose of the ctlseqs library is to provide developers with
|
||||||
of simple and easy-to-use API for handling control functions, when working on
|
simple and easy-to-use API for handling control functions, when working on
|
||||||
terminal emulators and text-based programs.
|
terminal emulators and text-based programs.
|
||||||
|
|
||||||
However, while there is no de facto standard, control functions used in
|
However, since there is no de facto standard, control functions used in
|
||||||
terminals are largely vendor-specific, and terminal emulators like to add their
|
terminals are largely vendor-specific, and terminal emulators like to add their
|
||||||
own private controls. That makes ctlseqs not suitable for writing text-based
|
own private controls. That makes ctlseqs not suitable for writing text-based
|
||||||
programs which intend to be portable. Instead of raw control codes, the
|
programs which intend to be portable. Instead of raw control codes, developers
|
||||||
developer should stick to ncurses or terminfo.
|
should stick to ncurses or terminfo.
|
||||||
|
|
||||||
@cindex List of common use cases of ctlseqs
|
@cindex List of common use cases of ctlseqs
|
||||||
There are still cases when dealing with raw escape sequences is inevitable, and
|
There are still cases when dealing with raw escape sequences is inevitable, and
|
||||||
|
@ -158,8 +139,8 @@ terminal emulators.
|
||||||
@node Helper Macros
|
@node Helper Macros
|
||||||
@chapter Helper Macros
|
@chapter Helper Macros
|
||||||
|
|
||||||
A helper macro in ctlseqs is a C preprocessor macro representing a control
|
ctlseqs provides C preprocessor macros representing control functions, which
|
||||||
function, which expands to a C string literal.
|
expand to C string literals.
|
||||||
|
|
||||||
@cindex List of control function types in ctlseqs helper macros
|
@cindex List of control function types in ctlseqs helper macros
|
||||||
The control function can be one of the following three types:
|
The control function can be one of the following three types:
|
||||||
|
@ -170,12 +151,12 @@ The control function can be one of the following three types:
|
||||||
@item Other control functions (such as device control functions).
|
@item Other control functions (such as device control functions).
|
||||||
@end itemize
|
@end itemize
|
||||||
|
|
||||||
Name of a helper macro is the function name with @code{CTLSEQS_} as prefix.
|
The name of a helper macro is the control function name with @code{CTLSEQS_}
|
||||||
For a control function other than elements from the C0 or C1 set, the
|
as prefix. For a control function other than elements from the C0 or C1 set,
|
||||||
corresponding helper macro is a function-like macro which may or may not take
|
the corresponding helper macro is a function-like macro which may or may not
|
||||||
arguments.
|
take arguments.
|
||||||
|
|
||||||
Control sequences listed in the helper macros are primarily exerpted from
|
Control sequences listed in the helper macros are primarily excerpted from
|
||||||
@url{https://invisible-island.net/xterm/ctlseqs/ctlseqs.html, XTerm's manual},
|
@url{https://invisible-island.net/xterm/ctlseqs/ctlseqs.html, XTerm's manual},
|
||||||
which may differ across implementations.
|
which may differ across implementations.
|
||||||
|
|
||||||
|
@ -232,8 +213,8 @@ ctlseqs_matcher_free(matcher);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
On rare occurences when ctlseqs fail to allocate enough memory, function
|
On rare occurences when ctlseqs fail to allocate enough memory, function
|
||||||
@code{ctlseqs_matcher_init} may return @code{NULL}. However, it is okay to pass
|
@code{ctlseqs_matcher_init} may return @code{NULL}.
|
||||||
null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
|
However, it is safe to pass null pointers to @code{ctlseqs_matcher_free}.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Matcher Configuration:: Configuring a control sequence matcher
|
* Matcher Configuration:: Configuring a control sequence matcher
|
||||||
|
@ -245,8 +226,8 @@ null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
|
||||||
@section Matcher Configuration
|
@section Matcher Configuration
|
||||||
|
|
||||||
Matcher configuration consists of two parts: the number of matching patterns,
|
Matcher configuration consists of two parts: the number of matching patterns,
|
||||||
and the patterns themselves. Invoke function @code{ctlseqs_matcher_config} to
|
and the pattern values.
|
||||||
configure a matcher.
|
Invoke function @code{ctlseqs_matcher_config} to configure a matcher.
|
||||||
|
|
||||||
@cindex Control sequence matcher configuration example
|
@cindex Control sequence matcher configuration example
|
||||||
@example
|
@example
|
||||||
|
@ -262,10 +243,10 @@ int result = ctlseqs_matcher_config(matcher, &options);
|
||||||
// ...
|
// ...
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Each invocation of @code{ctlseqs_matcher_config} on the same matcher overwrites
|
Each invocation of @code{ctlseqs_matcher_config} on the same matcher
|
||||||
the data generated from the last invocation. Upon success, the function returns
|
overwrites the data generated from the last invocation.
|
||||||
@code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns
|
Upon success, the function returns @code{CTLSEQS_OK}.
|
||||||
@code{CTLSEQS_NOMEM}.
|
If the function fails to allocate enough memory, returns @code{CTLSEQS_NOMEM}.
|
||||||
|
|
||||||
@quotation Caution
|
@quotation Caution
|
||||||
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
||||||
|
@ -296,19 +277,21 @@ The following types of control functions are recognizable by the matcher:
|
||||||
|
|
||||||
According to ECMA-48, CSI parameter bytes are of range @code{0x30} to
|
According to ECMA-48, CSI parameter bytes are of range @code{0x30} to
|
||||||
@code{0x3f}, intermediate bytes @code{0x20} to @code{0x2f}, and final byte
|
@code{0x3f}, intermediate bytes @code{0x20} to @code{0x2f}, and final byte
|
||||||
@code{0x40} to @code{0x7e}. Command string consists of printable characters and
|
@code{0x40} to @code{0x7e}.
|
||||||
characters of range @code{0x08} and @code{0x0e}. Character string can be any
|
Command string consists of printable characters and characters of range
|
||||||
bit combination which does not represent @code{SOS} or @code{ST}.
|
@code{0x08} and @code{0x0e}.
|
||||||
|
Character string can be any bit combination which does not represent
|
||||||
|
@code{SOS} or @code{ST}.
|
||||||
|
|
||||||
A supported control function, either verbatim or combined with placeholders,
|
A supported control function, either verbatim or combined with placeholders,
|
||||||
can be specified as a valid pattern. The terminating @code{NUL} character does
|
can be specified as a valid pattern.
|
||||||
not count into the pattern.
|
The terminating @code{NUL} character does not count into the pattern.
|
||||||
|
|
||||||
@cindex List of supported placeholders
|
@cindex List of supported placeholders
|
||||||
A placeholder indicates that when matching a string against the pattern, the
|
A placeholder indicates that when matching a string against the pattern,
|
||||||
value at the placeholder's location should conform to its rules. A placeholder
|
the value at the placeholder's location should conform to its rules.
|
||||||
can only take place in the @code{param}, @code{intmd}, @code{cmdstr} or
|
A placeholder can only take place in the @code{param}, @code{intmd},
|
||||||
@code{chrstr} fields, and can be one of the following values:
|
@code{cmdstr} or @code{chrstr} fields, and can be one of the following values:
|
||||||
|
|
||||||
@itemize @bullet
|
@itemize @bullet
|
||||||
@item @code{CTLSEQS_PH_NUM}: An unsigned integer.
|
@item @code{CTLSEQS_PH_NUM}: An unsigned integer.
|
||||||
|
@ -363,8 +346,9 @@ offset 0, and the pointer to the first character of the control funtion at the
|
||||||
@code{str} field at offset 1.
|
@code{str} field at offset 1.
|
||||||
|
|
||||||
If @code{ctlseqs_match} fails to find any control functions, returns
|
If @code{ctlseqs_match} fails to find any control functions, returns
|
||||||
@code{CTLSEQS_NESEQ}. For a partial control function, returns
|
@code{CTLSEQS_NOSEQ}.
|
||||||
@code{CTLSEQS_PARTIAL}. If the matcher is not configured with a pattern of the
|
For a partial control function, returns @code{CTLSEQS_PARTIAL}.
|
||||||
|
If the matcher is not configured with a matching pattern of the
|
||||||
control function, the function returns @code{CTLSEQS_NOMATCH}.
|
control function, the function returns @code{CTLSEQS_NOMATCH}.
|
||||||
|
|
||||||
If the control function matches a pattern configured in the matcher, returns
|
If the control function matches a pattern configured in the matcher, returns
|
||||||
|
@ -403,7 +387,7 @@ patterns is provided.
|
||||||
|
|
||||||
@quotation Caution
|
@quotation Caution
|
||||||
If the given string can match multiple patterns in the matcher, it is
|
If the given string can match multiple patterns in the matcher, it is
|
||||||
unspecified which of them will be the final match result.
|
unspecified which one of them will be the final match result.
|
||||||
@end quotation
|
@end quotation
|
||||||
|
|
||||||
|
|
||||||
|
@ -418,81 +402,106 @@ unspecified which of them will be the final match result.
|
||||||
@node Example Programs
|
@node Example Programs
|
||||||
@chapter Example Programs
|
@chapter Example Programs
|
||||||
|
|
||||||
|
There are a few example programs which may shed some light on using ctlseqs.
|
||||||
|
|
||||||
@node API Reference
|
@node API Reference
|
||||||
@appendix API Reference
|
@appendix API Reference
|
||||||
|
|
||||||
This appendix section contains a complete list of functions exposed by ctlseqs,
|
This section contains a complete list of functions exposed by ctlseqs, which is
|
||||||
which is meant for a TL;DR purpose. See the corresponding man(3) pages for
|
meant for a TL;DR purpose. See the corresponding man(3) pages for details.
|
||||||
concise details.
|
|
||||||
|
|
||||||
Initialize matcher:
|
Initialize matcher:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
struct ctlseqs_matcher *ctlseqs_matcher_init(void);
|
struct ctlseqs_matcher *
|
||||||
|
ctlseqs_matcher_init(void);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Configure matcher:
|
Configure matcher:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
int ctlseqs_matcher_config(
|
int
|
||||||
|
ctlseqs_matcher_config(
|
||||||
struct ctlseqs_matcher *matcher,
|
struct ctlseqs_matcher *matcher,
|
||||||
struct ctlseqs_matcher_options const *options);
|
struct ctlseqs_matcher_options const *options
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Match string:
|
Match string:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
ssize_t ctlseqs_match(
|
ssize_t
|
||||||
|
ctlseqs_match(
|
||||||
struct ctlseqs_reader const *matcher,
|
struct ctlseqs_reader const *matcher,
|
||||||
char const *str,
|
char const *str,
|
||||||
size_t str_len,
|
size_t str_len,
|
||||||
union ctlseqs_value *result);
|
union ctlseqs_value *result
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Destroy matcher:
|
Destroy matcher:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
void ctlseqs_matcher_free(struct ctlseqs_matcher *matcher);
|
void
|
||||||
|
ctlseqs_matcher_free(
|
||||||
|
struct ctlseqs_matcher *matcher
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Initialize reader:
|
Initialize reader:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
struct ctlseqs_reader *ctlseqs_reader_init(void);
|
struct ctlseqs_reader *
|
||||||
|
ctlseqs_reader_init(void);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Configure reader:
|
Configure reader:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
int ctlseqs_reader_config(
|
int
|
||||||
|
ctlseqs_reader_config(
|
||||||
struct ctlseqs_reader *reader,
|
struct ctlseqs_reader *reader,
|
||||||
struct ctlseqs_reader_options const *options);
|
struct ctlseqs_reader_options const *options
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Read and match:
|
Read and match:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
ssize_t ctlseqs_read(
|
ssize_t
|
||||||
|
ctlseqs_read(
|
||||||
struct ctlseqs_reader *reader,
|
struct ctlseqs_reader *reader,
|
||||||
struct ctlseqs_matcher const *matcher,
|
struct ctlseqs_matcher const *matcher,
|
||||||
int timeout);
|
int timeout
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Purge reader:
|
Purge reader:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
void ctlseqs_purge(
|
void
|
||||||
|
ctlseqs_purge(
|
||||||
struct ctlseqs_reader *reader,
|
struct ctlseqs_reader *reader,
|
||||||
size_t nbytes);
|
size_t nbytes
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Destroy reader:
|
Destroy reader:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
void ctlseqs_reader_free(struct ctlseqs_reader *reader);
|
void
|
||||||
|
ctlseqs_reader_free(
|
||||||
|
struct ctlseqs_reader *reader
|
||||||
|
);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
|
|
||||||
|
@node Indices
|
||||||
|
@appendix Indices
|
||||||
|
|
||||||
|
@printindex cp
|
||||||
|
|
||||||
|
|
||||||
@node GNU Free Documentation License
|
@node GNU Free Documentation License
|
||||||
@appendix GNU Free Documentation License
|
@appendix GNU Free Documentation License
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_match - match control sequence
|
ctlseqs_match - match control sequence
|
||||||
|
@ -7,8 +7,12 @@ ctlseqs_match - match control sequence
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "ssize_t ctlseqs_match(struct ctlseqs_reader const *" matcher ,
|
.B ssize_t ctlseqs_match(
|
||||||
.BI " char const *" str ", size_t " str_len ", union ctlseqs_value *" result );
|
.BI " struct ctlseqs_matcher const *" matcher ,
|
||||||
|
.BI " char const *" str ,
|
||||||
|
.BI " size_t " str_len ,
|
||||||
|
.BI " union ctlseqs_value *" result
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
@ -97,7 +101,7 @@ The string can be recognized as part of a control sequence, but is not yet termi
|
||||||
No valid control sequence is found in the given string.
|
No valid control sequence is found in the given string.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_MATCHER_CONFIG 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_MATCHER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_matcher_config - configure control sequence matcher
|
ctlseqs_matcher_config - configure control sequence matcher
|
||||||
|
@ -7,8 +7,10 @@ ctlseqs_matcher_config - configure control sequence matcher
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "int ctlseqs_matcher_config(struct ctlseqs_matcher *" matcher ,
|
.B int ctlseqs_matcher_config(
|
||||||
.BI " struct ctlseqs_matcher_options const *" options );
|
.BI " struct ctlseqs_matcher *" matcher ,
|
||||||
|
.BI " struct ctlseqs_matcher_options const *" options
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_matcher_free - free control sequence matcher
|
ctlseqs_matcher_free - free control sequence matcher
|
||||||
|
@ -7,15 +7,17 @@ ctlseqs_matcher_free - free control sequence matcher
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "void ctlseqs_matcher_free(struct ctlseqs_matcher *" matcher ");"
|
.B void ctlseqs_matcher_free(
|
||||||
|
.BI " struct ctlseqs_matcher *" matcher
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Destroys a
|
Destroys a
|
||||||
.I matcher
|
.I matcher
|
||||||
instance created by
|
instance created by
|
||||||
.BR ctlseqs_matcher_init ()
|
.B ctlseqs_matcher_init
|
||||||
and releases its holding memory.
|
and releases its memory.
|
||||||
.PP
|
.PP
|
||||||
If
|
If
|
||||||
.I matcher
|
.I matcher
|
||||||
|
@ -25,7 +27,7 @@ is NULL, this function has no effect.
|
||||||
This function has no return values.
|
This function has no return values.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_MATCHER_INIT 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_MATCHER_INIT 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_matcher_init - initialize control sequence matcher
|
ctlseqs_matcher_init - initialize control sequence matcher
|
||||||
|
@ -12,10 +12,10 @@ ctlseqs_matcher_init - initialize control sequence matcher
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Creates a control sequence matcher, which can be configured with
|
Creates a control sequence matcher, which can be configured with
|
||||||
.BR ctlseqs_matcher_config ().
|
.BR ctlseqs_matcher_config .
|
||||||
.PP
|
.PP
|
||||||
Instance of a control sequence matcher should be freed with
|
Instance of a matcher should be freed with
|
||||||
.BR ctlseqs_matcher_free ().
|
.BR ctlseqs_matcher_free .
|
||||||
.
|
.
|
||||||
.SH RETURN VALUE
|
.SH RETURN VALUE
|
||||||
Returns a pointer to opaque type
|
Returns a pointer to opaque type
|
||||||
|
@ -25,7 +25,7 @@ holding the matcher instance.
|
||||||
If the function fails to allocate sufficient memory, returns NULL.
|
If the function fails to allocate sufficient memory, returns NULL.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_PURGE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_PURGE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_purge - purge read buffer
|
ctlseqs_purge - purge read buffer
|
||||||
|
@ -7,7 +7,10 @@ ctlseqs_purge - purge read buffer
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "void ctlseqs_purge(struct ctlseqs_reader *" reader ", size_t " nbytes );
|
.B void ctlseqs_purge(
|
||||||
|
.BI " struct ctlseqs_reader *" reader ,
|
||||||
|
.BI " size_t " nbytes
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
@ -26,7 +29,7 @@ This function has no return values.
|
||||||
.
|
.
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
The 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 COPYRIGHT
|
.SH COPYRIGHT
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_read - read control sequence
|
ctlseqs_read - read control sequence
|
||||||
|
@ -7,8 +7,11 @@ ctlseqs_read - read control sequence
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "ssize_t ctlseqs_read(struct ctlseqs_reader *" reader ,
|
.B ssize_t ctlseqs_read(
|
||||||
.BI " struct ctlseqs_matcher const *" matcher ", int " timeout );
|
.BI " struct ctlseqs_reader *" reader ,
|
||||||
|
.BI " struct ctlseqs_matcher const *" matcher ,
|
||||||
|
.BI " int " timeout
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
@ -17,7 +20,7 @@ Attempts to read a control sequence with given
|
||||||
and match it against the patterns in
|
and match it against the patterns in
|
||||||
.IR matcher ,
|
.IR matcher ,
|
||||||
similar to
|
similar to
|
||||||
.BR ctlseqs_match() .
|
.BR ctlseqs_match .
|
||||||
.PP
|
.PP
|
||||||
When match fails, the number of characters read will be stored into the
|
When match fails, the number of characters read will be stored into the
|
||||||
.I result
|
.I result
|
||||||
|
@ -40,7 +43,7 @@ is enabled, this argument has no effect.
|
||||||
For a successful match, the extracted values are stored in
|
For a successful match, the extracted values are stored in
|
||||||
.I result
|
.I result
|
||||||
like
|
like
|
||||||
.BR ctlseqs_match() ,
|
.BR ctlseqs_match ,
|
||||||
but starting at offset 0 unless
|
but starting at offset 0 unless
|
||||||
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
|
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
|
||||||
is enabled.
|
is enabled.
|
||||||
|
@ -83,7 +86,7 @@ An unexpected error occurs during a system call within the function.
|
||||||
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
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_reader_config - configure control sequence reader
|
ctlseqs_reader_config - configure control sequence reader
|
||||||
|
@ -7,8 +7,10 @@ ctlseqs_reader_config - configure control sequence reader
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "int ctlseqs_reader_config(struct ctlseqs_reader *" reader ,
|
.B int ctlseqs_reader_config(
|
||||||
.BI " struct ctlseqs_reader_options const *" options );
|
.BI " struct ctlseqs_reader *" reader ,
|
||||||
|
.BI " struct ctlseqs_reader_options const *" options
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
@ -37,7 +39,7 @@ struct ctlseqs_reader_options {
|
||||||
Field
|
Field
|
||||||
.I result
|
.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
|
||||||
.BR ctlseqs_read ()
|
.B ctlseqs_read
|
||||||
will be stored.
|
will be stored.
|
||||||
.PP
|
.PP
|
||||||
Field
|
Field
|
||||||
|
@ -55,18 +57,18 @@ is the bit mask of multiple boolean options.
|
||||||
.TP
|
.TP
|
||||||
.B CTLSEQS_READER_NO_POLL
|
.B CTLSEQS_READER_NO_POLL
|
||||||
In a
|
In a
|
||||||
.BR ctlseqs_read ()
|
.B ctlseqs_read
|
||||||
call, do not
|
call, do not
|
||||||
.BR poll ()
|
.B poll
|
||||||
before
|
before
|
||||||
.BR read ().
|
.BR read .
|
||||||
You may want this option enabled if
|
You may want this option enabled if
|
||||||
.I fd
|
.I fd
|
||||||
is maintained in an event loop.
|
is polled elsewhere (e.g. in an event loop).
|
||||||
.TP
|
.TP
|
||||||
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
|
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
|
||||||
When a sequence is successfully matched against a pattern during
|
When a sequence is successfully matched against a pattern during
|
||||||
.BR ctlseqs_read (),
|
.BR ctlseqs_read ,
|
||||||
save the original sequence to
|
save the original sequence to
|
||||||
.I result
|
.I result
|
||||||
alongside the extracted values.
|
alongside the extracted values.
|
||||||
|
@ -85,7 +87,7 @@ Attempts to change
|
||||||
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
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_reader_free - free control sequence reader
|
ctlseqs_reader_free - free control sequence reader
|
||||||
|
@ -7,14 +7,16 @@ ctlseqs_reader_free - free control sequence reader
|
||||||
.nf
|
.nf
|
||||||
.B #include <ctlseqs.h>
|
.B #include <ctlseqs.h>
|
||||||
.PP
|
.PP
|
||||||
.BI "void ctlseqs_reader_free(struct ctlseqs_reader *" reader ");"
|
.B void ctlseqs_reader_free(
|
||||||
|
.BI " struct ctlseqs_reader *" reader
|
||||||
|
.B );
|
||||||
.fi
|
.fi
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Destroys a
|
Destroys a
|
||||||
.I reader
|
.I reader
|
||||||
instance created by
|
instance created by
|
||||||
.BR ctlseqs_reader_init ()
|
.B ctlseqs_reader_init
|
||||||
and releases its holding memory.
|
and releases its holding memory.
|
||||||
.PP
|
.PP
|
||||||
If
|
If
|
||||||
|
@ -25,7 +27,7 @@ is NULL, this function has no effect.
|
||||||
This function has no return values.
|
This function has no return values.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH CTLSEQS_READER_INIT 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
.TH CTLSEQS_READER_INIT 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||||
.
|
.
|
||||||
.SH NAME
|
.SH NAME
|
||||||
ctlseqs_reader_init - initialize control sequence reader
|
ctlseqs_reader_init - initialize control sequence reader
|
||||||
|
@ -12,10 +12,10 @@ ctlseqs_reader_init - initialize control sequence reader
|
||||||
.
|
.
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Creates a control sequence reader, which can be configured with
|
Creates a control sequence reader, which can be configured with
|
||||||
.BR ctlseqs_reader_config ().
|
.BR ctlseqs_reader_config .
|
||||||
.PP
|
.PP
|
||||||
Instance of a control sequence reader should be freed with
|
Instance of a reader should be freed with
|
||||||
.BR ctlseqs_reader_free ().
|
.BR ctlseqs_reader_free .
|
||||||
.
|
.
|
||||||
.SH RETURN VALUE
|
.SH RETURN VALUE
|
||||||
Returns a pointer to opaque type
|
Returns a pointer to opaque type
|
||||||
|
@ -25,7 +25,7 @@ holding the reader instance.
|
||||||
If the function fails to allocate sufficient memory, returns NULL.
|
If the function fails to allocate sufficient memory, returns NULL.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
||||||
.PP
|
.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.
|
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.
|
This file is offered as-is, without any warranty.
|
||||||
|
|
Loading…
Reference in New Issue