| Haskell Hierarchical Libraries (regex-posix package) | Source code | Contents | Index

Text.Regex.Posix.String

Portability | non-portable (regex-base needs MPTC+FD)
Stability | experimental
Maintainer | libraries@haskell.org, textregexlazy@personal.mightyreason.com

Contents

Types
Miscellaneous
Medium level API functions
Compilation options
Execution options

Description

This provides `String` instances for `RegexMaker` and `RegexLike` based on Text.Regex.Posix.Wrap, and a (`RegexContext` `Regex` `String` `String`) instance.

To use these instance, you would normally import Text.Regex.Posix. You only need to import this module to use the medium level API of the compile, regexec, and execute functions. All of these report error by returning Left values instead of undefined or error or fail.

Synopsis

data Regex
MatchOffset
MatchLength
data ReturnCode
type WrapError = (ReturnCode, String)
unusedOffset :: Int
compile :: CompOption -> ExecOption -> String -> IO (Either WrapError Regex)
regexec :: Regex -> String -> IO (Either WrapError (Maybe (String, String, String, [String])))
execute :: Regex -> String -> IO (Either WrapError (Maybe (Array Int (MatchOffset, MatchLength))))
newtype CompOption = CompOption CInt
compBlank :: CompOption
compExtended :: CompOption
compIgnoreCase :: CompOption
compNoSub :: CompOption
compNewline :: CompOption
newtype ExecOption = ExecOption CInt
execBlank :: ExecOption
execNotBOL :: ExecOption
execNotEOL :: ExecOption

Types
data Regex

A compiled regular expression.
Instances

RegexLike Regex ByteString
RegexLike Regex String
RegexContext Regex ByteString ByteString
RegexContext Regex String String
RegexOptions Regex CompOption ExecOption
RegexMaker Regex CompOption ExecOption ByteString
RegexMaker Regex CompOption ExecOption String

MatchOffset
MatchLength
data ReturnCode

ReturnCode is an enumerated `CInt`, corresponding to the error codes from `man 3 regex`:

- `retBadbr` (`REG_BADBR`) invalid repetition count(s) in `{ }`
- `retBadpat` (`REG_BADPAT`) invalid regular expression
- `retBadrpt` (`REG_BADRPT`) `?`, `*`, or `+` operand invalid
- `retEcollate` (`REG_ECOLLATE`) invalid collating element
- `retEctype` (`REG_ECTYPE`) invalid character class
- `retEescape` (`REG_EESCAPE`) `\` applied to unescapable character
- `retEsubreg` (`REG_ESUBREG`) invalid backreference number
- `retEbrack` (`REG_EBRACK`) brackets `[ ]` not balanced
- `retEparen` (`REG_EPAREN`) parentheses `( )` not balanced
- `retEbrace` (`REG_EBRACE`) braces `{ }` not balanced
- `retErange` (`REG_ERANGE`) invalid character range in `[ ]`
- `retEspace` (`REG_ESPACE`) ran out of memory
- `retNoMatch` (`REG_NOMATCH`) The regexec() function failed to match

Instances

Eq ReturnCode
Show ReturnCode

type WrapError = (ReturnCode, String)
The return code will be retOk when it is the Haskell wrapper and not the underlying library generating the error message.
Miscellaneous
unusedOffset :: Int
Medium level API functions
compile

:: CompOption | Flags (summed together)
-> ExecOption | Flags (summed together)
-> String | The regular expression to compile (ASCII only, no null bytes)
-> IO (Either WrapError Regex) | Returns: the compiled regular expression

regexec

:: Regex | Compiled regular expression
-> String | String to match against

-> IO (Either WrapError (Maybe (String, String, String, [String])))

Returns: `Nothing` if the regex did not match the string, or:

       Just (everything before match,
             matched portion,
             everything after match,
             subexpression matches)

Matches a regular expression against a string

execute

:: Regex | Compiled regular expression
-> String | String to match against

-> IO (Either WrapError (Maybe (Array Int (MatchOffset, MatchLength))))

Returns: `Nothing` if the regex did not match the string, or:

       Just (array of offset length pairs)

Matches a regular expression against a string

Compilation options
newtype CompOption

A bitmapped `CInt` containing options for compilation of regular expressions. Option values (and their man 3 regcomp names) are

- `compBlank` which is a completely zero value for all the flags. This is also the `blankCompOpt` value.
- `compExtended` (REG_EXTENDED) which can be set to use extended instead of basic regular expressions. This is set in the `defaultCompOpt` value.
- `compNewline` (REG_NEWLINE) turns on newline sensitivity: The dot (.) and inverted set `[^ ]` never match newline, and ^ and $ anchors do match after and before newlines. This is set in the `defaultCompOpt` value.
- `compIgnoreCase` (REG_ICASE) which can be set to match ignoring upper and lower distinctions.
- `compNoSub` (REG_NOSUB) which turns off all information from matching except whether a match exists.

Constructors

CompOption CInt |

Instances

Bits CompOption
Eq CompOption
Num CompOption
Show CompOption
RegexOptions Regex CompOption ExecOption
RegexMaker Regex CompOption ExecOption ByteString
RegexMaker Regex CompOption ExecOption String

compBlank :: CompOption
A completely zero value for all the flags. This is also the `blankCompOpt` value.
compExtended :: CompOption
compIgnoreCase :: CompOption
compNoSub :: CompOption
compNewline :: CompOption
Execution options
newtype ExecOption

A bitmapped `CInt` containing options for execution of compiled regular expressions. Option values (and their man 3 regexec names) are

- `execBlank` which is a complete zero value for all the flags. This is the blankExecOpt value.
- `execNotBOL` (REG_NOTBOL) can be set to prevent ^ from matching at the start of the input.
- `execNotEOL` (REG_NOTEOL) can be set to prevent $ from matching at the end of the input (before the terminating NUL).

Constructors

ExecOption CInt |

Instances

Bits ExecOption
Eq ExecOption
Num ExecOption
Show ExecOption
RegexOptions Regex CompOption ExecOption
RegexMaker Regex CompOption ExecOption ByteString
RegexMaker Regex CompOption ExecOption String

execBlank :: ExecOption
A completely zero value for all the flags. This is also the `blankExecOpt` value.
execNotBOL :: ExecOption
execNotEOL :: ExecOption
Produced by Haddock version 0.8