Named captures are automatically bound to corresponding named variables in the surrounding scope. For example,
"Hi John" =~ "hi (?<Name>[a-z]+)"/i, Name == "John".
textvalue may either be an atom or a list of codes.
Options can either be an atom or a list of options. If an atom, it's
split into a list of single character atoms which is used as the
Options value. This allows on to use
is, for example, instead of
[i,s]. Acceptable options are:
i- case-insensitive (default false)
s- let `.
match\n` (default false)
Captures is unified with a list of captured values, with the leftmost capture first, etc. Each captured value is a list of codes. For example,
?- regex('(a+)(b*)', , 'aaabbbbb', [A,B]). A = "aaa", B = "bbbbb".
Named captures are also supported. In that case, Captures must be
a list of pairs like
['A'=A,'B'=B]. Every named capture in the
pattern must have a corresponding key in Captures. (This is a
temporary restriction and will be removed later).
A brief word on argument order. Prolog convention prefers to place an Options argument as the final argument or as the last one before outputs. However, widely followed regular expression convention places options immediately after the pattern. I chose to follow the latter convention. This argument order benefits higher-order calls like maplist/3 which can do things like:
?- maplist(regex('(a+)(b+)', i), [ab, aab, abb], L). L = [["a", "b"], ["aa", "b"], ["a", "bb"]].