MAN page from Mandrake Other ldap-devel-3.3-3.i386.rpm

regex

Section: C Library Functions (3)
Updated: local
Index

NAME

re_comp, re_exec, re_subs, re_modw, re_fail - regular expression handling

ORIGIN

Dept. of Computer Science
York University

SYNOPSIS

char *re_comp(pat)
char *pat;

re_exec(str)
char *str;

re_subs(src, dst)
char *src;
char *dst;

void re_fail(msg, op)
char *msg;
char op;

void re_modw(str)
char *str;

DESCRIPTION

These functions implemented(1)-stylepartial regular expressions and supporting facilities.

Re_compcompiles a pattern string into an internal form (a deterministic finite-stateautomaton) to be executed byre_execfor pattern matching.Re_compreturns 0 if the pattern is compiled successfully, otherwise it returns anerror message string. Ifre_compis called with a 0 or a null string, it returns without changing thecurrently compiled regular expression.

Re_compsupports the same limited set ofregular expressionsfound inedand Berkeleyregex(3)routines:

[1] char Matches itself, unless it is a special
character (meta-character): . \ [ ] * + ^ $

[2] . Matches any character.

[3] \ Matches the character following it, except
when followed by a digit 1 to 9, (, fB), < or >.(see [7], [8] and [9]) It is used as an escape character for all other meta-characters, and itself. When usedin a set ([4]), it is treated as an ordinarycharacter.

[4] [set] Matches one of the characters in the set.
If the first character in the set is ^,it matches a character NOT in the set. Ashorthand S-Eis used to specify a set ofcharacters S up to E,inclusive. The specialcharacters ] and - have no specialmeaning if they appear as the first charsin the set.

        examples:       match:        [a-z]           any lowercase alpha        [^]-]           any char except ] and -        [^A-Z]          any char except                         uppercase alpha        [a-zA-Z0-9]     any alphanumeric

[5] * Any regular expression form [1] to [4], followed by
closure char (*) matches zero or more matches ofthat form.

[6] + Same as [5], except it matches one or more.

[7] A regular expression in the form [1] to [10], enclosed
as $form$ matches what form matches. The enclosurecreates a set of tags, used for [8] and forpattern substitution inre_subs. The tagged forms are numberedstarting from 1.

[8] A \ followed by a digit 1 to 9 matches whatever a
previously tagged regular expression ([7]) matched.

[9] \< Matches the beginning of a word,
that is, an empty string followed by aletter, digit, or _ and not preceded bya letter, digit, or _ .
\> Matches the end of a word,
that is, an empty string precededby a letter, digit, or _ , and notfollowed by a letter, digit, or _ .

[10] A composite regular expression
xy where x and yare in the form of [1] to [10] matches the longestmatch of x followed by a match for y.

[11] ^ $ a regular expression starting with a ^ character
and/or ending with a $ character, restricts thepattern matching to the beginning of the line,and/or the end of line [anchors]. Elsewhere in thepattern, ^ and $ are treated as ordinary characters.

Re_execexecutes the internal form produced byre_compand searches the argument string for the regular expression describedby the internalform. Re_execreturns 1 if the last regular expression pattern is matched within the string,0 if no match is found. In case of an internal error (corrupted internalform), re_exec calls the user-suppliedre_failand returns 0.

The strings passed to bothre_compandre_execmay have trailing or embedded newline characters. The strings must be terminated by nulls.

Re_subsdoesed-stylepattern substitution, after a successful match is found byre_exec.The source string parameter tore_subsis copied to the destination string with the following interpretation;

[1] & Substitute the entire matched string in the destination.

[2] \n Substitute the substring matched by a tagged subpattern
numbered n, where n is between 1 to 9, inclusive.

[3] \char Treat the next character literally,
unless the character is a digit ([2]).

If the copy operation with the substitutions is successful,re_subsreturns 1.If the source string is corrupted, or the last call tore_execfails, it returns 0.

Re_modwis used to add new characters into an internal table tochange the re_exec's understanding of whata word should look like, when matching with \< and \>constructs. If the string parameter is 0 or null string,the table is reset back to the default, which contains A-Z a-z 0-9 _ .

Re_failis a user-supplied routine to handle internal errors.re_execcallsre_failwith an error message string, and the opcode character that caused the error.The defaultre_failroutine simply prints the message and the opcode character tostderrand invokesexit(2).

EXAMPLES

In the examples below, thenfaformdescribes the internal form after the pattern is compiled. For additionaldetails, refer to the sources.

foo*.*     nfaform:  CHR f CHR o CLO CHR o END CLO ANY END END     matches:  fo foo fooo foobar fobar foxx ...fo[ob]a[rz]     nfaform:  CHR f CHR o CCL 2 o b CHR a CCL 2 r z END     matches:  fobar fooar fobaz fooazfoo\\+     nfaform:  CHR f CHR o CHR o CHR \ CLO CHR \ END END     matches:  foo\ foo\\ foo\\\  ...\(foo\)[1-3]\1 (same as foo[1-3]foo, but takes less internal space)     nfaform:  BOT 1 CHR f CHR o CHR o EOT 1 CCL 3 1 2 3 REF 1 END     matches:  foo1foo foo2foo foo3foo\(fo.*\)-\1     nfaform:  BOT 1 CHR f CHR o CLO ANY END EOT 1 CHR - REF 1 END     matches:  foo-foo fo-fo fob-fob foobar-foobar ...

DIAGNOSTICS

Re_compreturns one of the following strings if an error occurs:

No previous regular expression,Empty closure,Illegal closure,Cyclical reference,Undetermined reference,Unmatched \(,Missing ],Null pattern inside \(\),Null pattern inside \<\>,Too many \(\) pairs,Unmatched \).

REFERENCES

Software tools                Kernighan & PlaugerSoftware tools in Pascal      Kernighan & PlaugerGrep sources [rsx-11 C dist]  David ConroyEd - text editor              Unix Programmer's ManualAdvanced editing on Unix      B. W. KernighanRegExp sources                Henry Spencer

HISTORY AND NOTES

These routines are derived from various implementationsfound in Software Toolsbooks, and David Conroy's grep. They are NOT derived from licensed/restricted software.For more interesting/academic/complicated implementations,see Henry Spencer's regexp routines (V8), or GNU Emacspatternmatching module.

There_compandre_execroutines performalmostas well as their licensed counterparts, sometimes better. In very few instances, theyare about 10% to 15% slower.

AUTHOR

Ozan S. Yigit (oz)
usenet: utzoo!yetti!oz
bitnet: oz@yusol || ozAATTyuyetti

BUGS

These routines are Public Domain. You can get themin source.
The internal storage for the nfa form is not checked foroverflows. Currently, it is 1024 bytes.
Others, no doubt.

This document was created byman2html,using the manual pages.