update documentation
This commit is contained in:
parent
3447a058a7
commit
592bb717d6
|
@ -3,14 +3,14 @@
|
||||||
@c %**start of header
|
@c %**start of header
|
||||||
@setfilename ctlseqs.info
|
@setfilename ctlseqs.info
|
||||||
@include version.texi
|
@include version.texi
|
||||||
@settitle ctlseqs @value{VERSION} Manual
|
@settitle ctlseqs @value{VERSION}
|
||||||
@c %**end of header
|
@c %**end of header
|
||||||
|
|
||||||
|
|
||||||
@copying
|
@copying
|
||||||
This manual is for ctlseqs, a helper library for control sequences.
|
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
|
@quotation
|
||||||
Permission is granted to copy, distribute and/or modify this document under
|
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.
|
This manual is for ctlseqs, a helper library for control sequences.
|
||||||
|
|
||||||
Permission is granted to copy, distribute and/or modify this document under
|
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
|
any later version published by the Free Software Foundation; with no
|
||||||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
|
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);
|
printf(CTLSEQS_CUP("%d", "%d"), 3, 4);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Keep in mind that the standard output stream is line buffered in a terminal.
|
Keep in mind that the standard output stream is by default line buffered in a
|
||||||
Either @code{fflush(stdout)} after printing, or disable output buffering with
|
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)}.
|
@code{setvbuf(stdout, NULL, _IONBF, 0)}.
|
||||||
|
|
||||||
|
|
||||||
|
@ -197,15 +198,13 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
|
||||||
@}
|
@}
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
However, as the number of possible matches grows, this naive implementation
|
However, as the number of patterns grows, this naive implementation becomes
|
||||||
becomes less efficient and harder to maintain.
|
less efficient and harder to maintain. This problem can be easily solved by
|
||||||
|
using the control sequence matcher provided by ctlseqs.
|
||||||
Such problems 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
|
The @code{struct ctlseqs_matcher *} is a pointer to an opaque type which
|
||||||
represents an instance of control sequence matcher. Before using, the matcher
|
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}.
|
be deallocated with @code{ctlseqs_matcher_free}.
|
||||||
|
|
||||||
@cindex Control sequence matcher initialization example
|
@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
|
@node Control Sequence Reading
|
||||||
@chapter 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
|
@node Tips
|
||||||
@chapter Tips & Hints
|
@chapter Tips & Hints
|
||||||
|
|
|
@ -88,7 +88,7 @@ followed by a pointer to the first character of the string stored in field
|
||||||
.
|
.
|
||||||
.SH RETURN VALUES
|
.SH RETURN VALUES
|
||||||
If
|
If
|
||||||
.I seq
|
.I str
|
||||||
contains a valid control sequence, and matches at least one pattern in
|
contains a valid control sequence, and matches at least one pattern in
|
||||||
.IR matcher ,
|
.IR matcher ,
|
||||||
returns a non-negative integer representing the offset of a matching pattern.
|
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.
|
No valid control sequence is found in the given string.
|
||||||
.
|
.
|
||||||
.SH COPYRIGHT
|
.SH COPYRIGHT
|
||||||
Copyright (c) 2020,2021 CismonX <admin@cismon.net>
|
Copyright (c) 2020,2021,2022 CismonX <admin@cismon.net>
|
||||||
.PP
|
.PP
|
||||||
Copying and distribution of this file, with or without modification, are
|
Copying and distribution of this file, with or without modification, are
|
||||||
permitted in any medium without royalty, provided the copyright notice and
|
permitted in any medium without royalty, provided the copyright notice and
|
||||||
|
|
Loading…
Reference in New Issue