HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Modulepcre2-2.3.1GHC2021

Text.Regex.Pcre2.Unsafe

These items are unsafe for one reason or another, and are sequestered here to require the user to do an extra import to get them.

Chief among them is the callout interface: these options and associated datatypes may be used to register effectful callbacks, sometimes referred to as callouts in the PCRE2 API, for regex compilation, matching, and substitution. We include them here for completeness and use them to implement unit tests for this library; for ordinary use, however, seek other means to accomplish whatever is needed (such as accreting effects with optics), since they carry all the problems of unsafePerformIO. See the C API docs for more information.

  • 6 types
  • 1 value
  • Packagepcre2-2.3.1
  • Exports7
  • LanguageGHC2021
  • LicenceApache-2.0
  • SourceUnsafe.hs

Un-refining Captures

1 declaration
valuegetCaptures :: Captures info -> NonEmpty Text
#

Extract the underlying captures from a Template Haskell-generated Captures. This loses type-level information.

Options

1 declaration
datadata Option
#

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.

Constructors

  • BadEscapeIsLiteral

    Do not throw an error for unrecognized or malformed escapes. "This is a dangerous option."

  • UnsafeCompileRecGuard (Int -> IO Bool)

    Run the given guard on every new descent into a level of parentheses, passing the current depth as argument. Returning False aborts pattern compilation with an exception. Multiples of this option before the rightmost are ignored.

    NOTE: Currently (PCRE2 version 10.39) patterns seem to be compiled in two passes, both times triggering the recursion guard. Also, it is triggered at the beginning of the pattern, passing 0. None of this is documented; expect the unexpected in the presence of side effects!

  • UnsafeCallout (CalloutInfo -> IO CalloutResult)

    Run the given callout at every callout point (see the docs for more info). Multiples of this option before the rightmost are ignored.

  • AutoCallout

    Run callout for every pattern item. Only relevant if a callout is set.

  • UnsafeSubCallout (SubCalloutInfo -> IO SubCalloutResult)

    Run the given callout on every substitution. This is at most once unless SubGlobal is set. Multiples of this option before the rightmost are ignored.

Instances2Semigroup, Monoid

Types

5 declarations
datadata CalloutInfo
#

Input for user-defined callouts.

Constructors

Instances2Eq, Show
datadata SubCalloutInfo
#

Input for user-defined substitution callouts.

Constructors

Instances2Eq, Show
datadata SubCalloutResult
#

Substitution callout functions return one of these values, which dictates what happens next in the substitution.

Constructors

Instances2Eq, Show