From aa3cef3bc79321e919ccdc5787f471920a5876e5 Mon Sep 17 00:00:00 2001 From: CismonX Date: Thu, 24 Dec 2020 20:55:49 +0800 Subject: [PATCH] Update `ctlseqs_match()`. --- man/Makefile.am | 1 + man/ctlseqs_match.3 | 98 +++++++++++++++++++++++++++++++++++++++++++++ src/ctlseqs.c | 10 +++-- src/ctlseqs.h | 2 +- 4 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 man/ctlseqs_match.3 diff --git a/man/Makefile.am b/man/Makefile.am index 881cf0e..324b814 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -9,6 +9,7 @@ dist_man3_MANS = \ ctlseqs_matcher_init.3 \ ctlseqs_matcher_config.3 \ + ctlseqs_match.3 \ ctlseqs_matcher_free.3 \ ctlseqs_reader_init.3 \ ctlseqs_reader_config.3 \ diff --git a/man/ctlseqs_match.3 b/man/ctlseqs_match.3 new file mode 100644 index 0000000..8225ea1 --- /dev/null +++ b/man/ctlseqs_match.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 +.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 +.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) diff --git a/src/ctlseqs.c b/src/ctlseqs.c index 00627fc..d12b715 100644 --- a/src/ctlseqs.c +++ b/src/ctlseqs.c @@ -492,15 +492,17 @@ ctlseqs_matcher_config(struct ctlseqs_matcher *matcher, struct ctlseqs_matcher_o } 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 = { - .seq = seq, + .seq = *seq_ptr, .seq_len = seq_len, .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 diff --git a/src/ctlseqs.h b/src/ctlseqs.h index 8cf2913..cab2cc9 100644 --- a/src/ctlseqs.h +++ b/src/ctlseqs.h @@ -407,7 +407,7 @@ void ctlseqs_matcher_free(struct ctlseqs_matcher *matcher); 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 * ctlseqs_reader_init();