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 format. Its values are shell, posix, list and pred. Their effect is as if changing in the example above the call to match_posix/3 by a call to, respectively, match_shell/2, match_posix/3, match_struct/3, and match_pred/3. The default value is posix. The other prolog flag is exact. Its values are on and off. The off value means replacing in the example R with []. If the value is on, then R is a variable. The default value is 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).