Update man pages.
This commit is contained in:
parent
c4b9ba3aef
commit
5bc1441777
GPG Key ID:
3094873E29A482FB
|
|
@ -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 <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 );
|
||||
.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 <admin@cismon.net>
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue