ctlseqs/man/ctlseqs_matcher_config.3

115 lines
2.9 KiB
Groff

.TH CTLSEQS_MATCHER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
.
.SH NAME
ctlseqs_matcher_config - configure control sequence matcher
.
.SH SYNOPSYS
.nf
.B #include <ctlseqs.h>
.PP
.B int ctlseqs_matcher_config(
.BI " struct ctlseqs_matcher *" matcher ,
.BI " struct ctlseqs_matcher_options const *" options
.B );
.fi
.
.SH DESCRIPTION
Changes the properties of the given
.IR matcher .
.PP
The
.I options
argument is a pointer to a
.BR "struct ctlseqs_matcher_options" ,
whose definition is shown below:
.PP
.nf
.in +4n
.EX
struct ctlseqs_matcher_options {
char const *const *patterns;
size_t npatterns;
};
.EE
.in
.fi
.PP
Field
.I patterns
is an array of pointers to NUL-terminated strings, each of which represents a pattern of control sequences.
.PP
Field
.I npatterns
is the number of strings provided in
.IR patterns .
.PP
Multiple calls on the same
.I matcher
will discard all data from previous calls.
.SS Placeholders
A pattern may contain zero to multiple placeholders, where a placeholder indicates that when matching a string against the pattern, the value at the placeholder's location should conform to its rules.
.PP
Currently supported placeholders:
.TP
.B CTLSEQS_PH_NUM
An unsigned integer.
.TP
.B CTLSEQS_PH_NUMS
Multiple unsigned integers separated with the semicolon ASCII character (value 0x3b).
.TP
.B CTLSEQS_PH_STR
A string of printable characters.
.TP
.B CTLSEQS_PH_CMDSTR
A string containing printable characters and characters of range 0x08\(ti0x0d.
.TP
.B CTLSEQS_PH_CSI_PARAM
A string of CSI parameter bytes (range 0x30\(ti0x3f).
.TP
.B CTLSEQS_PH_CSI_INTMD
A string of CSI intermediate bytes (range 0x20\(ti0x2f).
.TP
.B CTLSEQS_PH_HEXNUM
A string representing a hexadecimal number.
.TP
.B CTLSEQS_PH_CHRSTR
A string of any bit combination which does not represent SOS or ST.
.
.SH RETURN VALUE
.TP
.B CTLSEQS_OK
Success.
.TP
.B CTLSEQS_NOMEM
Fails to allocate sufficient memory.
.
.SH NOTES
Any value in
.I patterns
must correspond to an ECMA-35/ECMA-48 conformant escape sequence, and should also be supported by the matcher.
Otherwise, function behaviour is undefined.
.PP
Currently supported escape sequences:
.TP
.B CSI [param...] [intmd...] final
Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and final byte 0x40\(ti0x7e.
.TP
.B (APC|DCS|OSC|PM) [cmdstr] ST
Command string consists of bytes of printable characters and characters of range 0x08\(ti0x0d.
.TP
.B (SS2|SS3) ch
The byte following a single-shift should be a printable character.
.TP
.B SOS [chrstr] ST
Character string can be any bit combination which does not represent SOS or ST.
.
.SH COPYRIGHT
Copyright (c) 2020,2021 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_match (3),
.BR ctlseqs_read (3)