diff --git a/man/ctlseqs_match.3 b/man/ctlseqs_match.3 index 8225ea1..002ccb4 100644 --- a/man/ctlseqs_match.3 +++ b/man/ctlseqs_match.3 @@ -1,4 +1,4 @@ -.TH CTLSEQS_MATCH 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual" +.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 "ctlseqs Library Manual" . .SH NAME ctlseqs_match - match control sequence @@ -7,24 +7,43 @@ ctlseqs_match - match control sequence .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 ); +.BI "ssize_t ctlseqs_match(struct ctlseqs_reader const *" matcher , +.BI " char const *" str ", size_t " str_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 +Matches string +.I str +against the patterns specified in +.IR matcher , +until a valid control sequence is found, or +.I str_len number of characters are processed. .PP +For a NULL +.IR matcher , +the function behaves as if a matcher configured with 0 +.I npatterns +is specified. +.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. +is the buffer where the function stores match results. +If +.I str +contains a control sequence (or part of a control sequence), the length of the sequence is stored in +.I buffer +at offset 0, and the pointer to the starting ESC character at offset 1. +Otherwise, +.I buffer +value at offset 0 and 1 is unspecified. +. +.SS Match results +If the control sequence matches a pattern in +.IR matcher , +a group of values is extracted from the sequence for each placeholder, and stored into +.I result +sequentially, starting at offset 2. .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" : @@ -34,6 +53,7 @@ An extracted value can be either a string (not guaranteed to be NUL-terminated), .EX union ctlseqs_value { char const *str; + size_t len; unsigned long num; }; .EE @@ -65,26 +85,33 @@ A single unsigned integer, which is the integer value of extracted hexadecimal s .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. +.PP +The +.I len +field of +.B "union ctlseqs_value" +should be used instead of +.I num +when the unsigned integer refers to the length of the following string or number of following values. . .SH RETURN VALUES -.PP -If the string specified by -.I seq_ptr -is a valid control sequence, and matches at least one pattern in +If +.I seq +contains 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 +A valid control sequence is found, 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. +No valid control sequence is found in the given string. . .SH COPYRIGHT Copyright (c) 2020 CismonX @@ -93,6 +120,4 @@ Copying and distribution of this file, with or without modification, are permitt 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) +.BR ctlseqs_matcher_config (3) diff --git a/man/ctlseqs_read.3 b/man/ctlseqs_read.3 index 10b6baa..7dc0a4b 100644 --- a/man/ctlseqs_read.3 +++ b/man/ctlseqs_read.3 @@ -12,22 +12,21 @@ ctlseqs_read - read control sequence .fi . .SH DESCRIPTION -Attempts to read a terminal control sequence, and extract values according to given patterns. +Attempts to read a terminal control sequence with given +.IR reader , +and match it against the patterns in +.IR matcher , +similar to +.BR ctlseqs_match() . .PP -The +When match fails, the number of characters read will be stored into the +.I result +field in .I reader -argument specifies the behaviour of the read operation, which can be configured with -.BR ctlseqs_reader_config (). -.PP -The -.I matcher -argument specifies the expected patterns of control sequences to be matched upon after a successful read, which can be configured with -.BR ctlseqs_matcher_config (). -A NULL -.I matcher -is allowed, acting as if -.I npatterns -is 0. +at offset 0, and the pointer to the first character stored at offset 1. +If option +.B CTLSEQS_READER_SAVE_MATCHED_SEQS +is enabled, also save those values when the match is successful. .PP Argument .I timeout @@ -37,6 +36,14 @@ If is -1, the function blocks indefinitely. If option .B CTLSEQS_READER_NO_POLL is enabled, this argument has no effect. +.SS Match results +For a successful match, the extracted values are stored in +.I result +like +.BR ctlseqs_match() , +but starting at offset 0 unless +.B CTLSEQS_READER_SAVE_MATCHED_SEQS +is enabled. . .SH RETURN VALUE If a control sequence is successfully read, and matches at least one pattern in @@ -82,5 +89,6 @@ Copying and distribution of this file, with or without modification, are permitt This file is offered as-is, without any warranty. . .SH SEE ALSO +.BR ctlseqs_match (3), .BR ctlseqs_matcher_config (3), .BR ctlseqs_reader_config (3) diff --git a/man/ctlseqs_reader_config.3 b/man/ctlseqs_reader_config.3 index 2a7eb1e..4981e2b 100644 --- a/man/ctlseqs_reader_config.3 +++ b/man/ctlseqs_reader_config.3 @@ -51,69 +51,7 @@ is the file descriptor to read from. Field .I flags is the bit mask of multiple boolean options. -.SS Extracted values -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 -Once a sequence is successfully matched, a group of values is extracted from the sequence for each placeholder, and stored into -.I result -sequentially. -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. -.PP -If the -.BR ctlseqs_read () -call returns -.BR CTLSEQS_NOSEQ , -.BR CTLSEQS_NOMATCH , -.B CTLSEQS_PARTIAL -or -.BR CTLSEQS_NOMEM , -the length of the entire string followed by the string itself will be stored into -.IR result . -The same is true for a successful match when option -.B CTLSEQS_READER_SAVE_MATCHED_SEQS -is enabled, inserting these two values before the extracted ones. -.SS Flags -Flags are boolean switches which can be combined as a bitmask for the -.I flags -option. -.PP -Currently supported flags: +.SS Supported flags .TP .B CTLSEQS_READER_NO_POLL In a @@ -129,7 +67,9 @@ is maintained in an event loop. .B CTLSEQS_READER_SAVE_MATCHED_SEQS When a sequence is successfully matched against a pattern during .BR ctlseqs_read (), -save the original sequence to buffer alongside the extracted values. +save the original sequence to +.I result +alongside the extracted values. . .SH RETURN VALUE .TP @@ -151,4 +91,5 @@ Copying and distribution of this file, with or without modification, are permitt This file is offered as-is, without any warranty. . .SH SEE ALSO +.BR ctlseqs_match (3), .BR ctlseqs_read (3)