Update documentation for matcher.
continuous-integration/drone/push Build is passing
Details
continuous-integration/drone/push Build is passing
Details
This commit is contained in:
parent
3db4333d0a
commit
0ebc0054c4
|
@ -221,7 +221,7 @@ 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 using, it should
|
||||
should be initialized with @code{ctlseqs_matcher_init}. After used, it should
|
||||
be deallocated with @code{ctlseqs_matcher_free}.
|
||||
|
||||
@cindex Control sequence matcher initialization example
|
||||
|
@ -267,8 +267,10 @@ the data generated from the last invocation. Upon success, the function returns
|
|||
@code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns
|
||||
@code{CTLSEQS_NOMEM}.
|
||||
|
||||
@quotation Caution
|
||||
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
||||
invalid, function behaviour is undefined. See @ref{Patterns} for details.
|
||||
@end quotation
|
||||
|
||||
@menu
|
||||
* Patterns:: Supported control squence pattern formats
|
||||
|
@ -327,8 +329,8 @@ The following code is a valid example of patterns:
|
|||
|
||||
@example
|
||||
const char *patterns[] = @{
|
||||
CTLSEQS_XTVERSION(),
|
||||
CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM),
|
||||
CTLSEQS_XTVERSION(),
|
||||
CTLSEQS_DECRQM("1000"),
|
||||
// ...
|
||||
@};
|
||||
|
@ -342,17 +344,6 @@ Function @code{ctlseqs_match} matches a given character string to a matcher.
|
|||
The function accepts four arguments: the matcher, the string to match, length
|
||||
of the string to match, and a buffer which stores the match result.
|
||||
|
||||
The following code is an example of invoking @code{ctlseqs_match}:
|
||||
|
||||
@example
|
||||
struct ctlseqs_matcher *matcher /* = ... */;
|
||||
// ...
|
||||
char const *str = CTLSEQS_CUP("2", "4");
|
||||
size_t str_len = sizeof(CTLSEQS_CUP("2", "4")) - 1;
|
||||
union ctlseqs_value buffer[4];
|
||||
ssize_t result = ctlseqs_match(matcher, str, str_len, buffer);
|
||||
@end example
|
||||
|
||||
Before matching, a buffer which is large enough to store the match result
|
||||
should be allocated. The buffer is an array of @code{union ctlseqs_value},
|
||||
whose definition is shown below:
|
||||
|
@ -377,8 +368,43 @@ If @code{ctlseqs_match} fails to find any control functions, returns
|
|||
control function, the function returns @code{CTLSEQS_NOMATCH}.
|
||||
|
||||
If the control function matches a pattern configured in the matcher, returns
|
||||
the offset of the matched pattern, and store the extracted values to the result
|
||||
buffer according to each of the placeholders, starting from offset 2.
|
||||
the offset of the matched pattern, and stores the extracted values to the
|
||||
result buffer according to each of the placeholders, starting from offset 2:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{CTLSEQS_PH_NUM}, @code{CTLSEQS_PH_HEXNUM}: The integer is stored in
|
||||
field @code{num}.
|
||||
@item @code{CTLSEQS_PH_NUMS}: The number of integers is stored in field
|
||||
@code{len}, followed by that many integers stored in field @code{num}.
|
||||
@item @code{CTLSEQS_PH_CSI_PARAM}, @code{CTLSEQS_PH_CSI_INTMD},
|
||||
@code{CTLSEQS_PH_STR}, @code{CTLSEQS_PH_CMDSTR}, @code{CTLSEQS_PH_CHRSTR}: The
|
||||
length of the string is stored in field @code{len}, followed by a pointer to
|
||||
the first character of the string stored in field @code{str}.
|
||||
@end itemize
|
||||
|
||||
The following code is an example of invoking @code{ctlseqs_match}:
|
||||
|
||||
@example
|
||||
struct ctlseqs_matcher *matcher /* = ... */;
|
||||
// ...
|
||||
union ctlseqs_value buffer[4];
|
||||
char const *str = "foo" CTLSEQS_CUP("2", "4");
|
||||
size_t str_len = sizeof("foo" CTLSEQS_CUP("2", "4")) - 1;
|
||||
ssize_t result = ctlseqs_match(matcher, str, str_len, buffer);
|
||||
|
||||
assert(result == 0);
|
||||
assert(buffer[0].len == 6 && buffer[1].str == str + 3);
|
||||
assert(buffer[2].num == 2 && buffer[3].num == 4);
|
||||
@end example
|
||||
|
||||
Function @code{ctlseqs_match} allows @code{NULL} value for argument
|
||||
@code{matcher}, in which case it behaves like a matcher configured with zero
|
||||
patterns is provided.
|
||||
|
||||
@quotation Caution
|
||||
If the given string can match multiple patterns in the matcher, it is
|
||||
unspecified which of them will be the final match result.
|
||||
@end quotation
|
||||
|
||||
|
||||
@node Control Sequence Reading
|
||||
|
|
|
@ -37,7 +37,6 @@ at offset 0, and the pointer to the starting ESC character at offset 1.
|
|||
Otherwise,
|
||||
.I buffer
|
||||
value at offset 0 and 1 is unspecified.
|
||||
.
|
||||
.SS Match results
|
||||
If the control sequence matches a pattern in
|
||||
.IR matcher ,
|
||||
|
@ -62,37 +61,21 @@ union ctlseqs_value {
|
|||
.PP
|
||||
A group can contain one or multiple values, depending on different placeholders:
|
||||
.TP
|
||||
.B CTLSEQS_PH_NUM
|
||||
A single unsigned integer.
|
||||
.BR CTLSEQS_PH_NUM ", " CTLSEQS_PH_HEXNUM
|
||||
The integer is stored in field
|
||||
.IR num .
|
||||
.TP
|
||||
.B CTLSEQS_PH_NUMS
|
||||
An unsigned integer indicating the number of extracted values, followed by unsigned integers of that many.
|
||||
The number of integers is stored in field
|
||||
.IR len ,
|
||||
followed by that many integers stored in field
|
||||
.IR num .
|
||||
.TP
|
||||
.B CTLSEQS_PH_STR
|
||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string of printable characters.
|
||||
.TP
|
||||
.B CTLSEQS_PH_CMDSTR
|
||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string containing only printable characters and characters of range 0x08\(ti0x0d.
|
||||
.TP
|
||||
.B CTLSEQS_PH_CSI_PARAM
|
||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI parameter bytes (range 0x30\(ti0x3f).
|
||||
.TP
|
||||
.B CTLSEQS_PH_CSI_INTMD
|
||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI intermediate bytes (range 0x20\(ti0x2f).
|
||||
.TP
|
||||
.B CTLSEQS_PH_HEXNUM
|
||||
A single unsigned integer, which is the integer value of extracted hexadecimal string.
|
||||
.TP
|
||||
.B CTLSEQS_PH_CHRSTR
|
||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string of any bit combination which does not represent SOS or ST.
|
||||
.PP
|
||||
The
|
||||
.I len
|
||||
field of
|
||||
.B "union ctlseqs_value"
|
||||
should be used instead of
|
||||
.I num
|
||||
when the unsigned integer refers to the length of the following string or number of following values.
|
||||
.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR
|
||||
The length of the string is stored in field
|
||||
.IR len ,
|
||||
followed by a pointer to the first character of the string stored in field
|
||||
.IR str .
|
||||
.
|
||||
.SH RETURN VALUES
|
||||
If
|
||||
|
|
Loading…
Reference in New Issue