Update documentation.
continuous-integration/drone/push Build is passing Details

This commit is contained in:
CismonX 2021-11-12 17:42:39 +08:00
parent 8f7423581d
commit 4e72aeb8d7
Signed by: cismonx
GPG Key ID: 3094873E29A482FB
1 changed files with 27 additions and 24 deletions

View File

@ -65,6 +65,7 @@ version.
Appendices
* API Reference:: C API reference for ctlseqs.
* General Index:: Index of general concepts of ctlseqs.
* GNU Free Documentation License:: Copying conditions of this manual.
@end menu
@ -173,7 +174,7 @@ printf(CTLSEQS_XTVERSION());
printf(CTLSEQS_CUP("%d", "%d"), 3, 4);
@end example
Rememeber that the standard output stream is line buffered within a terminal.
Keep in mind that the standard output stream is line buffered in a terminal.
Either @code{fflush(stdout)} after printing, or disable output buffering with
@code{setvbuf(stdout, NULL, _IONBF, 0)}.
@ -191,7 +192,9 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
// ...
@} else if (2 == sscanf(str, CTLSEQS_CUP("%d", "%d"), &row, &col)) @{
// ...
@} else /* ... */
@} else @{
// ...
@}
@end example
However, as the number of possible matches grows, this naive implementation
@ -369,9 +372,9 @@ the first character of the string stored in field @code{str}.
The following code is an example of invoking @code{ctlseqs_match}:
@example
union ctlseqs_value buffer[4];
struct ctlseqs_matcher *matcher /* = ... */;
// ...
union ctlseqs_value buffer[4];
char const *str = "foo" CTLSEQS_CUP("2", "4");
size_t str_len = sizeof("foo" CTLSEQS_CUP("2", "4")) - 1;
ssize_t result = ctlseqs_match(matcher, str, str_len, buffer);
@ -402,7 +405,16 @@ unspecified which one of them will be the final match result.
@node Example Programs
@chapter Example Programs
There are a few example programs which may shed some light on using ctlseqs.
In the source code repository of ctlseqs, there are a few programs that
demonstrates the basic usage of ctlseqs.
See ``example/sixdraw.c'' for a simple TUI program in which you can draw lines
on the terminal window using a mouse.
See ``tests/tcsgrep.c'' for a program which parses control functions into
human-readable text. It was originally written as a tool to run tests for
ctlseqs, but can also be considered as a crude alternative of
@url{https://www.gnu.org/software/teseq/, GNU Teseq}.
@node API Reference
@appendix API Reference
@ -413,15 +425,13 @@ meant for a TL;DR purpose. See the corresponding man(3) pages for details.
Initialize matcher:
@example
struct ctlseqs_matcher *
ctlseqs_matcher_init(void);
struct ctlseqs_matcher *ctlseqs_matcher_init(void);
@end example
Configure matcher:
@example
int
ctlseqs_matcher_config(
int ctlseqs_matcher_config(
struct ctlseqs_matcher *matcher,
struct ctlseqs_matcher_options const *options
);
@ -430,8 +440,7 @@ ctlseqs_matcher_config(
Match string:
@example
ssize_t
ctlseqs_match(
ssize_t ctlseqs_match(
struct ctlseqs_reader const *matcher,
char const *str,
size_t str_len,
@ -442,8 +451,7 @@ ctlseqs_match(
Destroy matcher:
@example
void
ctlseqs_matcher_free(
void ctlseqs_matcher_free(
struct ctlseqs_matcher *matcher
);
@end example
@ -451,15 +459,13 @@ ctlseqs_matcher_free(
Initialize reader:
@example
struct ctlseqs_reader *
ctlseqs_reader_init(void);
struct ctlseqs_reader *ctlseqs_reader_init(void);
@end example
Configure reader:
@example
int
ctlseqs_reader_config(
int ctlseqs_reader_config(
struct ctlseqs_reader *reader,
struct ctlseqs_reader_options const *options
);
@ -468,8 +474,7 @@ ctlseqs_reader_config(
Read and match:
@example
ssize_t
ctlseqs_read(
ssize_t ctlseqs_read(
struct ctlseqs_reader *reader,
struct ctlseqs_matcher const *matcher,
int timeout
@ -479,8 +484,7 @@ ctlseqs_read(
Purge reader:
@example
void
ctlseqs_purge(
void ctlseqs_purge(
struct ctlseqs_reader *reader,
size_t nbytes
);
@ -489,15 +493,14 @@ ctlseqs_purge(
Destroy reader:
@example
void
ctlseqs_reader_free(
void ctlseqs_reader_free(
struct ctlseqs_reader *reader
);
@end example
@node Indices
@appendix Indices
@node General Index
@appendix General Index
@printindex cp