update documentation
This commit is contained in:
parent
3447a058a7
commit
592bb717d6
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue