Pattern (regular expression) matching

Author(s): The Ciao Development Team.

This library provides facilities for matching strings and terms against patterns. Some prolog flags are available to control its behavior.

The flag case_insensitive controls whether to perform case-insensitive (on) or case-sensitive (off) match. The default value is off.

There is a syntax facility that allows using this regular expression matching in a similar way to unification. You can use =~ "regexp" as an argument of a predicate, and then that argument must match with the regexp. For example:

   pred ( =~ "ab*c", B) :- ...

is equivalent to

      pred (X,B) :- match_posix("ab*c",X,R), ...

Two additional flags control this matching. The first one is
@tt{format}. @cindex{format} Its values are @tt{shell}, @tt{posix},
@tt{list} and @tt{pred}.  Their effect is as if changing in the
example above the call to @pred{match_posix/3} by a call to,
respectively, @tt{match_shell/2}, @tt{match_posix/3},
@tt{match_struct/3}, and @tt{match_pred/3}.  The default value is
@tt{posix}.  The other prolog flag is @tt{exact}. @cindex{exact}
Its values are @tt{on} and @tt{off}. The @tt{off} value means
replacing in the example @tt{R} with @tt{[]}. If the value is
@tt{on}, then @tt{R} is a variable. The default value is @tt{on}.

Usage and interface

Library usage:
:- use_package(regexp). or :- module(...,...,[regexp]).
New operators defined:
=~/1 [200,fy].
Implicit imports:
- System library modules:
  regexp_code.
- Packages:
  prelude, initial, condcomp, assertions, assertions/assertions_basic.

Documentation on internals

PREDICATEmatch_shell/3

Usage:match_shell(Exp,IN,Rest)

Matches IN against Exp. Rest is the longest remainder of the string after the match. For example, match_shell("??*","foo.pl",Tail) succeeds, instantiating Tail to "o.pl".

The following properties should hold at call time:
(regexp_code:shell_regexp/1)Exp is a shell regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).
(basic_props:string/1)Rest is a string (a list of character codes).

PREDICATEmatch_shell/2

Usage:match_shell(Exp,IN)

Matches completely IN (no tail can remain unmatched) against Exp similarly to match_shell/3.

The following properties should hold at call time:
(regexp_code:shell_regexp/1)Exp is a shell regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).

PREDICATEmatch_posix/2

Usage:match_posix(Exp,IN)

Matches completely IN (no tail can remain unmatched) against Exp similarly to match_posix/3.

The following properties should hold at call time:
(regexp_code:shell_regexp/1)Exp is a shell regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).

PREDICATEmatch_posix/4

Usage:match_posix(Exp,In,Match,Rest)

The following properties should hold at call time:
(regexp_code:shell_regexp/1)Exp is a shell regular expression to match against.
(basic_props:string/1)In is a string (a list of character codes).
(basic_props:list/2)Match is a list of strings.
(basic_props:string/1)Rest is a string (a list of character codes).

PREDICATEmatch_posix_rest/3

Usage:match_posix_rest(Exp,IN,Rest)

Matches IN against Exp. Tail is the remainder of the string after the match. For example, match_posix("ab*c","abbbbcdf",Tail) succeeds, instantiating Tail to "df".

The following properties should hold at call time:
(regexp_code:posix_regexp/1)Exp is a posix regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).
(basic_props:string/1)Rest is a string (a list of character codes).

PREDICATEmatch_posix_matches/3

Usage:match_posix_matches(Exp,IN,Matches)

Matches completely IN against Exp. Exp can contain anchored expressions of the form \(regexp\). Matches will contain a list of the anchored expression which were matched on success. Note that since POSIX expressions are being read inside a string, backslashes will have to be doubled. For example,

?- match_posix_matches("\(aa|bb\)\(bb|aa\)", "bbaa", M).
M = ["bb","aa"] ? ;
no

?- match_posix_matches("\(aa|bb\)\(bb|aa\)", "aabb", M).
M = ["aa","bb"] ? ;
no

The following properties should hold at call time:
(regexp_code:shell_regexp/1)Exp is a shell regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).
(basic_props:list/2)Matches is a list of strings.

PREDICATEmatch_struct/4

Usage:match_struct(Exp,IN,Rest,Tail)

Matches IN against Exp. Tail is the remainder of the list of atoms IN after the match. For example, match_struct([a,*(b),c],[a,b,b,b,c,d,e],Tail) succeeds, instantiating Tail to [d,e].

Call and exit should be compatible with:
(regexp_code:struct_regexp/1)Exp is a struct regular expression to match against.
(basic_props:string/1)IN is a string (a list of character codes).
(basic_props:string/1)Rest is a string (a list of character codes).

PREDICATEmatch_pred/2

No further documentation available for this predicate.

PREDICATEreplace_first/4

Usage:replace_first(IN,Old,New,Resul)

Replace the first occurrence of the Old by New in IN and copy the result in Resul.

The following properties should hold at call time:
(basic_props:string/1)IN is a string (a list of character codes).
(regexp_code:posix_regexp/1)Old is a posix regular expression to match against.
(basic_props:string/1)New is a string (a list of character codes).
(basic_props:string/1)Resul is a string (a list of character codes).

PREDICATEreplace_all/4

Usage:replace_all(IN,Old,New,Resul)

Replace all occurrences of the Old by New in IN and copy the result in Resul.

The following properties should hold at call time:
(basic_props:string/1)IN is a string (a list of character codes).
(regexp_code:posix_regexp/1)Old is a posix regular expression to match against.
(basic_props:string/1)New is a string (a list of character codes).
(basic_props:string/1)Resul is a string (a list of character codes).