GNU Info

(sc)Using Regi

---

Next: Frames You Can Customize Prev: Configuring the Citation Engine Up: Configuring the Citation Engine

---

Enter node , (file) or (file)node

Using Regi
==========

   Regi works by interpreting frames with the function
`regi-interpret'.  A frame is a list of arbitrary size where each
element is a entry of the following form:

     (PRED FUNC [NEGATE-P [CASE-FOLD-SEARCH]])

   Regi starts with the first entry in a frame, evaluating the PRED of
that entry against the beginning of the line that `point' is on.  If
the PRED evaluates to true (or false if the optional NEGATE-P is
non-`nil'), then the FUNC for that entry is `eval'uated.  How
processing continues is determined by the return value for FUNC, and is
described below.  If PRED was false the next entry in the frame is
checked until all entries have been matched against the current line.
If no entry matches, `point' is moved forward one line and the frame is
reset to the first entry.

   PRED can be a string, a variable, a list or one of the following
symbols: `t', `begin', `end', or `every'.  If PRED is a string, or a
variable or list that `eval'uates to a string, it is interpreted as a
regular expression.  This regexp is matched against the current line,
from the beginning, using `looking-at'.  This match folds case if the
optional CASE-FOLD-SEARCH is non-`nil'.  If PRED is not a string, or
does not `eval'uate to a string, it is interpreted as a binary value
(`nil' or non-`nil').

   The four special symbol values for PRED are recognized:

`t'
     Always produces a true outcome.

`begin'
     Always executed before the frame is interpreted. This can be used
     to initialize some global variables for example.

`end'
     Always executed after frame interpreting is completed. This can be
     used to perform any necessary post-processing.

`every'
     Executes whenever the frame is reset, usually after the entire
     frame has been matched against the current line.

   Note that NEGATE-P and CASE-FOLD-SEARCH are ignored if PRED is one
of these special symbols.  Only the first occurrence of each symbol in
a frame is used; any duplicates are ignored.  Also note that for
performance reasons, the entries associated with these symbols are
removed from the frame during the main interpreting loop.

   Your FUNC can return certain values which control continued Regi
processing.  By default, if your FUNC returns `nil' (as it should be
careful to do explicitly), Regi will reset the frame to the first
entry, and advance `point' to the beginning of the next line.  If a
list is returned from your function, it can contain any combination of
the following elements:

the symbol `continue'
     This tells Regi to continue processing entries after a match,
     instead of reseting the frame and moving `point'. In this way,
     lines of text can have multiple matches, but you have to be
     careful to avoid entering infinite loops.

the symbol `abort'
     This tells Regi to terminate frame processing. However, any `end'
     entry is still processed.

the list `(frame . NEWFRAME)'
     This tells Regi to substitute NEWFRAME as the frame it is
     interpreting.  In other words, your FUNC can modify the Regi frame
     on the fly.  NEWFRAME can be a variable containing a frame, or it
     can be the frame in-lined.

the list `(step . STEP)'
     Tells Regi to move STEP number of lines forward as it continues
     processing. By default, Regi moves forward one line.  STEP can be
     zero or negative of course, but watch out for infinite loops.

   During execution of your FUNC, the following variables will be
temporarily bound to some useful information:

`curline'
     The current line in the buffer that Regi is `looking-at', as a
     string.

`curframe'
     The current frame being interpreted.

`curentry'
     The current frame entry being interpreted.