SWI-Prolog 9.1.21
All Application Manual Name SummaryHelp

PublicShow sourcepcre.pl -- Perl compatible regular expression matching for SWI-Prolog

This module provides an interface to the PCRE2 (Perl Compatible Regular Expression) library. This Prolog interface provides an almost complete wrapper around PCRE2 (the successor to PCRE) with as much backward compatibility to PCRE as possible, because the original implementation was for PCRE (also known as PCRE1).

Regular expressions are created from a pattern and options and represented as a SWI-Prolog blob. This implies they are subject to (atom) garbage collection. Compiled regular expressions can safely be used in multiple threads. Most predicates accept both an explicitly compiled regular expression, a pattern, or a term Pattern/Flags. The semantics of the pattern can be additionally modified by options. In the latter two cases a regular expression blob is created and stored in a cache. The cache can be cleared using re_flush/0.

Most of the predicates in this library take both a regular expression represented as a string with optional flags, e.g., 'aap'/i or a compiled regular expression. If a string (+flags) alternative is used, the library maintains a cache of compiled regular expressions. See also re_flush/0. The library can be asked to rewrite the re_match/2 and re_match/3 goals to use inlined compiled regular expression objects using

:- set_prolog_flag(re_compile, true).

This has some consequences:

See also
- `man pcre2api` or https://www.pcre.org/current/doc/html/pcre2api.html for details of the PCRE2 syntax and options.
Source re_match(+Regex, +String) is semidet
Source re_match(+Regex, +String, +Options) is semidet
Succeeds if String matches Regex. For example: 
?- re_match("^needle"/i, "Needle in a haystack").
true.

Defined Options are given below. For details, see the PCRE documentation. If an option is repeated, the first value is used and subsequent values are ignored. Unrecognized options are ignored. Unless otherwise specified, boolean options default to false.

If Regex is a text pattern (optionally with flags), then any of the Options for re_compile/3 can be used, in addition to the Options listed below. If Regex is the result of re_compile/3, then only the following execution-time Options are recognized and any others are ignored. Some options may not exist on your system, depending on the PCRE2 version and how it was built - these unsupported options are silently ignored.

Arguments:
Regex- is the output of re_compile/3, a pattern or a term Pattern/Flags, where Pattern is an atom or string. The defined flags and their related option for re_compile/3 are below.
  • x: extended(true)
  • i: caseless(true)
  • m: multiline(true)
  • s: dotall(true)
  • a: capture_type(atom)
  • r: capture_type(range)
  • t: capture_type(term)

If Regex is the output of re_compile/3, any compile-time options in Options or Flags are ignored and only match-time options are used.

The options that are derived from flags take precedence over the options in the Options list. In the case of conflicting flags, the first one is used (e.g., ra results in capture_type(range)).

Source re_matchsub(+Regex, +String, -Sub:dict) is semidet
Source re_matchsub(+Regex, +String, -Sub:dict, +Options) is semidet
Match String against Regex. On success, Sub is a dict containing integer keys for the numbered capture group and atom keys for the named capture groups. The entire match string has the key 0. The associated value is determined by the capture_type(Type) option passed to re_compile/3, or by flags if Regex is of the form Pattern/Flags; and may be specified at the level of individual captures using a naming convention for the caption name. See re_compile/3 for details.

The example below exploits the typed groups to parse a date specification:

?- re_matchsub("(?<date> (?<year_I>(?:\\d\\d)?\\d\\d) -
                (?<month_I>\\d\\d) - (?<day_I>\\d\\d) )"/x,
               "2017-04-20", Sub, []).
Sub = re_match{0:"2017-04-20", date:"2017-04-20",
               day:20, month:4, year:2017}.
Arguments:
Both- compilation and execution options are processed. See re_compile/3 and re_match/3 for the set of options. In addition, some compilation options may passed as /Flags to Regex - see re_match/3 for the list of flags.
Regex- See re_match/2 for a description of this argument.
Source re_foldl(:Goal, +Regex, +String, ?V0, ?V, +Options) is semidet
Fold all matches of Regex on String. Each match is represented by a dict as specified for re_matchsub/4. V0 and V are related using a sequence of invocations of Goal as illustrated below. 
call(Goal, Dict1, V0, V1),
call(Goal, Dict2, V1, V2),
...
call(Goal, Dictn, Vn, V).

This predicate is used to implement re_split/4 and re_replace/4. For example, we can count all matches of a Regex on String using this code:

re_match_count(Regex, String, Count) :-
    re_foldl(increment, Regex, String, 0, Count, []).

increment(_Match, V0, V1) :-
    V1 is V0+1.

After which we can query

?- re_match_count("a", "aap", X).
X = 2.

Here is an example Goal for extracting all the matches with their offsets within the string:

range_match(Dict, StringIndex-[MatchStart-Substring|List], StringIndex-List) :-
    Dict.(StringIndex.index) = MatchStart-MatchLen,
    sub_string(StringIndex.string, MatchStart, MatchLen, _, Substring).

