Copyright | (c) Chris Kuklewicz 2006 |
---|---|
License | BSD-3-Clause |
Maintainer | hvr@gnu.org, Andreas Abel |
Stability | stable |
Portability | non-portable (MPTC+FD) |
Safe Haskell | Safe |
Language | Haskell2010 |
This is a module of instances of RegexContext
(defined in
Text.Regex.Base.RegexLike). Nothing else is exported. This is
usually imported via the Text.Regex.Base convenience package which
itself is re-exported from newer Text.Regex.XXX
modules provided by
the different regex-xxx
backends.
These instances work for all the supported types and backends
interchangeably. These instances provide the different results that
can be gotten from a match
or matchM
operation (often via the =~
and
=~~
operators with combine makeRegex
with match
and matchM
respectively). This module name is Context
because they operators are
context dependent: use them in a context that expects an Int
and you
get a count of matches, use them in a Bool
context and get True
if
there is a match, etc.
takes a regular expression suppied in a type RegexContext
a b ca
generated by RegexMaker
and a target text supplied in type b
to a
result type c
using the match
class function. The matchM
class
function works like match
unless there is no match found, in which
case it calls fail
in the (arbitrary) monad context.
There are a few type synonyms from Text.Regex.Base.RegexLike that are used here:
-- | 0 based index from start of source, or (-1) for unused type MatchOffset = Int -- | non-negative length of a match type MatchLength = Int type MatchArray = Array Int (MatchOffset, MatchLength) type MatchText source = Array Int (source, (MatchOffset, MatchLength))
There are also a few newtypes that used to prevent any possible overlap of types, which were not needed for GHC's late overlap detection but are needed for use in Hugs.
newtype AllSubmatches f b = AllSubmatches { getAllSubmatches :: f b } newtype AllTextSubmatches f b = AllTextSubmatches { getAllTextSubmatches :: f b } newtype AllMatches f b = AllMatches { getAllMatches :: f b } newtype AllTextMatches f b = AllTextMatches { getAllTextMatches :: f b }
The newtypes' f
parameters are the containers, usually []
or
Array Int
, (where the arrays all have lower bound 0).
The two Submatches
newtypes return only information on the first
match. The other two newtypes return information on all the
non-overlapping matches. The two Text
newtypes are used to mark
result types that contain the same type as the target text.
Where provided, noncaptured submatches will have a MatchOffset
of
(-1) and non-negative otherwise. The semantics of submatches depend
on the backend and its compile and execution options. Where provided,
MatchLength
will always be non-negative. Arrays with no elements
are returned with bounds of (1,0). Arrays with elements will have a
lower bound of 0.
XXX THIS HADDOCK DOCUMENTATION IS OUT OF DATE XXX
These are for finding the first match in the target text:
:
Whether there is any match or not.RegexContext
a b Bool
:
Useful as a guard with RegexContext
a b () matchM
or =~~
in a monad, since failure to match calls fail
.
:
This returns the text of the whole match.
It will return RegexContext
a b b empty
from the Extract
type class if there is no match.
These are defined in each backend module, but documented here for convenience.
:
This returns the initial index and length of the whole match.
MatchLength will always be non-negative, and 0 for a failed match.RegexContext
a b (MatchOffset
, MatchLength
)
: The
RegexContext
a b (MatchResult
b) MatchResult
structure with details for the match. This is the
structure copied from the old JRegex
pacakge.
:
The text before the match, the text of the match, the text after the matchRegexContext
a b (b, b, b)
:
The text before the match, the details of the match, and the text after the matchRegexContext
a b (b, MatchText
b, b)
:
The text before the match, the text of the match, the text after the
match, and a list of the text of the 1st and higher sub-parts of the
match. This is the same return value as used in the old
RegexContext
a b (b, b, b, [b]) Text.Regex
API.
Two containers of the submatch offset information:
:
Array of RegexContext
a b MatchArray
(
for all the sub matches.
The whole match is at the intial 0th index.
Noncaptured submatches will have a MatchOffset
, MatchLength
)
of (-1)
The array will have no elements and bounds (1,0) if there is no match.MatchOffset
:
List of RegexContext
a b (AllSubmatches
[] (MatchOffset
, MatchLength
) (
The whole match is the first element, the rest are the submatches (if any) in order.
The list is empty if there is no match.MatchOffset
, MatchLength
)
Two containers of the submatch text and offset information:
RegexContext
a b (AllTextSubmatches
(Array Int) (b, (MatchOffset
,MatchLength
)))
RegexContext
a b (AllTextSubmatches
[] (b, (MatchOffset
,MatchLength
)))
Two containers of the submatch text information:
RegexContext
a b (AllTextSubmatches
[] b)
RegexContext
a b (AllTextSubmatches
(Array Int) b)
These instances are for all the matches (non-overlapping). Note that
backends are supposed to supply RegexLike
instances for which the
default matchAll
and matchAllText
stop searching after returning
any successful but empty match.
:
The number of matches, non-negative.RegexContext
a b Int
Two containers for locations of all matches:
RegexContext
a b (AllMatches
[] (MatchOffset
,MatchLength
))
RegexContext
a b (AllMatches
(Array Int) (MatchOffset
,MatchLength
))
Two containers for the locations of all matches and their submatches:
RegexContext
a b [MatchArray
]
RegexContext
a b (AllMatches
(Array Int)MatchArray
)
Two containers for the text and locations of all matches and their submatches:
RegexContext
a b [MatchText
b]
RegexContext
a b (AllTextMatches
(Array Int) (MatchText
b))
Two containers for text of all matches:
RegexContext
a b (AllTextMatches
[] b)
RegexContext
a b (AllTextMatches
(Array Int) b)
Four containers for text of all matches and their submatches:
RegexContext
a b [[b]]
RegexContext
a b (AllTextMatches
(Array Int) [b])
RegexContext
a b (AllTextMatches
[] (Array Int b))
RegexContext
a b (AllTextMatches
(Array Int) (Array Int b))