CondT and its related combinators form a DSL to express whether, given an item of type a: that item passes the predicate, and/or if recursion should be performed from that item, should it relate to the branch of a tree. This is used to build predicates that can guide recursive traversals.

For example, when recursing files in a directory tree, there are several scenarios that CondT maybe consider:

• Whether the entry at a given path is of interest, independent from its type (files or directories)
• If the path is a directory, if the directory should be recursed into.

Yes or no answers are accepted for either criterion. This means that the answer is "no" to both questions for a given directory, the combinator prune should be used both to ignore the entry itself, and to prevent recursion into its contents.

Several different predicate types may be promoted to CondT:

Bool

Using guard

m Bool

Using guardM

a -> Bool

Using guard_

a -> m Bool

Using guardM_

a -> m (Maybe r)

Using apply

a -> m (Maybe (r, a))

Using consider

Here is a trivial example:

flip runCondT 42 $ do
  guard_ even
  liftIO $ putStrLn "42 must be even to reach here"
  guard_ odd <|> guard_ even
  guard_ (== 42)

If CondT is executed using runCondT, it returns a Maybe r if the predicate matched. It should usually be run with applyCondT, which calls a continuation indicating wether recursion should be performed.

Apply a condition to an input value, returning a (possibly) updated copy of that value if it matches, and the next CondT to use if recursion into that value was indicated.

A specialized variant of runCondT that simply returns True or False.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runIdentity $ test "foo.hs" $ not_ bad >> return "Success"
True
>>> runIdentity $ test "foo.hs" $ not_ good >> return "Shouldn't reach here"
False

MonadQuery is a custom version of MonadReader, created so that users could still have their own MonadReader accessible within conditionals.

Apply a value-returning predicate. Note that whether or not this return a Just value, recursion will be performed in the entry itself, if applicable.

Consider an element, as apply, but returning a mutated form of the element. This can be used to apply optimizations to speed future conditions.

ignore ignores the current entry, but allows recursion into its descendents. This is the same as empty.

norecurse prevents recursion into the current entry's descendents, but does not ignore the entry itself.

prune is a synonym for both ignoring an entry and its descendents.

Return True or False depending on whether the given condition matches or not. This differs from simply stating the condition in that it itself always succeeds.

>>> runCond "foo.hs" $ matches (guard =<< queries (== "foo.hs"))
Just True
>>> runCond "foo.hs" $ matches (guard =<< queries (== "foo.hi"))
Just False

A variant of ifM which branches on whether the condition succeeds or not. Note that if_ x is equivalent to ifM (matches x), and is provided solely for convenience.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ if_ good (return "Success") (return "Failure")
Just "Success"
>>> runCond "foo.hs" $ if_ bad (return "Success") (return "Failure")
Just "Failure"

when_ is just like when, except that it executes the body if the condition passes, rather than based on a Bool value.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ when_ good ignore
Nothing
>>> runCond "foo.hs" $ when_ bad ignore
Just ()

when_ is just like when, except that it executes the body if the condition fails, rather than based on a Bool value.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ unless_ bad ignore
Nothing
>>> runCond "foo.hs" $ unless_ good ignore
Just ()

Check whether at least one of the given conditions is true. This is a synonym for asum.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ or_ [bad, good]
Just ()
>>> runCond "foo.hs" $ or_ [bad]
Nothing

Check that all of the given conditions are true. This is a synonym for sequence_.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ and_ [bad, good]
Nothing
>>> runCond "foo.hs" $ and_ [good]
Just ()

not_ inverts the meaning of the given predicate.

>>> let good = guard_ (== "foo.hs") :: Cond String ()
>>> let bad  = guard_ (== "foo.hi") :: Cond String ()
>>> runCond "foo.hs" $ not_ bad >> return "Success"
Just "Success"
>>> runCond "foo.hs" $ not_ good >> return "Shouldn't reach here"
Nothing

recurse changes the recursion predicate for any child elements. For example, the following file-finding predicate looks for all *.hs files, but under any .git directory looks only for a file named config:

if_ (name_ ".git" >> directory)
    (ignore >> recurse (name_ "config"))
    (glob "*.hs")

NOTE: If this code had used recurse (glob "*.hs")) instead in the else case, it would have meant that .git is only looked for at the top-level of the search (i.e., the top-most element).