Apache-2.0 licensed by Shlomo Shuck and contributors
Maintained by [email protected]
This version can be pinned in stack with:pcre2-2.2.1@sha256:057bd6337dbb681708f5df7ce2d13884e93830f1b2f4f51f8e7096dd87358285,6331

Module documentation for 2.2.1


CI Hackage

Regular expressions for Haskell.


licensePlate :: Text -> Maybe Text
licensePlate = match "[A-Z]{3}[0-9]{3,4}"

licensePlates :: Text -> [Text]
licensePlates = match "[A-Z]{3}[0-9]{3,4}"
case "The quick brown fox" of
    [regex|\bbrown\s+(?<animal>[A-z]+)\b|] -> Text.putStrLn animal
    _                                      -> error "nothing brown"
let kv'd = lined . packed . [_regex|(?x)  # Extended PCRE2 syntax
        ^\s*          # Ignore leading whitespace
        ([^=:\s].*?)  # Capture the non-empty key
        \s*           # Ignore trailing whitespace
        [=:]          # Separator
        \s*           # Ignore leading whitespace
        (.*?)         # Capture the possibly-empty value
        \s*$          # Ignore trailing whitespace

forMOf kv'd file $ execStateT $ do
    k <- gets $ capture @1
    v <- gets $ capture @2
    liftIO $ Text.putStrLn $ "found " <> k <> " set to " <> v

    case myMap ^. at k of
        Just v' | v /= v' -> do
            liftIO $ Text.putStrLn $ "setting " <> k <> " to " <> v'
            _capture @2 .= v'
        _ -> liftIO $ Text.putStrLn "no change"


  • No opaque “Regex” object. Instead, quiet functions with simple types—for the most part it’s Text (pattern) -> Text (subject) -> result. Use partial application to create performant, compile-once-match-many code.
  • No custom typeclasses.
  • A single datatype for both compile and match options, the Option monoid.
  • Text everywhere. See below for a version guide.
  • Match success expressed via Alternative.
  • Opt-in Template Haskell facilities for compile-time verification of patterns, indexing captures, and memoizing inline regexes.
  • Opt-in lens support.
  • No failure monads to express compile errors, preferring pure functions and throwing imprecise exceptions with pretty Show instances. Write simple code and debug it. Or, don’t, and use the Template Haskell features instead. Both are first-class.
  • Vast presentation of PCRE2 functionality. We can even register Haskell callbacks to run during matching!
  • Zero-copying of substrings where beneficial.
  • Few dependencies.
  • Bundled, statically-linked UTF-8 (formerly UTF-16) build of up-to-date PCRE2 (version 10.40), with a complete, exposed Haskell binding.


Currently we are slower than other libraries. For example:

Operation pcre2 pcre-light regex-pcre-builtin
Compile and match a regex 3.9 μs 1.2 μs 2.9 μs

If it’s really regex processing that’s causing a bottleneck, pcre-light/-heavy/lens-regex-pcre are recommended instead of this library for the very best performance.


Encoding text version pcre2 version Code unit representation
UTF-8 ≥ 2 ≥ 2.2 Foreign.C.Types.CUChar
UTF-16 < 2 < 2.2 Foreign.C.Types.CUShort


  • Many performance optimizations. Currently we are slower than other libraries. For example:
  • Make use of DFA matching and JIT compilation.
  • Improve PCRE2 C compile time.
  • Add splitting support.


Apache 2.0.
PCRE2 is distributed under the 3-clause BSD license.

Main Author

©2020–2022 Shlomo Shuck


