From 592bb717d6d5e4b6d366b8d51a1d7c94d10f58d7 Mon Sep 17 00:00:00 2001 From: CismonX Date: Mon, 2 May 2022 21:04:06 +0800 Subject: [PATCH] update documentation --- doc/ctlseqs.texi | 80 ++++++++++++++++++++++++++++++++++++++------- man/ctlseqs_match.3 | 4 +-- 2 files changed, 71 insertions(+), 13 deletions(-) diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index a5c90c9..91de2b3 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -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 +Copyright @copyright{} 2021,2022 CismonX @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 diff --git a/man/ctlseqs_match.3 b/man/ctlseqs_match.3 index 9dba0e4..3f4cd73 100644 --- a/man/ctlseqs_match.3 +++ b/man/ctlseqs_match.3 @@ -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 +Copyright (c) 2020,2021,2022 CismonX .PP Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and