NAME

ctlseqs_match - match control sequence

SYNOPSYS

#include <ctlseqs.h>

ssize_t ctlseqs_match(
    struct ctlseqs_matcher const *matcher,
    char                   const *str,
    size_t                        str_len,
    union ctlseqs_value          *result
);

DESCRIPTION

Matches string str against the patterns specified in matcher, until a valid control sequence is found, or str_len number of characters are processed.

For a NULL matcher, the function behaves as if a matcher configured with 0 npatterns is specified.

Argument result is the buffer where the function stores match results. If str contains a control sequence (or part of a control sequence), the length of the sequence is stored in buffer at offset 0, and the pointer to the starting ESC character at offset 1. Otherwise, buffer value at offset 0 and 1 is unspecified.

Match results

If the control sequence matches a pattern in matcher, a group of values is extracted from the sequence for each placeholder, and stored into result sequentially, starting at offset 2.

An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in union ctlseqs_value:





union ctlseqs_value {
    char const    *str;
    size_t         len;
    unsigned long  num;
};

A group can contain one or multiple values, depending on different placeholders:

CTLSEQS_PH_NUM, CTLSEQS_PH_HEXNUM: The integer is stored in field num.
CTLSEQS_PH_NUMS: The number of integers is stored in field len, followed by that many integers stored in field num.
CTLSEQS_PH_STR, CTLSEQS_PH_CMDSTR, CTLSEQS_PH_CSI_PARAM, CTLSEQS_PH_CSI_INTMD, CTLSEQS_PH_CHRSTR: The length of the string is stored in field len, followed by a pointer to the first character of the string stored in field str.

RETURN VALUES

If seq contains a valid control sequence, and matches at least one pattern in matcher, returns a non-negative integer representing the offset of a matching pattern.

Otherwise, returns a negative value:

CTLSEQS_NOMATCH: A valid control sequence is found, but fails to match any pattern in matcher.
CTLSEQS_PARTIAL: The string can be recognized as part of a control sequence, but is not yet terminated.
CTLSEQS_NOSEQ: No valid control sequence is found in the given string.

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.