Match a pattern to a subject and return the portion(s) that matched in an Alternative, or empty if no match.

Since: 2.0.0

matchOpt mempty = match

Since: 2.0.0

Does the pattern match the subject at least once?

matchesOpt mempty = matches

Match a pattern to a subject and return some non-empty list(s) of captures in an Alternative, or empty if no match. The non-empty list constructor :| serves as a cue to differentiate the 0th capture from the others:

let parseDate = captures "(\\d{4})-(\\d{2})-(\\d{2})"
in case parseDate "submitted 2020-10-20" of
    Just (date :| [y, m, d]) -> ...
    Nothing                  -> putStrLn "didn't match"

Since: 2.0.0

capturesOpt mempty = captures

Since: 2.0.0

Perform at most one substitution. See the docs for the special syntax of replacement.

>>> sub "\\b(\\w+) calling the (\\w+)\\b" "$2 calling the $1" "the pot calling the kettle black"
"the kettle calling the pot black"

Perform substitutions globally.

>>> gsub "a" "o" "apples and bananas"
"opples ond bononos"

subOpt mempty = sub
subOpt SubGlobal = gsub

Given a pattern, produce a traversal (0 or more targets) that focuses from a subject to the non-overlapping portions of it that match.

Equivalent to _captures patt . ix 0, but more efficient.

_matchOpt mempty = _match

Given a pattern, produce a traversal (0 or more targets) that focuses from a subject to each non-empty list of captures that pattern matches.

Substitution works in the following way: If a capture is set such that the new Text is not equal to the old one, a substitution occurs, otherwise it doesn't. This matters in cases where a capture encloses another capture—notably, all parenthesized captures are enclosed by the 0th.

>>> threeAndMiddle = _captures ". (.) ."
>>> "A A A" & threeAndMiddle .~ "A A A" :| ["B"]
"A B A"
>>> "A A A" & threeAndMiddle .~ "A B A" :| ["A"]
"A B A"

Changing multiple overlapping captures won't do what you want and is unsupported.

Changing an unset capture is unsupported because the PCRE2 match API does not give location info about it. Currently we ignore all such attempts. (Native substitution functions like sub do not have this limitation. See also SubUnknownUnset and SubUnsetEmpty.)

If the list becomes longer for some reason, the extra elements are ignored. If it's shortened, the absent elements are considered to be unchanged.

It's recommended that the list be modified capture-wise, using ix.

let madlibs = _captures "(\\w+) my (\\w+)"

print $ "Well bust my buttons!" &~ do
    zoom madlibs $ do
        ix 1 . _head .= 'd'
        ix 2 %= Text.reverse
    _last .= '?'

-- "Well dust my snottub?"

_capturesOpt mempty = _captures

As an expression

regex :: (Alternative f) => String -> Text -> f (Captures info)

if there are parenthesized captures, or

regex :: (Alternative f) => String -> Text -> f Text

if there are none. In other words, if there is more than the 0th capture, this behaves like captures (except returning an opaque Captures instead of a NonEmpty list), otherwise it behaves like match.

To retrieve an individual capture from a Captures, use capture.

case [regex|(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})|] "submitted 2020-10-20" of
    Just cs ->
        let date = capture @0 cs
            year = read @Int $ Text.unpack $ capture @"y" cs
            ...

forM_ @Maybe ([regex|\s+$|] line) $ \spaces ->
    printf "line has trailing spaces (%d characters)\n" (Text.length spaces)

As a pattern

This matches when the regex first matches. Any named captures are bound to variables of the same names.

case "submitted 2020-10-20" of
    [regex|(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})|] ->
        let year = read @Int $ Text.unpack y
            ...

Note that it is not possible to access the 0th capture this way. As a workaround, explicitly capture the whole pattern and name it.

If there are no named captures, this simply acts as a guard.

An optical variant of regex/a type-annotated variant of _captures. Can only be used as an expression.

_regex :: String -> Traversal' Text (Captures info)
_regex :: String -> Traversal' Text Text

embeddedNumbers :: Traversal' String Int
embeddedNumbers = packed . [_regex|\d+|] . unpacked . _Show

main :: IO ()
main = putStrLn $ "There are 14 competing standards" & embeddedNumbers %~ (+ 1)

-- There are 15 competing standards

A wrapper around a list of captures that carries additional type-level information about the number and names of those captures.

This type is only intended to be created by regex/_regex and consumed by capture/_capture, relying on type inference. Specifying the info explicitly in a type signature is not supported—the definition of CapturesInfo is not part of the public API and may change.

After obtaining Captures it's recommended to immediately consume them and transform them into application-level data, to avoid leaking the types.

Safely lookup a capture in a Captures result obtained from a Template Haskell-generated matching function.

The type signature may be interpreted like this: Given some capture group index i and some info about a regex, ensure that index exists and is resolved to the number num at compile time. Then, at runtime, get a capture group (numbered num) from a list of (at least num) captures.

In practice the variable i is specified by type application and the other variables are inferred.

capture @3
capture @"bar"

Specifying an invalid index will result in a type error.

Like capture but focus from a Captures to a capture.

A Monoid representing nearly every facility PCRE2 presents for tweaking the behavior of regex compilation and execution.

All library functions that take options have the suffix Opt in their names; for each of them, there's also a non-Opt convenience function that simply has the (unexported) mempty option. For many uses, options won't be needed.

Some options can be enabled by special character sequences in the pattern as an alternative to specifying them as an Option. See Caseless for example.

Most options are exported in Text.Regex.Pcre2. The callout interface is found in Text.Regex.Pcre2.Unsafe.

Documentation is scant here. For more complete, accurate information, including discussions of corner cases arising from specific combinations of options and pattern items, please see the C API documentation.

What \R, backslash R, can mean.

What's considered a newline.

The root of the PCRE2 exception hierarchy.

Vanilla PCRE2 exceptions with messages generated by the underlying C library.

PCRE2 compile exceptions. Along with a message stating the cause, we show the pattern with a cursor pointing at where the error is (if not after the last character).

See Bsr.

Which code widths PCRE2 is compiled to operate on. Can be any combination of 8, 16, and 32. Should be [8] but provided here for completeness.

See DepthLimit.

See HeapLimit.

Was PCRE2 built with JIT support?

A nice description of the CPU architecture JIT support is compiled for, if any.

Number of bytes used for internal linkage in compiled regexes.

See MatchLimit.

See Newline.

See NeverBackslashC.

See ParensLimit.

Size in bytes of PCRE2's built-in character processing tables.

Unicode version string such as 8.0.0, if Unicode is supported at all.

Was PCRE2 built with Unicode support?

Version of the built-in C library. The versioning scheme is that PCRE legacy is 8.x and PCRE2 is 10.x, so this should be 10.something.