View source with raw comments or as raw
    1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker and Peter Ludemann
    4    E-mail:        jan@swi-prolog.org
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2017-2022, VU University Amsterdam
    7                              SWI-Prolog Solutions b.v.
    8    All rights reserved.
    9
   10    Redistribution and use in source and binary forms, with or without
   11    modification, are permitted provided that the following conditions
   12    are met:
   13
   14    1. Redistributions of source code must retain the above copyright
   15       notice, this list of conditions and the following disclaimer.
   16
   17    2. Redistributions in binary form must reproduce the above copyright
   18       notice, this list of conditions and the following disclaimer in
   19       the documentation and/or other materials provided with the
   20       distribution.
   21
   22    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   23    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   24    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   25    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   26    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   27    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   28    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   29    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   30    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   31    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   32    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   33    POSSIBILITY OF SUCH DAMAGE.
   34*/
   35
   36:- module(pcre,
   37          [ re_match/2,           % +Regex, +String
   38            re_match/3,           % +Regex, +String, +Options
   39            re_matchsub/3,        % +Regex, +String, -Subs
   40            re_matchsub/4,        % +Regex, +String, -Subs, +Options
   41            re_foldl/6,           % :Goal, +Regex, +String, ?V0, ?V, +Options
   42            re_split/3,           % +Pattern, +String, -Split:list
   43            re_split/4,           % +Pattern, +String, -Split:list, +Options
   44            re_replace/4,         % +Pattern, +With, +String, -NewString
   45            re_replace/5,         % +Pattern, +With, +String, -NewString, +Options
   46            re_compile/3,         % +Pattern, -Regex, +Options
   47            re_flush/0,
   48            re_config/1           % ?Config
   49          ]).   50:- autoload(library(apply), [maplist/2, maplist/3]).   51:- autoload(library(error), [must_be/2, existence_error/2]).   52:- autoload(library(dcg/basics), [eos/2, digit/3, digits/3]).   53:- autoload(library(lists), [append/3]).   54
   55:- use_foreign_library(foreign(pcre4pl)).   56
   57:- meta_predicate
   58    re_foldl(3, +, +, ?, ?, +).

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 comprehensive 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.

