Copyright	(c) Chris Kuklewicz 200620072008 derived from (c) The University of Glasgow 2002
Maintainer	hvr@gnu.org, Andreas Abel
Stability	stable
Portability	non-portable (regex-base needs MPTC+FD)
Safe Haskell	None
Language	Haskell2010

Text.Regex.Posix.Wrap

Contents

High-level API
Low-level API
Miscellaneous
Compilation options
Execution options
Return codes

Description

WrapPosix.hsc exports a wrapped version of the ffi imports. To increase type safety, the flags are newtype'd. The other important export is a Regex type that is specific to the Posix library backend. The flags are documented in Text.Regex.Posix. The defaultCompOpt is (compExtended .|. compNewline).

The Regex, CompOption, and ExecOption types and their RegexOptions instance is declared. The =~ and =~~ convenience functions are defined.

This module will fail or error only if allocation fails or a nullPtr is passed in.

2009-January : wrapMatchAll and wrapCount now adjust the execution option execNotBOL after the first result to take into account 'n' in the text immediately before the next matches. (version 0.93.3)

2009-January : wrapMatchAll and wrapCount have been changed to return all non-overlapping matches, including empty matches even if they coincide with the end of the previous non-empty match. The change is that the first non-empty match no longer terminates the search. One can filter the results to obtain the old behavior or to obtain the behavior of "sed", where "sed" eliminates the empty matches which coincide with the end of non-empty matches. (version 0.94.0)

Synopsis

data Regex
type RegOffset = Int64
type RegOffsetT = Int32
(=~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target) => source1 -> source -> target
(=~~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target, MonadFail m) => source1 -> source -> m target
type WrapError = (ReturnCode, String)
wrapCompile :: CompOption -> ExecOption -> CString -> IO (Either WrapError Regex)
wrapTest :: Regex -> CString -> IO (Either WrapError Bool)
wrapMatch :: Regex -> CString -> IO (Either WrapError (Maybe [(RegOffset, RegOffset)]))
wrapMatchAll :: Regex -> CString -> IO (Either WrapError [MatchArray])
wrapCount :: Regex -> CString -> IO (Either WrapError Int)
unusedRegOffset :: RegOffset
newtype CompOption = CompOption CInt
compBlank :: CompOption
compExtended :: CompOption
compIgnoreCase :: CompOption
compNoSub :: CompOption
compNewline :: CompOption
newtype ExecOption = ExecOption CInt
execBlank :: ExecOption
execNotBOL :: ExecOption
execNotEOL :: ExecOption
newtype ReturnCode = ReturnCode CInt
retBadbr :: ReturnCode
retBadpat :: ReturnCode
retBadrpt :: ReturnCode
retEcollate :: ReturnCode
retEctype :: ReturnCode
retEescape :: ReturnCode
retEsubreg :: ReturnCode
retEbrack :: ReturnCode
retEparen :: ReturnCode
retEbrace :: ReturnCode
retErange :: ReturnCode
retEspace :: ReturnCode

High-level API

data Regex #

A compiled regular expression.

Instances

Instances details

RegexLike Regex String #
Instance details Defined in Text.Regex.Posix.String Methods matchOnce :: Regex -> String -> Maybe MatchArray # matchAll :: Regex -> String -> [MatchArray] # matchCount :: Regex -> String -> Int # matchTest :: Regex -> String -> Bool # matchAllText :: Regex -> String -> [MatchText String] # matchOnceText :: Regex -> String -> Maybe (String, MatchText String, String) #
RegexLike Regex ByteString #
Instance details Defined in Text.Regex.Posix.ByteString.Lazy Methods matchOnce :: Regex -> ByteString -> Maybe MatchArray # matchAll :: Regex -> ByteString -> [MatchArray] # matchCount :: Regex -> ByteString -> Int # matchTest :: Regex -> ByteString -> Bool # matchAllText :: Regex -> ByteString -> [MatchText ByteString] # matchOnceText :: Regex -> ByteString -> Maybe (ByteString, MatchText ByteString, ByteString) #
RegexLike Regex ByteString #
Instance details Defined in Text.Regex.Posix.ByteString Methods matchOnce :: Regex -> ByteString -> Maybe MatchArray # matchAll :: Regex -> ByteString -> [MatchArray] # matchCount :: Regex -> ByteString -> Int # matchTest :: Regex -> ByteString -> Bool # matchAllText :: Regex -> ByteString -> [MatchText ByteString] # matchOnceText :: Regex -> ByteString -> Maybe (ByteString, MatchText ByteString, ByteString) #
RegexOptions Regex CompOption ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods blankCompOpt :: CompOption # blankExecOpt :: ExecOption # defaultCompOpt :: CompOption # defaultExecOpt :: ExecOption # setExecOpts :: ExecOption -> Regex -> Regex # getExecOpts :: Regex -> ExecOption #
RegexContext Regex String String #
Instance details Defined in Text.Regex.Posix.String Methods match :: Regex -> String -> String # matchM :: MonadFail m => Regex -> String -> m String #
RegexContext Regex ByteString ByteString #
Instance details Defined in Text.Regex.Posix.ByteString.Lazy Methods match :: Regex -> ByteString -> ByteString # matchM :: MonadFail m => Regex -> ByteString -> m ByteString #
RegexContext Regex ByteString ByteString #
Instance details Defined in Text.Regex.Posix.ByteString Methods match :: Regex -> ByteString -> ByteString # matchM :: MonadFail m => Regex -> ByteString -> m ByteString #
RegexMaker Regex CompOption ExecOption String #
Instance details Defined in Text.Regex.Posix.String Methods makeRegex :: String -> Regex # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex # makeRegexM :: MonadFail m => String -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString.Lazy Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption (Seq Char) #
Instance details Defined in Text.Regex.Posix.Sequence Methods makeRegex :: Seq Char -> Regex # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex # makeRegexM :: MonadFail m => Seq Char -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex #
RegexLike Regex (Seq Char) #
Instance details Defined in Text.Regex.Posix.Sequence Methods matchOnce :: Regex -> Seq Char -> Maybe MatchArray # matchAll :: Regex -> Seq Char -> [MatchArray] # matchCount :: Regex -> Seq Char -> Int # matchTest :: Regex -> Seq Char -> Bool # matchAllText :: Regex -> Seq Char -> [MatchText (Seq Char)] # matchOnceText :: Regex -> Seq Char -> Maybe (Seq Char, MatchText (Seq Char), Seq Char) #
RegexContext Regex (Seq Char) (Seq Char) #
Instance details Defined in Text.Regex.Posix.Sequence Methods match :: Regex -> Seq Char -> Seq Char # matchM :: MonadFail m => Regex -> Seq Char -> m (Seq Char) #

