Text.Regex.Applicative

Type of regular expressions that recognize symbols of type s and produce a result of type a.

Regular expressions can be built using Functor, Applicative, Alternative, and Filtrable instances in the following natural way:

• f <$> ra matches iff ra matches, and its return value is the result of applying f to the return value of ra.

• pure x matches the empty string (i.e. it does not consume any symbols), and its return value is x

• rf <*> ra matches a string iff it is a concatenation of two strings: one matched by rf and the other matched by ra. The return value is f a, where f and a are the return values of rf and ra respectively.

• ra <|> rb matches a string which is accepted by either ra or rb. It is left-biased, so if both can match, the result of ra is used.

• empty is a regular expression which does not match any string.

• many ra matches concatenation of zero or more strings matched by ra and returns the list of ra's return values on those strings.

• some ra matches concatenation of one or more strings matched by ra and returns the list of ra's return values on those strings.

• catMaybes ram matches iff ram matches and produces 'Just _'.

• ra <> rb matches ra followed by rb. The return value is a <> b, where a and b are the return values of ra and rb respectively. (See https://github.com/feuerbach/regex-applicative/issues/37#issue-499781703 for an example usage.)

• mempty matches the empty string (i.e. it does not consume any symbols), and its return value is the mempty value of type a.

Match and return the given symbol

Match and return a single symbol which satisfies the predicate

Like psym, but allows to return a computed value instead of the original symbol

Match and return any single symbol

Match and return the given sequence of symbols.

Note that there is an IsString instance for regular expression, so if you enable the OverloadedStrings language extension, you can write string "foo" simply as "foo".

Example:

{-# LANGUAGE OverloadedStrings #-}
import Text.Regex.Applicative

number = "one" *> pure 1  <|>  "two" *> pure 2

main = print $ "two" =~ number

Match zero or more instances of the given expression, which are combined using the given folding function.

Greediness argument controls whether this regular expression should match as many as possible (Greedy) or as few as possible (NonGreedy) instances of the underlying expression.

Match zero or more instances of the given expression, but as few of them as possible (i.e. non-greedily). A greedy equivalent of few is many.

Examples:

Text.Regex.Applicative> findFirstPrefix (few anySym  <* "b") "ababab"
Just ("a","abab")
Text.Regex.Applicative> findFirstPrefix (many anySym  <* "b") "ababab"
Just ("ababa","")

RE is a profunctor. This is its contravariant map.

(A dependency on the profunctors package doesn't seem justified.)

Return matched symbols as part of the return value

Attempt to match a string of symbols against the regular expression. Note that the whole string (not just some part of it) should be matched.

Examples:

Text.Regex.Applicative> match (sym 'a' <|> sym 'b') "a"
Just 'a'
Text.Regex.Applicative> match (sym 'a' <|> sym 'b') "ab"
Nothing

Replace matches of the regular expression with its value.

Text.Regex.Applicative > replace ("!" <$ sym 'f' <* some (sym 'o')) "quuxfoofooooofoobarfobar"
"quux!!!bar!bar"

Find a string prefix which is matched by the regular expression.

Of all matching prefixes, pick one using left bias (prefer the left part of <|> to the right part) and greediness.

This is the match which a backtracking engine (such as Perl's one) would find first.

If match is found, the rest of the input is also returned.

See also findFirstPrefixWithUncons, of which this is a special case.

Examples:

Text.Regex.Applicative> findFirstPrefix ("a" <|> "ab") "abc"
Just ("a","bc")
Text.Regex.Applicative> findFirstPrefix ("ab" <|> "a") "abc"
Just ("ab","c")
Text.Regex.Applicative> findFirstPrefix "bc" "abc"
Nothing

Find the longest string prefix which is matched by the regular expression.

Submatches are still determined using left bias and greediness, so this is different from POSIX semantics.

If match is found, the rest of the input is also returned.

See also findLongestPrefixWithUncons, of which this is a special case.

Examples:

Text.Regex.Applicative Data.Char> let keyword = "if"
Text.Regex.Applicative Data.Char> let identifier = many $ psym isAlpha
Text.Regex.Applicative Data.Char> let lexeme = (Left <$> keyword) <|> (Right <$> identifier)
Text.Regex.Applicative Data.Char> findLongestPrefix lexeme "if foo"
Just (Left "if"," foo")
Text.Regex.Applicative Data.Char> findLongestPrefix lexeme "iffoo"
Just (Right "iffoo","")

Find the shortest prefix (analogous to findLongestPrefix)

See also findShortestPrefixWithUncons, of which this is a special case.

Find the leftmost substring that is matched by the regular expression. Otherwise behaves like findFirstPrefix. Returns the result together with the prefix and suffix of the string surrounding the match.

Find the leftmost substring that is matched by the regular expression. Otherwise behaves like findLongestPrefix. Returns the result together with the prefix and suffix of the string surrounding the match.

Find the leftmost substring that is matched by the regular expression. Otherwise behaves like findShortestPrefix. Returns the result together with the prefix and suffix of the string surrounding the match.

Find the first prefix, with the given uncons function.

Find the longest prefix, with the given uncons function.

Find the shortest prefix (analogous to findLongestPrefix), with the given uncons function.

A functor with application, providing operations to

• embed pure expressions (pure), and

• sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id

liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

Identity

pure id <*> v = v

Composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

Homomorphism

pure f <*> pure x = pure (f x)

Interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

• u *> v = (id <$ u) <*> v

• u <* v = liftA2 const u v

As a consequence of these laws, the Functor instance for f will satisfy

• fmap f x = pure f <*> x

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

• (*>) = (>>)

(which implies that pure and <*> satisfy the applicative functor laws).

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

• some v = (:) Prelude.<$> v <*> many v

• many v = some v <|> pure []

Examples

>>> Nothing <|> Just 42Just 42

>>> [1, 2] <|> [3, 4][1,2,3,4]

>>> empty <|> print (2^15)32768

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)(2,True)

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

Perform a computation with Maybe and replace the result with a constant value if it is Just:

>>> 'a' <$ Just 2Just 'a'>>> 'a' <$ NothingNothing

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

The Const functor.

Examples

>>> fmap (++ "World") (Const "Hello")Const "Hello"

Because we ignore the second type parameter to Const, the Applicative instance, which has (<*>) :: Monoid m => Const m (a -> b) -> Const m a -> Const m b essentially turns into Monoid m => m -> m -> m, which is (<>)

>>> Const [1, 2, 3] <*> Const [4, 5, 6]Const [1,2,3,4,5,6]

Lists, but with an Applicative functor based on zipping.

Examples

In contrast to the Applicative for GHC.List.List:

>>> (+) <$> [1, 2, 3] <*> [4, 5, 6][5,6,7,6,7,8,7,8,9]

The Applicative instance of ZipList applies the operation by pairing up the elements, analogous to zipWithN

>>> (+) <$> ZipList [1, 2, 3] <*> ZipList [4, 5, 6]ZipList {getZipList = [5,7,9]}

>>> (,,,) <$> ZipList [1, 2] <*> ZipList [3, 4] <*> ZipList [5, 6] <*> ZipList [7, 8]ZipList {getZipList = [(1,3,5,7),(2,4,6,8)]}

>>> ZipList [(+1), (^2), (/ 2)] <*> ZipList [5, 5, 5]ZipList {getZipList = [6.0,25.0,2.5]}