A pattern is a compiled regular expression plus its compilation options.

Patterns can be created by calling compile explicitly:

import Data.ByteString.Char8 (pack)

p :: Pattern
p = case compile (pack "^hello world$") of
        Right ok -> ok
        Left err -> error ("compilation error: " ++ errorMessage err)
 

Or by using the IsString instance:

import Data.String (fromString)

p :: Pattern
p = fromString "^hello world$"

Or by using the OverloadedStrings language extension:

{-# LANGUAGE OverloadedStrings #-}

p :: Pattern
p = "^hello world$"

compile = compileWith defaultOptions

Compile a regular expression with the given options. If compilation fails, the error can be inspected with errorMessage and errorCode.

Use optionEncoding to select whether the input bytes should be interpreted as UTF-8 or Latin1. The default is UTF8.

The regular expression originally provided to compileWith.

The options originally provided to compileWith.

The capturing groups defined within the pattern. Groups are listed from left to right, and are Nothing if the group is unnamed.

ghci> patternGroups "(\\d+)|(?P<word>\\w+)"
fromList [Nothing,Just "word"]

Options controlling how to compile a regular expression. The fields in this value may be set using record syntax:

compileNoCase :: B.ByteString -> Either Error Pattern
compileNoCase = compileWith (defaultOptions { optionCaseSensitive = False })
 

defaultOptions = Options
        { optionEncoding = EncodingUtf8
        , optionPosixSyntax = False
        , optionLongestMatch = False
        , optionMaxMemory = 8388608  -- 8 << 20
        , optionLiteral = False
        , optionNeverNewline = False
        , optionDotNewline = False
        , optionNeverCapture = False
        , optionCaseSensitive = True
        , optionPerlClasses = False
        , optionWordBoundary = False
        , optionOneLine = False
        }
 

Only checked in posix mode

Only checked in posix mode

Only checked in posix mode

A successful match of the pattern against some input. Capturing groups may be retrieved with matchGroup or matchGroups.

The capturing group with the given index, or Nothing if the group was not set in this match.

The entire match is group 0.

All of the groups in the pattern, with each group being Nothing if it was not set in this match. Groups are returned in the same order as patternGroups.

The entire match is group 0.

The most general matching function. Attempt to match the pattern to the input within the given constraints.

If the number of match groups to populate is 0, matching can be performed more efficiently.

Attempt to find the pattern somewhere within the input.

Replace the first occurance of the pattern with the given replacement template. If the template contains backslash escapes such as \1, the capture group with the given index will be inserted in their place.

Returns the new bytes, and True if a replacement occured.

Replace every occurance of the pattern with the given replacement template. If the template contains backslash escapes such as \1, the capture group with the given index will be inserted in their place.

Returns the new bytes, and how many replacements occured.

Attempt to find the pattern somewhere within the input, and extract it using the given template. If the template contains backslash escapes such as \1, the capture group with the given index will be inserted in their place.

Returns Nothing if the pattern was not found in the input.

Escapes bytes such that the output is a regular expression which will exactly match the input.