See also
- `man pcre2api` or https://www.pcre.org/current/doc/html/pcre2api.html for details of the PCRE2 syntax and options. */
   81:- predicate_options(re_match/3, 3,
   82                     [ start(integer), % Not part of pcre2 API
   83                       % These are in the same order as in pcre4pl.c, to make it easy to compare them
   84                       anchored(boolean),    % Also re_compile/3
   85                       utf_check(boolean),   % Also re_compile/3
   86                       endanchored(boolean), % Also re_compile/3
   87                       bol(boolean),
   88                       eol(boolean),
   89                       empty(boolean),
   90                       empty_atstart(boolean),
   91                       partial_soft(bool),
   92                       partial_hard(bool),
   93                       % dfa_restart(bool),  % TODO: if pcre2_dfa_match() is supported
   94                       % dfa_shortest(bool), % TODO: if pcre2_dfa_match() is supported
   95                       jit(boolean),
   96                       copy_matched_subject(boolean)
   97                     ]).   98:- predicate_options(re_compile/3, 3,
   99                     [ capture_type(oneof([atom,string,range])), % Not part of pcre2 API
  100                       % These are in the same order as in pcre4pl.c, to make it easy to compare them
  101                       anchored(boolean),    % Also re_match/3
  102                       utf_check(boolean),   % Also re_match/3
  103                       endanchored(boolean), % Also re_match/3
  104                       allow_empty_class(boolean),
  105                       alt_bsux(boolean),
  106                       auto_callout(boolean),
  107                       caseless(boolean),
  108                       dollar_endonly(boolean),
  109                       dotall(boolean),
  110                       dupnames(boolean),
  111                       extended(boolean),
  112                       firstline(boolean),
  113                       match_unset_backref(boolean),
  114                       multiline(boolean),
  115                       never_ucp(boolean),
  116                       never_utf(boolean),
  117                       auto_capture(boolean),
  118                       no_auto_capture(boolean), % backwards compatibility
  119                       auto_possess(boolean),
  120                       dotstar_anchor(boolean),
  121                       start_optimize(boolean),
  122                       ucp(boolean),
  123                       greedy(boolean),
  124                       ungreedy(boolean), % Backwards compatibility
  125                       utf(boolean),
  126                       never_backslash_c(boolean),
  127                       alt_circumflex(boolean),
  128                       alt_verbnames(boolean),
  129                       use_offset_limit(boolean),
  130                       extended_more(boolean),
  131                       literal(boolean),
  132                       match_invalid_utf(boolean),
  133                       jit_complete(boolean),
  134                       jit_partial_soft(boolean),
  135                       jit_partial_hard(boolean),
  136                       jit_invalid_utf(boolean),
  137                       bsr(oneof([anycrlf,unicode])),
  138                       bsr2(oneof([anycrlf,unicode])),
  139                       compat(oneof([])), % Obsolete
  140                       newline(oneof([any,anycrlf,cr,lf,crlf,nul])),
  141                       newline2(oneof([any,anycrlf,cr,lf,crlf,nul]))
  142                     ]).  143:- predicate_options(re_matchsub/4, 4,
  144                     [ pass_to(re_match/3, 3)
  145                     ]).  146:- predicate_options(re_foldl/6, 6,
  147                     [ pass_to(re_match/3, 3)
  148                     ]).  149:- predicate_options(re_split/4, 4,
  150                     [ pass_to(re_match/3, 3)
  151                     ]).  152:- predicate_options(re_replace/5, 5,
  153                     [ pass_to(re_match/3, 3)
  154                     ]).
 re_match(+Regex, +String) is semidet
 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)).

  231re_match(Regex, String) :-
  232    re_match(Regex, String, []).
  233re_match(Regex, String, Options) :-
  234    re_compiled(Regex, Compiled, Options),
  235    re_match_(Compiled, String, Options).
 re_matchsub(+Regex, +String, -Sub:dict) is semidet
 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.
  268re_matchsub(Regex, String, Subs) :-
  269    re_matchsub(Regex, String, Subs, []).
  270
  271re_matchsub(Regex, String, Subs, Options) :-
  272    re_compiled(Regex, Compiled, Options),
  273    re_matchsub_(Compiled, String, Pairs, Options),
  274    dict_pairs(Subs, re_match, Pairs).
 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"].
  327re_foldl(Goal, Regex, String, V0, V, Options) :-
  328    re_compiled(Regex, Compiled, Options),
  329    re_foldl_(Compiled, String, Goal, V0, V, Options).
  330
  331:- public re_call_folder/4. % prevent code obfusication name mangling
  332:- meta_predicate re_call_folder(2, +, ?, ?).  333
  334%   re_call_folder(:Goal, +Pairs, ?V0, ?V1).
  335%   Used by re_foldl_/6 to call Goal with a dict.
  336%     DO NOT use "%!" comment - that would add it to the docs
  337re_call_folder(Goal, Pairs, V0, V1) :-
  338    dict_pairs(Dict, re_match, Pairs),
  339    call(Goal, Dict, V0, V1).
 re_split(+Pattern, +String, -Splits:list) is det
 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).
  365re_split(Pattern, String, Splits) :-
  366    re_split(Pattern, String, Splits, []).
  367re_split(Pattern, String, Splits, Options) :-
  368    split_range_regex(Pattern, Compiled, Type, Options),
  369    State = state(String, 0, Type),
  370    re_foldl(split(State), Compiled, String, Splits, [Last], Options),
  371    arg(2, State, LastSkipStart),
  372    typed_sub(Type, String, LastSkipStart, _, 0, Last).
  373
  374split_range_regex(Pattern/Flags, Compiled, Type, Options) =>
  375    split_range_regex(Pattern, Flags, Compiled, Type, Options).
  376split_range_regex(Pattern, Compiled, Type, Options) =>
  377    split_range_regex(Pattern, '', Compiled, Type, Options).
  378
  379split_range_regex(Pattern, Flags, Compiled, Type, Options) =>
  380    regex_capture_type_flag_chars(Flags, Chars, Options),
  381    split_flags(Chars, Chars1, Type),
  382    atom_chars(RFlags, [r|Chars1]),
  383    re_flags_options(RFlags, ROptions),
  384    append(ROptions, Options, Options2),
  385    re_compiled(Pattern/RFlags, Compiled, Options2).
  386
  387split_flags([], [], Type) :-
  388    default(Type, string).
  389split_flags([H|T0], T, Type) :-
  390    split_type(H, Type),
  391    !,
  392    split_flags(T0, T, Type).
  393split_flags([H|T0], [H|T], Type) :-
  394    split_flags(T0, T, Type).
  395
  396split_type(a, atom).
  397split_type(s, string).
  398split_type(n, name).
  399
  400split(State, Dict, [Skipped,Sep|T], T) :-
  401    matched(State, Dict.0, Sep),
  402    skipped(State, Dict.0, Skipped).
  403
  404matched(state(String, _, Type), Start-Len, Matched) :-
  405    typed_sub(Type, String, Start, Len, _, Matched).
  406
  407skipped(State, Start-Len, Skipped) :-
  408    State = state(String, Here, Type),
  409    SkipLen is Start-Here,
  410    typed_sub(Type, String, Here, SkipLen, _, Skipped),
  411    NextSkipStart is Start+Len,
  412    nb_setarg(2, State, NextSkipStart).
  413
  414typed_sub(string, Haystack, B, L, A, String) :-
  415    sub_string(Haystack, B, L, A, String).
  416typed_sub(atom, Haystack, B, L, A, String) :-
  417    sub_atom(Haystack, B, L, A, String).
  418typed_sub(name, Haystack, B, L, A, Value) :-
  419    sub_string(Haystack, B, L, A, String),
  420    (   number_string(Number, String)
  421    ->  Value = Number
  422    ;   atom_string(Value, String)
  423    ).
 re_replace(+Pattern, +With, +String, -NewString) is det
 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.

  467re_replace(Pattern, With, String, NewString) :-
  468    re_replace(Pattern, With, String, NewString, []).
  469
  470re_replace(Pattern, With, String, NewString, Options) :-
  471    replace_range_regex(Pattern, Compiled, All, Type, Options),
  472    compile_replacement(With, RCompiled),
  473    State = state(String, 0, Type),
  474    (   All == all
  475    ->  re_foldl(replace(State, RCompiled), Compiled, String, Parts, [Last], [])
  476    ;   (   re_matchsub(Compiled, String, Match, [])
  477        ->  replace(State, RCompiled, Match, Parts, [Last])
  478        ;   Repl = false
  479        )
  480    ),
  481    (   Repl == false
  482    ->  parts_to_output(Type, [String], NewString)
  483    ;   arg(2, State, LastSkipStart),
  484        sub_string(String, LastSkipStart, _, 0, Last),
  485        parts_to_output(Type, Parts, NewString)
  486    ).
  487
  488regex_capture_type_flag_chars(Flags, Chars, Options) :-
  489    atom_chars(Flags, Chars0),
  490    % For replace or split, the capture_type must be range, so if a
  491    % different result is desired, it is specified in the flags. The
  492    % following code converts an Options capture_type to a flag
  493    % character and appends it to the Flags.
  494    (   memberchk(capture_type(T), Options),
  495        type_flag(TFlag, T)
  496    ->  % No need to do delete(Options,capture_type(_),Options2)
  497        % because Flags take precedence and first occurence in Options
  498        % takes precedence.
  499        append(Chars0, [TFlag], Chars)
  500    ;   Chars = Chars0
  501    ).
 replace_range_regex(+Pattern, -Compiled, -All, -Type, +Options) is det
  504replace_range_regex(Pattern/Flags, Compiled, All, Type, Options) =>
  505    replace_range_regex(Pattern, Flags, Compiled, All, Type, Options).
  506replace_range_regex(Pattern, Compiled, All, Type, Options) =>
  507    replace_range_regex(Pattern, '', Compiled, All, Type, Options).
  508
  509replace_range_regex(Pattern, Flags, Compiled, All, Type, Options) =>
  510    regex_capture_type_flag_chars(Flags, Chars, Options),
  511    replace_flags(Chars, Chars1, All, Type),
  512    atom_chars(RFlags, [r|Chars1]),
  513    re_flags_options(RFlags, ROptions),
  514    append(ROptions, Options, Options2),
  515    re_compiled(Pattern, Compiled, Options2).
  516
  517replace_flags([], [], All, Type) :-
  518    default(All, first),
  519    default(Type, string).
  520replace_flags([H|T0], T, All, Type) :-
  521    (   all_flag(H, All)
  522    ->  true
  523    ;   type_flag(H, Type)
  524    ),
  525    !,
  526    replace_flags(T0, T, All, Type).
  527replace_flags([H|T0], [H|T], All, Type) :-
  528    replace_flags(T0, T, All, Type).
  529
  530all_flag(g, all).
  531
  532type_flag(a, atom).
  533type_flag(s, string).
 default(?Val, +Default) is det
