Update `ctlseqs_match()`.
This commit is contained in:
parent
f264a8f183
commit
aa3cef3bc7
|
@ -9,6 +9,7 @@
|
||||||
dist_man3_MANS = \
|
dist_man3_MANS = \
|
||||||
ctlseqs_matcher_init.3 \
|
ctlseqs_matcher_init.3 \
|
||||||
ctlseqs_matcher_config.3 \
|
ctlseqs_matcher_config.3 \
|
||||||
|
ctlseqs_match.3 \
|
||||||
ctlseqs_matcher_free.3 \
|
ctlseqs_matcher_free.3 \
|
||||||
ctlseqs_reader_init.3 \
|
ctlseqs_reader_init.3 \
|
||||||
ctlseqs_reader_config.3 \
|
ctlseqs_reader_config.3 \
|
||||||
|
|
|
@ -0,0 +1,98 @@
|
||||||
|
.TH CTLSEQS_MATCH 3 "Sep 01, 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 ", char const **" seq_ptr ,
|
||||||
|
.BI " size_t " seq_len ", union ctlseqs_value *" result );
|
||||||
|
.fi
|
||||||
|
.
|
||||||
|
.SH DESCRIPTION
|
||||||
|
Matches string against the patterns specified in
|
||||||
|
.IR matcher .
|
||||||
|
Stops when a valid control sequence is found, or when
|
||||||
|
.I seq_len
|
||||||
|
number of characters are processed.
|
||||||
|
.PP
|
||||||
|
Argument
|
||||||
|
.I seq_ptr
|
||||||
|
is the pointer to the string to be matched, which will point to the character next to the last one processed, when the function returns.
|
||||||
|
.SS Match results
|
||||||
|
Once a sequence is successfully matched, a group of values is extracted from the sequence for each placeholder, and stored into
|
||||||
|
.I result
|
||||||
|
sequentially.
|
||||||
|
.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;
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.SH RETURN VALUES
|
||||||
|
.PP
|
||||||
|
If the string specified by
|
||||||
|
.I seq_ptr
|
||||||
|
is 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
|
||||||
|
The string (or part of the string) is a valid control sequence, 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
|
||||||
|
The string cannot be recognized as a valid control sequence.
|
||||||
|
.
|
||||||
|
.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),
|
||||||
|
.BR ctlseqs_reader_config (3),
|
||||||
|
.BR ctlseqs_read (3)
|
|
@ -492,15 +492,17 @@ ctlseqs_matcher_config(struct ctlseqs_matcher *matcher, struct ctlseqs_matcher_o
|
||||||
}
|
}
|
||||||
|
|
||||||
CTLSEQS_HOT ssize_t
|
CTLSEQS_HOT ssize_t
|
||||||
ctlseqs_match(struct ctlseqs_matcher const *matcher, char const *seq, size_t seq_len, union ctlseqs_value *result)
|
ctlseqs_match(struct ctlseqs_matcher const *matcher, char const **seq_ptr, size_t seq_len, union ctlseqs_value *result)
|
||||||
{
|
{
|
||||||
struct ctlseqs_match_args args = {
|
struct ctlseqs_match_args args = {
|
||||||
.seq = seq,
|
.seq = *seq_ptr,
|
||||||
.seq_len = seq_len,
|
.seq_len = seq_len,
|
||||||
.result = result,
|
.result = result,
|
||||||
.save_seq = true,
|
.save_seq = false,
|
||||||
};
|
};
|
||||||
return ctlseqs_do_match(matcher, &args);
|
ssize_t retval = ctlseqs_do_match(matcher, &args);
|
||||||
|
*seq_ptr += args.result_idx;
|
||||||
|
return retval;
|
||||||
}
|
}
|
||||||
|
|
||||||
CTLSEQS_COLD void
|
CTLSEQS_COLD void
|
||||||
|
|
|
@ -407,7 +407,7 @@ void
|
||||||
ctlseqs_matcher_free(struct ctlseqs_matcher *matcher);
|
ctlseqs_matcher_free(struct ctlseqs_matcher *matcher);
|
||||||
|
|
||||||
ssize_t
|
ssize_t
|
||||||
ctlseqs_match(struct ctlseqs_matcher const *matcher, char const *seq, size_t seq_len, union ctlseqs_value *result);
|
ctlseqs_match(struct ctlseqs_matcher const *matcher, char const **seq_ptr, size_t seq_len, union ctlseqs_value *result);
|
||||||
|
|
||||||
struct ctlseqs_reader *
|
struct ctlseqs_reader *
|
||||||
ctlseqs_reader_init();
|
ctlseqs_reader_init();
|
||||||
|
|
Loading…
Reference in New Issue