And can be used with this query (note the capture_type(range) option, which is needed by range_match/3, and greedy(false) to invert the meaning of *?):

?- String = "{START} Mary {END} had a {START} little lamb {END}",
   re_foldl(range_match,
            "{START} *?(?<piece>.*) *?{END}",
            String, _{string:String,index:piece}-Matches, _-[],
            [capture_type(range),greedy(false)]).
Matches = [8-"Mary", 33-"little lamb"].
Source re_split(+Pattern, +String, -Splits:list) is det
Source re_split(+Pattern, +String, -Splits:list, +Options) is det
Split String using the regular expression Pattern. Splits is a list of strings holding alternating matches of Pattern and skipped parts of the String, starting with a skipped part. The Splits lists ends with a string of the content of String after the last match. If Pattern does not appear in String, Splits is a list holding a copy of String. This implies the number of elements in Splits is always odd. For example: 
?- re_split("a+", "abaac", Splits, []).
Splits = ["","a","b","aa","c"].
?- re_split(":\\s*"/n, "Age: 33", Splits, []).
Splits = ['Age', ': ', 33].
Arguments:
Pattern- is the pattern text, optionally follows by /Flags. Similar to re_matchsub/4, the final output type can be controlled by a flag a (atom), s (string, default) or n (number if possible, atom otherwise).
Source re_replace(+Pattern, +With, +String, -NewString) is det
Source re_replace(+Pattern, +With, +String, -NewString, +Options) is det
Replace matches of the regular expression Pattern in String with With (possibly containing references to captured substrings).

Throws an error if With uses a name that doesn't exist in the Pattern.

Arguments:
Pattern- is the pattern text, optionally followed by /Flags. Flags may include g, replacing all occurences of Pattern. In addition, similar to re_matchsub/4, the final output type can be controlled by a flag a (atom) or s (string, default). The output type can also be specified by the capture_type option. Capture type suffixes can modify behavior; for example, the following will change an ISO 8601 format date (YYYY-MM-DD) to American style (m/d/y), and also remove leading zeros by using the _I suffix: 
re_replace("(?<date> (?<year_I>(?:\\d\\d)?\\d\\d) -
            (?<month_I>\\d\\d) - (?<day_I>\\d\\d) )"/x,
           "$month-$day-$year",
           ISODate, AmericanDate)`
With- is the replacement text. It may reference captured substrings using \N or $Name. Both N and Name may be written as {N} and {Name} to avoid ambiguities. If a substring is named, it cannot be referenced by its number. The single chracters $ and \ can be escaped by doubling (e.g., re_replace(".","$$","abc",Replaced) results in Replaced="$bc"). (Because \ is an escape character inside strings, you need to write "\\\\" to get a single backslash.)
Options- See re_match/3 for the set of options.

The options that are derived from flags take precedence over the options in the Options list. In the case of conflicting flags, the first one is used (e.g., as results in capture_type(string)). If a capture_type is meaningless (range or term), it is ignored.

Source re_compile(+Pattern, -Regex, +Options) is det
Compiles Pattern to a Regex blob of type regex (see blob/2). Defined Options are given below. Please consult the PCRE2 API documentation for details. If an option is repeated, the first value is used and subsequent values are ignored. Unrecognized options are ignored. Unless otherwise specified, boolean options default to false. Some options may not exist on your system, depending on the PCRE2 version and how it was built - these unsupported options are silently ignored.

The various matching predicates can take either a Regex blob or a string pattern; if they are given a string pattern, they call re_compile/3 and cache the result; so, there is little reason to use re_compile/3 directly.

In addition to the options above that directly map to PCRE flags the following options are processed:

The capture_type specifies the default for this pattern. The interface supports a different type for each named group using the syntax `(?<name_T>...)`, where T is one of S (string), A (atom), I (integer), F (float), N (number), T (term) and R (range). In the current implementation I, F and N are synonyms for T. Future versions may act different if the parsed value is not of the requested numeric type.

Note that re_compile/3 does not support the Pattern/Flags form that is supported by re_match/3, re_replace/4, etc.; the Pattern must be text and all compile options specified in Options.

Source re_flush
Clean pattern and replacement caches.
To be done
- Flush automatically if the cache becomes too large.
Source re_config(?Term)
Extract configuration information from the pcre library. Term is of the form Name(Value). Name is derived from the PCRE_CONFIG_* constant after removing PCRE_CONFIG_ and mapping the name to lower case, e.g. utf8, unicode_properties, etc. Value is a Prolog boolean, integer, or atom. For boolean (1 or 0) values, true or false is returned.

re_config/1 will backtrack through all the possible configuration values if its argument is a variable. If an unknown option is specified, re_config/1 fails.

Non-compatible changes between PCRE1 and PCRE2 because numeric values changed: bsr and newline have been replaced by bsr2 and newline2:

Term values are as follows. Some values might not exist, depending on the version of PCRE2 and the options it was built with.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source re_matchsub(+Regex, +String, -Sub:dict) is semidet
Source re_matchsub(+Regex, +String, -Sub:dict, +Options) is semidet
Match String against Regex. On success, Sub is a dict containing integer keys for the numbered capture group and atom keys for the named capture groups. The entire match string has the key 0. The associated value is determined by the capture_type(Type) option passed to re_compile/3, or by flags if Regex is of the form Pattern/Flags; and may be specified at the level of individual captures using a naming convention for the caption name. See re_compile/3 for details.

The example below exploits the typed groups to parse a date specification:

?- re_matchsub("(?<date> (?<year_I>(?:\\d\\d)?\\d\\d) -
                (?<month_I>\\d\\d) - (?<day_I>\\d\\d) )"/x,
               "2017-04-20", Sub, []).
Sub = re_match{0:"2017-04-20", date:"2017-04-20",
               day:20, month:4, year:2017}.
Arguments:
Both- compilation and execution options are processed. See re_compile/3 and re_match/3 for the set of options. In addition, some compilation options may passed as /Flags to Regex - see re_match/3 for the list of flags.
Regex- See re_match/2 for a description of this argument.
Source re_split(+Pattern, +String, -Splits:list) is det
Source re_split(+Pattern, +String, -Splits:list, +Options) is det
Split String using the regular expression Pattern. Splits is a list of strings holding alternating matches of Pattern and skipped parts of the String, starting with a skipped part. The Splits lists ends with a string of the content of String after the last match. If Pattern does not appear in String, Splits is a list holding a copy of String. This implies the number of elements in Splits is always odd. For example: 
?- re_split("a+", "abaac", Splits, []).
Splits = ["","a","b","aa","c"].
?- re_split(":\\s*"/n, "Age: 33", Splits, []).
Splits = ['Age', ': ', 33].
Arguments:
Pattern- is the pattern text, optionally follows by /Flags. Similar to re_matchsub/4, the final output type can be controlled by a flag a (atom), s (string, default) or n (number if possible, atom otherwise).
Source re_replace(+Pattern, +With, +String, -NewString) is det
Source re_replace(+Pattern, +With, +String, -NewString, +Options) is det
Replace matches of the regular expression Pattern in String with With (possibly containing references to captured substrings).

Throws an error if With uses a name that doesn't exist in the Pattern.

Arguments:
Pattern- is the pattern text, optionally followed by /Flags. Flags may include g, replacing all occurences of Pattern. In addition, similar to re_matchsub/4, the final output type can be controlled by a flag a (atom) or s (string, default). The output type can also be specified by the capture_type option. Capture type suffixes can modify behavior; for example, the following will change an ISO 8601 format date (YYYY-MM-DD) to American style (m/d/y), and also remove leading zeros by using the _I suffix: 
re_replace("(?<date> (?<year_I>(?:\\d\\d)?\\d\\d) -
            (?<month_I>\\d\\d) - (?<day_I>\\d\\d) )"/x,
           "$month-$day-$year",
           ISODate, AmericanDate)`