If Val isn't instantiated, instantiate it to Default. If Val is already instantiated, succeed. Equivalent to: default( Val, Default), var(Val) => Val = Default. default(_Val, _Default) => true.
  541default(Val, Val) :- !.
  542default(_, _).
  543
  544replace(State, With, Dict, [Skipped|Parts], T) :-
  545    State = state(String, _, _Type),
  546    copy_term(With, r(PartsR, Skel)),
  547    maplist(dict_pair_lookup(Dict), Skel),
  548    range_strings(PartsR, String, Parts, T),
  549    skipped(State, Dict.0, Skipped).
  550
  551% dict_pair_lookup(d{a:1}, a-K) results in K=1.
  552dict_pair_lookup(Dict, Key-Dict.Key).
  553
  554range_strings([], _, T, T).
  555range_strings([Start-Len|T0], String, [S|T1], T) :-
  556    !,
  557    sub_string(String, Start, Len, _, S),
  558    range_strings(T0, String, T1, T).
  559range_strings([S|T0], String, [S|T1], T) :-
  560    range_strings(T0, String, T1, T).
  561
  562parts_to_output(string, Parts, String) :-
  563    atomics_to_string(Parts, String).
  564parts_to_output(atom, Parts, String) :-
  565    atomic_list_concat(Parts, String).
 compile_replacement(+With, -Compiled)
