update documentation
continuous-integration/drone/push Build is passing Details
continuous-integration/drone Build is passing Details

This commit is contained in:
CismonX 2022-05-02 21:04:06 +08:00
parent 3447a058a7
commit 592bb717d6
Signed by: cismonx
GPG Key ID: 3094873E29A482FB
2 changed files with 71 additions and 13 deletions

View File

@ -3,14 +3,14 @@
@c %**start of header
@setfilename ctlseqs.info
@include version.texi
@settitle ctlseqs @value{VERSION} Manual
@settitle ctlseqs @value{VERSION}
@c %**end of header
@copying
This manual is for ctlseqs, a helper library for control sequences.
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
Copyright @copyright{} 2021,2022 CismonX <admin@@cismon.net>
@quotation
Permission is granted to copy, distribute and/or modify this document under
@ -44,7 +44,7 @@ license is included in the section entitled ``GNU Free Documentation License''.
This manual is for ctlseqs, a helper library for control sequences.
Permission is granted to copy, distribute and/or modify this document under
the terms of the @pxref{GNU Free Documentation License}, Version 1.3 or
the terms of the @ref{GNU Free Documentation License}, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
@ -174,8 +174,9 @@ printf(CTLSEQS_XTVERSION());
printf(CTLSEQS_CUP("%d", "%d"), 3, 4);
@end example
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
Keep in mind that the standard output stream is by default line buffered in a
terminal. In order to make the control functions take effect immediately,
either @code{fflush(stdout)} after printing, or disable output buffering with
@code{setvbuf(stdout, NULL, _IONBF, 0)}.
@ -197,15 +198,13 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
@}
@end example
However, as the number of possible matches grows, this naive implementation
becomes less efficient and harder to maintain.
Such problems can be easily solved by using the control sequence matcher
provided by ctlseqs.
However, as the number of patterns grows, this naive implementation becomes
less efficient and harder to maintain. This problem can be easily solved by
using the control sequence matcher provided by ctlseqs.
The @code{struct ctlseqs_matcher *} is a pointer to an opaque type which
represents an instance of control sequence matcher. Before using, the matcher
should be initialized with @code{ctlseqs_matcher_init}. After used, it should
should be initialized with @code{ctlseqs_matcher_init}. After using, it should
be deallocated with @code{ctlseqs_matcher_free}.
@cindex Control sequence matcher initialization example
@ -397,6 +396,65 @@ unspecified which one of them will be the final match result.
@node Control Sequence Reading
@chapter Control Sequence Reading
In practice, control sequences are often read from stream (e.g. STDIN). The
ctlseqs library provides a control sequence reader utility, which reads data
from a file descriptor, buffers it, and matches the data against the patterns
specified in the given matcher.
Like the matcher, @code{struct ctlseqs_reader *} is a pointer to an opaque
type which represents an instance of control sequence reader, initialized with
@code{ctlseqs_reader_init} and deallocated with @code{ctlseqs_reader_free}
after using. It is safe to pass null pointers to @code{ctlseqs_reader_free}.
@cindex Control sequence reader initialization example
@example
struct ctlseqs_reader *reader = ctlseqs_reader_init();
// ...
ctlseqs_reader_free(reader);
@end example
@node Reader Configuration
@section Reader Configuration
Options of a control sequence reader can be set with function
@code{ctlseqs_reader_config}.
@cindex Control sequence reader configuration example
@example
union ctlseqs_value buffer[4];
struct ctlseqs_reader *reader /* = ... */;
struct ctlseqs_reader_options options = @{
.result = buffer,
.maxlen = 1024,
.fd = STDIN_FILENO,
.flags = 0,
@};
int result = ctlseqs_reader_config(reader, &options);
// ...
@end example
In @code{struct ctlseqs_reader_options}:
@itemize @bullet
@item field @code{result} is the buffer where match results are stored, as
defined in @ref{Matching String}.
@item Field @code{maxlen} is the maximum length of control sequence to process,
before the reader gives up reading and returns an error.
@item Field @code{fd} is the file descriptor to read from.
@item Field @code{flags} is the bitmask of multiple boolean options that
affects the reader's behaviour. See @ref{Reader Flags} for details.
@end itemize
Upon success, the function return @code{CTLSEQS_OK}. If the function fails to
allocate enough memory (for the internal read buffer), returns
@code{CTLSEQS_NOMEM}. If trying to set @code{maxlen} to a value smaller than
the current internal read buffer data size, returns @code{CTLSEQS_ERROR}.
@node Reader Flags
@subsection Reader Flags
@node Tips
@chapter Tips & Hints

View File

@ -88,7 +88,7 @@ followed by a pointer to the first character of the string stored in field
.
.SH RETURN VALUES
If
.I seq
.I str
contains a valid control sequence, and matches at least one pattern in
.IR matcher ,
returns a non-negative integer representing the offset of a matching pattern.
@ -107,7 +107,7 @@ terminated.
No valid control sequence is found in the given string.
.
.SH COPYRIGHT
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
Copyright (c) 2020,2021,2022 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