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