Compile the replacement specification into a specification that can be processed quickly. The compiled expressions are cached and may be reclaimed using re_flush/0 (which also removes compiled Regex from re_compile/3).

This "compilation" has nothing to do with PCRE pattern compilation; it's used by re_replace/5 to proces the With argument.

  577:- table compile_replacement/2 as shared.  578
  579compile_replacement(With, r(Parts, Extract)) :-
  580    string_codes(With, Codes),
  581    phrase(replacement_parts(Parts, Pairs), Codes),
  582    % Pairs is LookupKey-Slot pairs, where a LookupKey might be
  583    % duplicated (Slot is a shared variable within Parts).
  584    Extract = Pairs.
  585
  586replacement_parts(Parts, Extract) -->
  587    string_escape(HCodes),
  588    (   ("\\" ; "$"),
  589        capture_name(Name)
  590    ->  !,
  591        { add_part(HCodes, Parts, T0),
  592          T0 = [Repl|T1],
  593          Extract = [Name-Repl|Extract1]
  594        },
  595        replacement_parts(T1, Extract1)
  596    ;   eos
  597    ->  !,
  598        { add_part(HCodes, Parts, []),
  599          Extract = []
  600        }
  601    ).
  602
  603add_part([], Parts, Parts) :-
  604    !.
  605add_part(Codes, [H|T], T) :-
  606    string_codes(H, Codes).
 string_escape(-Codes)// is nondet
