yREGEX.3

.TH yREGEX 3 2017-nov "linux" "interfacing applications with library"

.SH NAME
.B yREGEX
\- personal, small-volume regular-expression matching library

.SH PATRON
.B artemis-agrotera
(the huntress) goddess of the wilderness

.SH IMAGERY
beautiful young woman in cloak and deer pelt, with bow and spears

.SH SUMMARY
yREGEX is a transparent library for small-volume, day-to-day regular expression
matching based on ken thompsons finite automata algorithm (not recursion),
plus added back-references and sub-match rules.

.SH CRAZY, NIAVE, DOG-FOODING, BOOT-STRAPPING ANIMAL
i am not competing to be the best.  i created this to understand, learn,
and own every byte.  it's optimized for transparency and debugging.  if i
wanted awesome, fast, and cutting-edge, i'd use yours ;)

.SH DOCUMENTATION FILES (see also)
.nf  
yREGEX (3)·········interfacing applications with library
yREGEX (6)         interactive usage and navigation
.B yREGEX (7)         decision rationale, scope, and objectives

.SH TABLE OF CONTENTS
.nf  
a) synopsis        standard public function overview
b) primary         compiling and executing
c) solution        getting solution details
d) cursoring       walking through alternate solutions
e) debugging       logging, debugging, and tracing

.SH A) SYNOPSIS
.nf
---(header)------------------------------------
.B #include  <yREGEX.h>
.sp
---(primary)-----------------------------------
.BI "char  yREGEX_comp   (cchar *" "a_regex" ");"
.BI "char  yREGEX_exec   (cchar *" "a_text " ");"
.BI "char  yREGEX_fast   (cchar *" "a_text " ");"
.sp
---(solution)----------------------------------
.BI "char  yREGEX_best   (cchar  " "a_type " ", cchar " "a_side" ","
.BI " " "                    " "int   *" "a_beg  " ", int  *" "a_len"  ","
.BI " " "                    " "int   *" "a_fbeg " ", int  *" "a_flen" ");"
.sp
---(cursoring)---------------------------------
.BI "char  yREGEX_method (cchar  " "a_type " ");"
.BI "char  yREGEX_cursor (cchar  " "a_dir  " ","
.BI " " "                    " "int   *" "a_beg  " ", int  *" "a_len"  ","
.BI " " "                    " "int   *" "a_fbeg " ", int  *" "a_flen" ");"
.sp
---(linking)-----------------------------------
.B link with -L/usr/local/libs -lyREGEX or -lyREGEX_debug

.SH B) PRIMARY
yREGEX is pretty standard stuff from an interface standpoint, but a little
simplier.  mainly because it is not re-entrant so it does not require pointers
to maintain context.

.B yREGEX_comp (<regex>)
takes one argument, a plain-text c-string containing the regular expression.
it then verify and precompile its contents for execution.  a negative return
value means the regex was not correct.

.B yREGEX_exec (<text>)
takes one argument, a plain-text c-string containing the text to be searched.
the compiled regex is used to find matches and the number of matches found
is returned.

.B yREGEX_fast (<text>)
same as yREGEX_exec, but returns once the first match is found.  this is
useful when just filtering matching lines.

.SH C) SOLUTIONS
yREGEX is a little different here as it does not return match arrays for the
source program to iterate over.  yREGEX_exec returns the number of matches
(100 means >= 100).

.B yREGEX_best (<type>, <start>, <beg>, <len>, <fbeg>, <flen>)
.RS 3
returns the best match based on the first two arguments.
.RE

.RS 3
.B <type>
   YREGEX_GREEDY   biggest match,
   YREGEX_LAZY     smallest match, or
   YREGEX_BEST     scored using regex (always YREGEX_MOST).

.B <start>
   YREGEX_LEFT     leftomst match,
   YREGEX_RIGHT    rightmost match, or
   YREGEX_MOST     most greedy or lazy match based on <type>.

.B <beg>
returns the start position of selected match (may be NULL).

.B <len>
returns the length of selected match (may be NULL).

.B <fbeg>
returns the start position of ¼focus½ group (may be NULL).

.B <flen>
returns the length of ¼focus½ group (may be NULL).
.RE

.SH D) CURSORING
in addition to providing the best solution, you can cursor over the
alternative solutions.

.B yREGEX_method (<type>)
.RS 3
prepares the match cursor for one of two types of matches as shown above
(yREGEX_greedy, yREGEX_lazy).  defaults to greedy.
.RE

.B yREGEX_cursor (<dir>, <beg>, <len>, <fbeg>, <flen>)
.RS 3
walks through the matches for the type set in yREGEX_method.  same as
yREGEX_best, it returns both the match beg and length as well as the focus
group beg and length.
.RE

.RS 3
.B <dir>
is '['=head '>'=next '.'=curr '<'=prev ']'=last

.B <beg>, <len>, <fbeg>, and <flen>
same as yREGEX_best.
.RE

.SH FLAWS
.B not re-entrant,
can not be used on two regex patterns simultaneously.

.B not recursive,
so different solution orders than standard libraries.

.B named patterns
are internally compiled, and so not as flexible

.SH AUTHOR
heatherly <jelloshrke at gmail dot com>

.SH COLOPHON
this page is part of a documentation package mean to make the use of the
heatherly tools easier and faster