Add documentation for control sequence matcher.
This commit is contained in:
parent
91314246ff
commit
6cdb96491b
|
@ -64,10 +64,8 @@ version.
|
|||
* Example Programs:: Example programs using ctlseqs.
|
||||
|
||||
Appendices
|
||||
|
||||
* API Reference:: C API reference for ctlseqs.
|
||||
* GNU Free Documentation License:: Copying conditions of this manual.
|
||||
|
||||
@end menu
|
||||
|
||||
|
||||
|
@ -218,7 +216,73 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
|
|||
However, as the number of possible matches grows, this naive implementation
|
||||
becomes less efficient and harder to maintain.
|
||||
|
||||
The control sequence matcher provided by ctlseqs aims at solving such problems.
|
||||
Such problems can be easily solved by using the control sequence matcher
|
||||
provided by ctlseqs.
|
||||
|
||||
The @code{struct ctlseqs_matcher *} is a pointer to an opaque type which
|
||||
represents an instance of control sequence matcher. Before using, the matcher
|
||||
should be initialized with @code{ctlseqs_matcher_init}. After using, it should
|
||||
be deallocated with @code{ctlseqs_matcher_free}.
|
||||
|
||||
@cindex Control sequence matcher initialization example
|
||||
@example
|
||||
struct ctlseqs_matcher *matcher = ctlseqs_matcher_init();
|
||||
// ...
|
||||
ctlseqs_matcher_free(matcher);
|
||||
@end example
|
||||
|
||||
On rare occurences when ctlseqs fail to allocate enough memory, function
|
||||
@code{ctlseqs_matcher_init} may return @code{NULL}. However, it is okay to pass
|
||||
null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
|
||||
|
||||
@menu
|
||||
* Matcher Configuration:: Configuring a control sequence matcher
|
||||
* Matching String:: Matching a string with control sequence matcher
|
||||
@end menu
|
||||
|
||||
|
||||
@node Matcher Configuration
|
||||
@section Matcher Configuration
|
||||
|
||||
Matcher configuration consists of two parts: the number of matching patterns,
|
||||
and the patterns themselves. Invoke function @code{ctlseqs_matcher_config} to
|
||||
configure a matcher.
|
||||
|
||||
@cindex Control sequence matcher configuration example
|
||||
@example
|
||||
struct ctlseqs_matcher *matcher /* = ... */;
|
||||
char const *patterns[] = @{
|
||||
CTLSEQS_XTVERSION(),
|
||||
CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM),
|
||||
// ...
|
||||
@};
|
||||
struct ctlseqs_matcher_options options = @{
|
||||
.patterns = patterns,
|
||||
.npatterns = sizeof(patterns) / sizeof(char const *),
|
||||
@};
|
||||
int result = ctlseqs_matcher_config(matcher, &options);
|
||||
// ...
|
||||
@end example
|
||||
|
||||
Each invocation of @code{ctlseqs_matcher_config} on the same matcher overwrites
|
||||
the data generated from the last invocation. Upon success, the function returns
|
||||
@code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns
|
||||
@code{CTLSEQS_NOMEM}.
|
||||
|
||||
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
||||
invalid, function behaviour is undefined. See @ref{Patterns} for details.
|
||||
|
||||
@menu
|
||||
* Patterns:: Supported control squence pattern formats
|
||||
@end menu
|
||||
|
||||
|
||||
@node Patterns
|
||||
@subsection Patterns
|
||||
|
||||
|
||||
@node Matching String
|
||||
@section Matching String
|
||||
|
||||
|
||||
@node Control Sequence Reading
|
||||
|
|
Loading…
Reference in New Issue