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
|
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 using, it should
|
should be initialized with @code{ctlseqs_matcher_init}. After used, 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
|
||||||
|
@ -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_OK}. If the function fails to allocate enough memory, returns
|
||||||
@code{CTLSEQS_NOMEM}.
|
@code{CTLSEQS_NOMEM}.
|
||||||
|
|
||||||
|
@quotation Caution
|
||||||
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
||||||
invalid, function behaviour is undefined. See @ref{Patterns} for details.
|
invalid, function behaviour is undefined. See @ref{Patterns} for details.
|
||||||
|
@end quotation
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Patterns:: Supported control squence pattern formats
|
* Patterns:: Supported control squence pattern formats
|
||||||
|
@ -327,8 +329,8 @@ The following code is a valid example of patterns:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
const char *patterns[] = @{
|
const char *patterns[] = @{
|
||||||
CTLSEQS_XTVERSION(),
|
|
||||||
CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM),
|
CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM),
|
||||||
|
CTLSEQS_XTVERSION(),
|
||||||
CTLSEQS_DECRQM("1000"),
|
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
|
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.
|
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
|
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},
|
should be allocated. The buffer is an array of @code{union ctlseqs_value},
|
||||||
whose definition is shown below:
|
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}.
|
control function, the function returns @code{CTLSEQS_NOMATCH}.
|
||||||
|
|
||||||
If the control function matches a pattern configured in the matcher, returns
|
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
|
the offset of the matched pattern, and stores the extracted values to the
|
||||||
buffer according to each of the placeholders, starting from offset 2.
|
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
|
@node Control Sequence Reading
|
||||||
|
|
|
@ -37,7 +37,6 @@ at offset 0, and the pointer to the starting ESC character at offset 1.
|
||||||
Otherwise,
|
Otherwise,
|
||||||
.I buffer
|
.I buffer
|
||||||
value at offset 0 and 1 is unspecified.
|
value at offset 0 and 1 is unspecified.
|
||||||
.
|
|
||||||
.SS Match results
|
.SS Match results
|
||||||
If the control sequence matches a pattern in
|
If the control sequence matches a pattern in
|
||||||
.IR matcher ,
|
.IR matcher ,
|
||||||
|
@ -62,37 +61,21 @@ union ctlseqs_value {
|
||||||
.PP
|
.PP
|
||||||
A group can contain one or multiple values, depending on different placeholders:
|
A group can contain one or multiple values, depending on different placeholders:
|
||||||
.TP
|
.TP
|
||||||
.B CTLSEQS_PH_NUM
|
.BR CTLSEQS_PH_NUM ", " CTLSEQS_PH_HEXNUM
|
||||||
A single unsigned integer.
|
The integer is stored in field
|
||||||
|
.IR num .
|
||||||
.TP
|
.TP
|
||||||
.B CTLSEQS_PH_NUMS
|
.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
|
.TP
|
||||||
.B CTLSEQS_PH_STR
|
.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR
|
||||||
An unsigned integer indicating the number of characters of the extracted string, followed by a string of printable characters.
|
The length of the string is stored in field
|
||||||
.TP
|
.IR len ,
|
||||||
.B CTLSEQS_PH_CMDSTR
|
followed by a pointer to the first character of the string stored in field
|
||||||
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.
|
.IR str .
|
||||||
.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.
|
|
||||||
.
|
.
|
||||||
.SH RETURN VALUES
|
.SH RETURN VALUES
|
||||||
If
|
If
|
||||||
|
|
Loading…
Reference in New Issue