Similar to dcg_basics:string(Codes) but also escapes "$" and "/"
  610string_escape([]) -->
  611    [].
  612string_escape([0'$|T]) -->
  613    "$$", !,
  614    string_escape(T).
  615string_escape([0'\\|T]) -->
  616    "\\\\", !,
  617    string_escape(T).
  618string_escape([H|T]) -->
  619    [H],
  620    string_escape(T).
  621
  622capture_name(Name) -->
  623    "{",
  624    (   digit(D0)
  625    ->  digits(DL),
  626        "}",
  627        { number_codes(Name, [D0|DL]) }
  628    ;   letter(A0),
  629        alnums(AL),
  630        "}",
  631        { atom_codes(Name, [A0|AL]) }
  632    ).
  633capture_name(Name) -->
  634    digit(D0),
  635    !,
  636    digits(DL),
  637    { number_codes(Name, [D0|DL]) }.
  638capture_name(Name) -->
  639    letter(A0),
  640    !,
  641    alnums(AL),
  642    { atom_codes(Name, [A0|AL]) }.
  643
  644letter(L) -->
  645    [L],
  646    { between(0'a,0'z,L)
  647    ; between(0'A,0'Z,L)
  648    ; L == 0'_
  649    }, !.
  650
  651alnums([H|T]) -->
  652    alnum(H),
  653    !,
  654    alnums(T).
  655alnums([]) -->
  656    "".
  657
  658alnum(L) -->
  659    [L],
  660    { between(0'a,0'z,L)
  661    ; between(0'A,0'Z,L)
  662    ; between(0'0,0'9,L)
  663    ; L == 0'_
  664    }, !.
 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.




 re_compiled(+Spec, --Regex, +Options) is det
Create a compiled regex from a specification. Cached compiled
regular expressions can be reclaimed using re_flush/0 (which also
removes "compiled" With arguments from re_replace/4 and
re_replace/5).


  805:- table re_compiled_/4 as shared.  806
  807re_compiled(RegexIn, Regex, Options) :-
  808    (   blob(RegexIn, regex)
  809    ->  Regex = RegexIn
  810    ;   RegexIn = Text/Flags
  811    ->  re_compiled_(Text, Flags, Regex, Options)
  812    ;   re_compiled_(RegexIn, '', Regex, Options)
  813    ).
  814
  815re_compiled_(Text, Flags, Regex, Options) =>
  816    must_be(text, Text),
  817    must_be(atom, Flags),
  818    re_flags_options(Flags, Options0),
  819    append(Options0, Options, Options2),
  820    re_compile(Text, Regex, Options2).
  821
  822re_flags_options(Flags, Options) :-
  823    atom_chars(Flags, Chars),
  824    maplist(re_flag_option, Chars, Options).
  825
  826re_flag_option(Flag, Option) :-
  827    re_flag_option_(Flag, Option),
  828    !.
  829re_flag_option(Flag, _) :-
  830    existence_error(re_flag, Flag).
  831
  832re_flag_option_(i, caseless(true)).
  833re_flag_option_(m, multiline(true)).
  834re_flag_option_(x, extended(true)).
  835re_flag_option_(s, dotall(true)).
  836re_flag_option_(a, capture_type(atom)).
  837re_flag_option_(r, capture_type(range)).
  838re_flag_option_(t, capture_type(term)).



 re_flush
Clean pattern and replacement caches.




To be done
- Flush automatically if the cache becomes too large.







  846re_flush :-
  847    abolish_module_tables(pcre).



 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.





  921%   @see `man pcre2api` for details
  922
  923re_config(Term), var(Term) =>
  924    re_config_choice(Term),
  925    % This code depends on re_config_/1 failing if it's given an invalid
  926    % Term (e.g., re_config_(jittarget(_)) fails if jit(false)). If
  927    % re_config_/1 is changed to throw an error, then the following call
  928    % needs to be inside catch/3.
  929    re_config_(Term).
  930re_config(Term) =>
  931    re_config_(Term)