type RegOffset = Int64 #

RegOffset is typedef int regoff_t on Linux and ultimately typedef long long __int64_t on Max OS X. So rather than saying 2,147,483,647 is all the length you need, I'll take the larger: 9,223,372,036,854,775,807 should be enough bytes for anyone, no need for Integer. The alternative is to compile to different sizes in a platform dependent manner with type RegOffset = (#type regoff_t), which I do not want to do.

There is also a special value unusedRegOffset :: RegOffset which is (-1) and as a starting index means that the subgroup capture was unused. Otherwise the RegOffset indicates a character boundary that is before the character at that index offset, with the first character at index offset 0. So starting at 1 and ending at 2 means to take only the second character.

type RegOffsetT = Int32 #

(=~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target) => source1 -> source -> target #

(=~~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target, MonadFail m) => source1 -> source -> m target #

Low-level API

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.

wrapCompile #

Arguments

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

wrapTest :: Regex -> CString -> IO (Either WrapError Bool) #

wrapMatch :: Regex -> CString -> IO (Either WrapError (Maybe [(RegOffset, RegOffset)])) #

wrapMatch returns offsets for the begin and end of each capture. Unused captures have offsets of unusedRegOffset which is (-1).

wrapMatchAll :: Regex -> CString -> IO (Either WrapError [MatchArray]) #

wrapMatchAll returns the offset and length of each capture. Unused captures have an offset of unusedRegOffset which is (-1) and length of 0.

wrapCount :: Regex -> CString -> IO (Either WrapError Int) #

Miscellaneous

unusedRegOffset :: RegOffset #

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

Instances details

Eq CompOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (==) :: CompOption -> CompOption -> Bool # (/=) :: CompOption -> CompOption -> Bool #
Num CompOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (+) :: CompOption -> CompOption -> CompOption # (-) :: CompOption -> CompOption -> CompOption # (*) :: CompOption -> CompOption -> CompOption # negate :: CompOption -> CompOption # abs :: CompOption -> CompOption # signum :: CompOption -> CompOption # fromInteger :: Integer -> CompOption #
Show CompOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods showsPrec :: Int -> CompOption -> ShowS # show :: CompOption -> String # showList :: [CompOption] -> ShowS #
Bits CompOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (.&.) :: CompOption -> CompOption -> CompOption # (.\|.) :: CompOption -> CompOption -> CompOption # xor :: CompOption -> CompOption -> CompOption # complement :: CompOption -> CompOption # shift :: CompOption -> Int -> CompOption # rotate :: CompOption -> Int -> CompOption # zeroBits :: CompOption # bit :: Int -> CompOption # setBit :: CompOption -> Int -> CompOption # clearBit :: CompOption -> Int -> CompOption # complementBit :: CompOption -> Int -> CompOption # testBit :: CompOption -> Int -> Bool # bitSizeMaybe :: CompOption -> Maybe Int # bitSize :: CompOption -> Int # isSigned :: CompOption -> Bool # shiftL :: CompOption -> Int -> CompOption # unsafeShiftL :: CompOption -> Int -> CompOption # shiftR :: CompOption -> Int -> CompOption # unsafeShiftR :: CompOption -> Int -> CompOption # rotateL :: CompOption -> Int -> CompOption # rotateR :: CompOption -> Int -> CompOption # popCount :: CompOption -> Int #
RegexOptions Regex CompOption ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods blankCompOpt :: CompOption # blankExecOpt :: ExecOption # defaultCompOpt :: CompOption # defaultExecOpt :: ExecOption # setExecOpts :: ExecOption -> Regex -> Regex # getExecOpts :: Regex -> ExecOption #
RegexMaker Regex CompOption ExecOption String #
Instance details Defined in Text.Regex.Posix.String Methods makeRegex :: String -> Regex # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex # makeRegexM :: MonadFail m => String -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString.Lazy Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption (Seq Char) #
Instance details Defined in Text.Regex.Posix.Sequence Methods makeRegex :: Seq Char -> Regex # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex # makeRegexM :: MonadFail m => Seq Char -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex #

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

