diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index dc6d793..a376456 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -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