<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--Rendered using the Haskell Html Library v0.2-->
<HTML
><HEAD
><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"
><TITLE
>Text.Regex.Base.Context</TITLE
><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css"
><SCRIPT SRC="haddock-util.js" TYPE="text/javascript"
></SCRIPT
><SCRIPT TYPE="text/javascript"
>window.onload = function () {setSynopsis("mini_Text-Regex-Base-Context.html")};</SCRIPT
></HEAD
><BODY
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="topbar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" "
></TD
><TD CLASS="title"
>regex-base-0.93.2: Replaces/Enhances Text.Regex</TD
><TD CLASS="topbut"
><A HREF="index.html"
>Contents</A
></TD
><TD CLASS="topbut"
><A HREF="doc-index.html"
>Index</A
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="modulebar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><FONT SIZE="6"
>Text.Regex.Base.Context</FONT
></TD
><TD ALIGN="right"
><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="infohead"
>Portability</TD
><TD CLASS="infoval"
>non-portable (MPTC+FD)</TD
></TR
><TR
><TD CLASS="infohead"
>Stability</TD
><TD CLASS="infoval"
>experimental</TD
></TR
><TR
><TD CLASS="infohead"
>Maintainer</TD
><TD CLASS="infoval"
>libraries@haskell.org, textregexlazy@personal.mightyreason.com</TD
></TR
></TABLE
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Description</TD
></TR
><TR
><TD CLASS="doc"
><P
>This is a module of instances of <TT
><A HREF="Text-Regex-Base-RegexLike.html#t%3ARegexContext"
>RegexContext</A
></TT
> (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.
</P
><P
>These instances work for all the supported types and backends
interchangably. These instances provide the different results that
can be gotten from a match or matchM operation (often via the <TT
>=~</TT
> and
<TT
>=~~</TT
> operators with combine <TT
>makeRegex</TT
> with <TT
>match</TT
> and <TT
>matchM</TT
>
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.
</P
><P
><TT
>RegexContext a b c</TT
> takes a regular expression suppied in a type a
generated by RegexMaker and a target text supplied in type b to a
result type c using the <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3Amatch"
>match</A
></TT
> class function. The <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3AmatchM"
>matchM</A
></TT
> class
function works like <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3Amatch"
>match</A
></TT
> unless there is no match found, in which
case it calls <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Control-Monad.html#v%3Afail"
>fail</A
></TT
> in the (arbitrary) monad context.
</P
><P
>There are a few type synonyms from RegexLike that are used here:
</P
><PRE
>
-- | 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))
</PRE
><P
>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.
</P
><PRE
>
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) }
</PRE
><P
>The newtypes' <TT
>f</TT
> parameters are the containers, usually <TT
>[]</TT
> or
<TT
>Array Int</TT
>, (where the arrays all have lower bound 0).
</P
><P
>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.
</P
><P
>Where provided, noncaptured submatches will have a <TT
>MatchOffset</TT
> of
(-1) and non-negative otherwise. The semantics of submatches depend
on the backend and its compile and execution options. Where provided,
<TT
>MatchLength</TT
> 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.
</P
><P
>XXX THIS HADDOCK DOCUMENTATION IS OUT OF DATE XXX
</P
><P
>These are for finding the first match in the target text:
</P
><P
><TT
> RegexContext a b Bool </TT
> :
Whether there is any match or not.
</P
><P
><TT
> RegexContext a b () </TT
> :
Useful as a guard with <TT
>matchM</TT
> or <TT
>=~~</TT
> in a monad, since failure to match calls <TT
><A HREF="/usr/share/doc/ghc/html/libraries/base-4.2.0.2/Control-Monad.html#v%3Afail"
>fail</A
></TT
>.
</P
><P
><TT
> RegexContext a b b </TT
> :
This returns the text of the whole match.
It will return <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3Aempty"
>empty</A
></TT
> from the <TT
><A HREF="Text-Regex-Base-RegexLike.html#t%3AExtract"
>Extract</A
></TT
> type class if there is no match.
These are defined in each backend module, but documented here for convenience.
</P
><P
><TT
> RegexContext a b (MatchOffset,MatchLength) </TT
> :
This returns the initial index and length of the whole match.
MatchLength will always be non-negative, and 0 for a failed match.
</P
><P
><TT
> RegexContext a b (MatchResult b) </TT
> : The
<TT
><A HREF="Text-Regex-Base-RegexLike.html#t%3AMatchResult"
>MatchResult</A
></TT
> structure with details for the match. This is the
structure copied from the old <TT
>JRegex</TT
> pacakge.
</P
><P
><TT
> RegexContext a b (b, b, b) </TT
> :
The text before the match, the text of the match, the text after the match
</P
><P
><TT
> RegexContext a b (b, MatchText b, b) </TT
> :
The text before the match, the details of the match, and the text after the match
</P
><P
><TT
> RegexContext a b (b, b, b, [b]) </TT
> :
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
<TT
>Text.Regex</TT
> API.
</P
><P
>Two containers of the submatch offset information:
</P
><P
><TT
> RegexContext a b MatchArray </TT
> :
Array of <TT
>(MatchOffset,MatchLength)</TT
> for all the sub matches.
The whole match is at the intial 0th index.
Noncaptured submatches will have a <TT
>MatchOffset</TT
> of (-1)
The array will have no elements and bounds (1,0) if there is no match.
</P
><P
><TT
> RegexContext a b (AllSubmatches [] (MatchOffset,MatchLength) </TT
> :
List of <TT
>(MatchOffset,MatchLength)</TT
>
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.
</P
><P
>Two containers of the submatch text and offset information:
</P
><PRE
> RegexContext a b (AllTextSubmatches (Array Int) (b, (MatchOffset, MatchLength)))</PRE
><PRE
> RegexContext a b (AllTextSubmatches [] (b, (MatchOffset, MatchLength)))</PRE
><P
>Two containers of the submatch text information:
</P
><PRE
> RegexContext a b (AllTextSubmatches [] b)</PRE
><PRE
> RegexContext a b (AllTextSubmatches (Array Int) b)</PRE
><P
>These instances are for all the matches (non-overlapping). Note that
backends are supposed to supply <TT
><A HREF="Text-Regex-Base-RegexLike.html#t%3ARegexLike"
>RegexLike</A
></TT
> instances for which the
default <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3AmatchAll"
>matchAll</A
></TT
> and <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3AmatchAllText"
>matchAllText</A
></TT
> stop searching after returning
any successful but empty match.
</P
><P
><TT
> RegexContext a b Int </TT
> :
The number of matches, non-negative.
</P
><P
>Two containers for locations of all matches:
</P
><PRE
> RegexContext a b (AllMatches [] (MatchOffset, MatchLength))</PRE
><PRE
> RegexContext a b (AllMatches (Array Int) (MatchOffset,MatchLength))</PRE
><P
>Two containers for the locations of all matches and their submatches:
</P
><P
><TT
> RegexContext a b [MatchArray] </TT
> :
</P
><PRE
> RegexContext a b (AllMatches (Array Int) MatchArray)</PRE
><P
>Two containers for the text and locations of all matches and their submatches:
</P
><PRE
> RegexContext a b [MatchText b]</PRE
><PRE
> RegexContext a b (AllTextMatches (Array Int) (MatchText b))</PRE
><P
>Two containers for text of all matches:
<TT
> RegexContext a b (AllTextMatches [] b) </TT
>
</P
><PRE
> RegexContext a b (AllTextMatches (Array Int) b)</PRE
><P
>Four containers for text of all matches and their submatches:
</P
><PRE
> RegexContext a b [[b]]</PRE
><PRE
> RegexContext a b (AllTextMatches (Array Int) [b])</PRE
><PRE
> RegexContext a b (AllTextMatches [] (Array Int b))</PRE
><PRE
> RegexContext a b (AllTextMatches (Array Int) (Array Int b))</PRE
><P
>Unused matches are <TT
><A HREF="Text-Regex-Base-RegexLike.html#v%3Aempty"
>empty</A
></TT
> (defined via <TT
><A HREF="Text-Regex-Base-RegexLike.html#t%3AExtract"
>Extract</A
></TT
>)
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="botbar"
>Produced by <A HREF="http://www.haskell.org/haddock/"
>Haddock</A
> version 2.6.1</TD
></TR
></TABLE
></BODY
></HTML
>