Instances details

Eq ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (==) :: ExecOption -> ExecOption -> Bool # (/=) :: ExecOption -> ExecOption -> Bool #
Num ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (+) :: ExecOption -> ExecOption -> ExecOption # (-) :: ExecOption -> ExecOption -> ExecOption # (*) :: ExecOption -> ExecOption -> ExecOption # negate :: ExecOption -> ExecOption # abs :: ExecOption -> ExecOption # signum :: ExecOption -> ExecOption # fromInteger :: Integer -> ExecOption #
Show ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods showsPrec :: Int -> ExecOption -> ShowS # show :: ExecOption -> String # showList :: [ExecOption] -> ShowS #
Bits ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods (.&.) :: ExecOption -> ExecOption -> ExecOption # (.\|.) :: ExecOption -> ExecOption -> ExecOption # xor :: ExecOption -> ExecOption -> ExecOption # complement :: ExecOption -> ExecOption # shift :: ExecOption -> Int -> ExecOption # rotate :: ExecOption -> Int -> ExecOption # zeroBits :: ExecOption # bit :: Int -> ExecOption # setBit :: ExecOption -> Int -> ExecOption # clearBit :: ExecOption -> Int -> ExecOption # complementBit :: ExecOption -> Int -> ExecOption # testBit :: ExecOption -> Int -> Bool # bitSizeMaybe :: ExecOption -> Maybe Int # bitSize :: ExecOption -> Int # isSigned :: ExecOption -> Bool # shiftL :: ExecOption -> Int -> ExecOption # unsafeShiftL :: ExecOption -> Int -> ExecOption # shiftR :: ExecOption -> Int -> ExecOption # unsafeShiftR :: ExecOption -> Int -> ExecOption # rotateL :: ExecOption -> Int -> ExecOption # rotateR :: ExecOption -> Int -> ExecOption # popCount :: ExecOption -> Int #
RegexOptions Regex CompOption ExecOption #
Instance details Defined in Text.Regex.Posix.Wrap Methods blankCompOpt :: CompOption # blankExecOpt :: ExecOption # defaultCompOpt :: CompOption # defaultExecOpt :: ExecOption # setExecOpts :: ExecOption -> Regex -> Regex # getExecOpts :: Regex -> ExecOption #
RegexMaker Regex CompOption ExecOption String #
Instance details Defined in Text.Regex.Posix.String Methods makeRegex :: String -> Regex # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex # makeRegexM :: MonadFail m => String -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString.Lazy Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption ByteString #
Instance details Defined in Text.Regex.Posix.ByteString Methods makeRegex :: ByteString -> Regex # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex # makeRegexM :: MonadFail m => ByteString -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex #
RegexMaker Regex CompOption ExecOption (Seq Char) #
Instance details Defined in Text.Regex.Posix.Sequence Methods makeRegex :: Seq Char -> Regex # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex # makeRegexM :: MonadFail m => Seq Char -> m Regex # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex #

execBlank :: ExecOption #

A completely zero value for all the flags. This is also the blankExecOpt value.

execNotBOL :: ExecOption #

execNotEOL :: ExecOption #

Return codes

newtype 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

Constructors

ReturnCode CInt

Instances

Instances details

Eq ReturnCode #
Instance details Defined in Text.Regex.Posix.Wrap Methods (==) :: ReturnCode -> ReturnCode -> Bool # (/=) :: ReturnCode -> ReturnCode -> Bool #
Show ReturnCode #
Instance details Defined in Text.Regex.Posix.Wrap Methods showsPrec :: Int -> ReturnCode -> ShowS # show :: ReturnCode -> String # showList :: [ReturnCode] -> ShowS #

retBadbr :: ReturnCode #

retBadpat :: ReturnCode #

retBadrpt :: ReturnCode #

retEcollate :: ReturnCode #

retEctype :: ReturnCode #

retEescape :: ReturnCode #

retEsubreg :: ReturnCode #

retEbrack :: ReturnCode #

retEparen :: ReturnCode #

retEbrace :: ReturnCode #

retErange :: ReturnCode #

retEspace :: ReturnCode #