124 lines
3.7 KiB
Groff
124 lines
3.7 KiB
Groff
.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 "ctlseqs Library Manual"
|
|
.
|
|
.SH NAME
|
|
ctlseqs_match - match control sequence
|
|
.
|
|
.SH SYNOPSYS
|
|
.nf
|
|
.B #include <ctlseqs.h>
|
|
.PP
|
|
.BI "ssize_t ctlseqs_match(struct ctlseqs_reader const *" matcher ,
|
|
.BI " char const *" str ", size_t " str_len ", union ctlseqs_value *" result );
|
|
.fi
|
|
.
|
|
.SH DESCRIPTION
|
|
Matches string
|
|
.I str
|
|
against the patterns specified in
|
|
.IR matcher ,
|
|
until a valid control sequence is found, or
|
|
.I str_len
|
|
number of characters are processed.
|
|
.PP
|
|
For a NULL
|
|
.IR matcher ,
|
|
the function behaves as if a matcher configured with 0
|
|
.I npatterns
|
|
is specified.
|
|
.PP
|
|
Argument
|
|
.I result
|
|
is the buffer where the function stores match results.
|
|
If
|
|
.I str
|
|
contains a control sequence (or part of a control sequence), the length of the sequence is stored in
|
|
.I buffer
|
|
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 ,
|
|
a group of values is extracted from the sequence for each placeholder, and stored into
|
|
.I result
|
|
sequentially, starting at offset 2.
|
|
.PP
|
|
An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in
|
|
.BR "union ctlseqs_value" :
|
|
.PP
|
|
.nf
|
|
.in +4n
|
|
.EX
|
|
union ctlseqs_value {
|
|
char const *str;
|
|
size_t len;
|
|
unsigned long num;
|
|
};
|
|
.EE
|
|
.in
|
|
.fi
|
|
.PP
|
|
A group can contain one or multiple values, depending on different placeholders:
|
|
.TP
|
|
.B CTLSEQS_PH_NUM
|
|
A single unsigned integer.
|
|
.TP
|
|
.B CTLSEQS_PH_NUMS
|
|
An unsigned integer indicating the number of extracted values, followed by unsigned integers of that many.
|
|
.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.
|
|
.
|
|
.SH RETURN VALUES
|
|
If
|
|
.I seq
|
|
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.
|
|
.PP
|
|
Otherwise, returns a negative value:
|
|
.TP
|
|
.B CTLSEQS_NOMATCH
|
|
A valid control sequence is found, but fails to match any pattern in
|
|
.IR matcher .
|
|
.TP
|
|
.B CTLSEQS_PARTIAL
|
|
The string can be recognized as part of a control sequence, but is not yet terminated.
|
|
.TP
|
|
.B CTLSEQS_NOSEQ
|
|
No valid control sequence is found in the given string.
|
|
.
|
|
.SH COPYRIGHT
|
|
Copyright (c) 2020 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 this notice are preserved.
|
|
This file is offered as-is, without any warranty.
|
|
.
|
|
.SH SEE ALSO
|
|
.BR ctlseqs_matcher_config (3)
|