With- is the replacement text. It may reference captured substrings using \N or $Name. Both N and Name may be written as {N} and {Name} to avoid ambiguities. If a substring is named, it cannot be referenced by its number. The single chracters $ and \ can be escaped by doubling (e.g., re_replace(".","$$","abc",Replaced) results in Replaced="$bc"). (Because \ is an escape character inside strings, you need to write "\\\\" to get a single backslash.)
Options- See re_match/3 for the set of options.

The options that are derived from flags take precedence over the options in the Options list. In the case of conflicting flags, the first one is used (e.g., as results in capture_type(string)). If a capture_type is meaningless (range or term), it is ignored.

Source re_match(+Regex, +String) is semidet
Source re_match(+Regex, +String, +Options) is semidet
Succeeds if String matches Regex. For example: 
?- re_match("^needle"/i, "Needle in a haystack").
true.

Defined Options are given below. For details, see the PCRE documentation. If an option is repeated, the first value is used and subsequent values are ignored. Unrecognized options are ignored. Unless otherwise specified, boolean options default to false.

If Regex is a text pattern (optionally with flags), then any of the Options for re_compile/3 can be used, in addition to the Options listed below. If Regex is the result of re_compile/3, then only the following execution-time Options are recognized and any others are ignored. Some options may not exist on your system, depending on the PCRE2 version and how it was built - these unsupported options are silently ignored.

Arguments:
Regex- is the output of re_compile/3, a pattern or a term Pattern/Flags, where Pattern is an atom or string. The defined flags and their related option for re_compile/3 are below.
  • x: extended(true)
  • i: caseless(true)
  • m: multiline(true)
  • s: dotall(true)
  • a: capture_type(atom)
  • r: capture_type(range)
  • t: capture_type(term)

If Regex is the output of re_compile/3, any compile-time options in Options or Flags are ignored and only match-time options are used.

The options that are derived from flags take precedence over the options in the Options list. In the case of conflicting flags, the first one is used (e.g., ra results in capture_type(range)).