update documentation

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 <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

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 <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