NAME

ctlseqs_matcher_config - configure control sequence matcher

SYNOPSYS

#include <ctlseqs.h>

int ctlseqs_matcher_config(
    struct ctlseqs_matcher               *matcher,
    struct ctlseqs_matcher_options const *options
);

DESCRIPTION

Changes the properties of the given matcher.

The options argument is a pointer to a struct ctlseqs_matcher_options, whose definition is shown below:





struct ctlseqs_matcher_options {
    char const *const *patterns;
    size_t             npatterns;
};

Field patterns is an array of pointers to NUL-terminated strings, each of which represents a pattern of control sequences.

Field npatterns is the number of strings provided in patterns.

Multiple calls on the same matcher will discard all data from previous calls.

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.

Currently supported placeholders:

CTLSEQS_PH_NUM: An unsigned integer.
CTLSEQS_PH_NUMS: Multiple unsigned integers separated with the semicolon ASCII character (value 0x3b).
CTLSEQS_PH_STR: A string of printable characters.
CTLSEQS_PH_CMDSTR: A string containing printable characters and characters of range 0x08~0x0d.
CTLSEQS_PH_CSI_PARAM: A string of CSI parameter bytes (range 0x30~0x3f).
CTLSEQS_PH_CSI_INTMD: A string of CSI intermediate bytes (range 0x20~0x2f).
CTLSEQS_PH_HEXNUM: A string representing a hexadecimal number.
CTLSEQS_PH_CHRSTR: A string of any bit combination which does not represent SOS or ST.

RETURN VALUE

CTLSEQS_OK: Success.
CTLSEQS_NOMEM: Fails to allocate sufficient memory.

NOTES

Any value in 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.

Currently supported escape sequences:

CSI [param...] [intmd...] final: Parameter bytes are of range 0x30~0x3f, intermediate bytes 0x20~0x2f, and final byte 0x40~0x7e.
(APC|DCS|OSC|PM) [cmdstr] ST: Command string consists of bytes of printable characters and characters of range 0x08~0x0d.
(SS2|SS3) ch: The byte following a single-shift should be a printable character.
SOS [chrstr] ST: Character string can be any bit combination which does not represent SOS or ST.

COPYRIGHT

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.