Changelog and Acknowledgements


  • Fixed #26 where wide UTF-8 characters were not handled correctly.
  • Docs fully updated for UTF-8 instead of UTF-16. (Docs were deleted from the 2.2.0 release.)


  • Switched to UTF-8 to support text 2.0, implementing #22. text < 2 is no longer supported.
    • Changed type synonym PCRE2_UCHAR from CUShort to CUChar in the low-level bindings.
    • No API changes in the high-level bindings.
    • There is a minor regression in the ability to match \R against line separators (U+2028) and paragraph separators (U+2029). See #26.

  • Updated library, tests, and docs for mtl 2.3 and microlens-platform The mtl part of this is pursuant to #30.


  • Added pattern serialization API, which fixes #23.
  • Updated PCRE2 to 10.40 (no API changes).

  • Explicitly required text < 2.
  • Minor docs adjustments.


  • Replaced Proxy :: Proxy info with type applications in splices from regex/_regex. This significantly shortens the splices, producing nicer error messages. As a very minor consequence, we now require the user to turn on {-# LANGUAGE TypeApplications #-} when using regex/_regex with patterns with parenthesized captures, even when not using capture/_capture.


  • Enabled PCRE2’s built-in Unicode support, which fixes #21.


  • Added Show instance for Captures to ease debugging user code.



  • Fixed a minor issue where the caret indicating pattern location of a Pcre2CompileException was misplaced if the pattern contained a newline.


  • Added microlens as a dependency to improve Haddock docs (Traversal' et al. are clickable) and relieve maintenance burden somewhat.
  • Moderate refactoring of internals.


This release introduces significant breaking changes in order to make the API smaller, more consistent, and safer.

  • Implemented #18:
    • Removed matchAll, matchAllOpt, capturesAll, and capturesAllOpt.
    • Upgraded match, matchOpt, captures, and capturesOpt to offer their functionality, respectively.
    • Renamed capturesA and capturesAOpt to captures and capturesOpt, replacing the latter two functions altogether. captures/-Opt were intended to be extreme convenience functions that required no special datatypes beyond the Prelude. However, this was of doubtful benefit, since that’s false anyway—they required Text, not to mention {-# LANGUAGE OverloadedStrings #-}. Their names are simple and valuable, and no other Alternative-producing function has the naming convention “-A”, so repurposing their names was in order.
  • Moved the callout interface to a new module, Text.Regex.Pcre2.Unsafe. This includes the options UnsafeCompileRecGuard, UnsafeCallout, UnsafeSubCallout, and AutoCallout, and the types CalloutInfo, CalloutIndex, CalloutResult, SubCalloutInfo, and SubCalloutResult.
  • Also moved option BadEscapeIsLiteral there.
  • Removed the ineffectual options DupNames and Utf.

Other improvements with no API impact:

  • Updated PCRE2 to 10.37.
  • Replaced copied C files with symlinks, diminishing codebase by 1.5K lines and simplifying future PCRE2 updates.
  • Reduced size of Template Haskell splices to make error messages less obnoxious.
  • Moderate refactoring of internals and documentation.


  • Fixed #17, where functions returning Alternative containers were not restricted to single results despite their documentation.
  • Minor improvements to docs and examples.


  • Fixed some incorrect foreign imports’ safety.

  • Fixed a very minor issue where pcreVersion still reported “10.35” even though it in fact was using 10.36.


  • Made in-house streaming abstraction based on streaming and removed the latter as a dependency.
  • Updated PCRE2 to 10.36 (no API changes).
  • Docs fixes.


  • Refactored using the streaming library. Fixed #11, where large global matches were very slow.


  • Fixed #12, where some functions returned too many match results.


  • Added global matching.
    • New functions matchAll, matchAllOpt, capturesAll, capturesAllOpt.
    • Changed all traversals from affine to non-affine.
  • Changed capturesOptA to capturesAOpt for naming consistency.


  • Fixed #4, where multiple named captures were not type-indexed correctly.
  • Established automated builds using Github Workflows. Thanks amesgen!

  • Temporarily eliminate all dependency version bounds to get it building on Hackage.


  • Fixed #1, where building on Windows would succeed but not run. Thanks Andrew!
  • Try to adjust dependency version bounds to get it building on Hackage. Thanks snoyberg!


  • Initial release.