rex, split - regular expression search

SYNOPSIS

<rex $expr $data[ /]>                    <split $expr $data[ /]>
  or                                   or
<rex [options] $expr $data>          <split [options] $expr $data>
  ...                                  ...
</rex>                               </split>

DESCRIPTION
The rex function searches for each REX expression value of $expr in each value of $data. The split function acts the same way, except that it returns the non-matching data from $data (i.e. the SPLIT option below). The return type is varbyte if the $data is type varbyte or byte, otherwise it is varchar.

If given no other options, rex and split return a list of the matching (or non-matching) hits from $data. If any of the following options are given however, the statement is a looping block command, e.g. a close tag is expected, and $loop/$next are set as in SQL ($loop always starts at 0). Any statements inside the block are executed once per returned hit, with $ret being a loop variable accumulating hits. In addition, the variable $ret.off contains the integer byte offset into the current search buffer where the hit starts. The loop can be exited with BREAK or RETURN. The looping syntax was added in version 2.6.938200000 19990924; $ret.off in version 3.01.966500000 20000816.

Looping options are:

• ROW As in SQL, do not accumulate hits in $ret, and do not make it a loop variable; each new value erases the previous. ROW should be used in a looping rex/split when a large number of return values are expected but only need to be examined one at a time; this saves memory and time since all the hits do not have to be stored in memory. ROW should also be used when functions are called within the block, because otherwise $ret is a loop variable, hindering multi-value returns.

• SKIP=$n Skip the first $n hits when returning values. This does not affect the value of $loop.

• MAX=$n Return at most $n hits.

• SPLIT Instead of returning the hit data, return non-matching data, i.e. the parts of $data outside the hits. The REX expressions in effect become delimiters for the data returned. This is similar to the command-line rex option -v (except there are no delimiters as with command-line rex). This is the default for the split command.

• NONEMPTY Ignore empty (zero-length) return values. This is useful with SPLIT when empty values are not significant.

DIAGNOSTICS
rex returns a list of the matching hits from $data. split returns a list of the non-matching data. If looping, the corresponding byte offset into the current search item is returned in $ret.off as well.

• REX Expression Syntax
• REX Expression Repetition Operators
• REX Caveats and Commentary
• Some Useful REX Expressions