-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Combinators for Strategic Programming
--   
--   The Kansas University Rewrite Engine (KURE) is a DSL for strategic
--   rewriting. KURE shares concepts with Stratego, but unlike Stratego,
--   KURE is strongly typed. KURE is similar to StrategyLib, but has a
--   lightweight generic traversal mechanism using type families rather
--   than SYB. The basic transformation functionality can be found in
--   <a>Language.KURE.Translate</a>, and the traversal functionality can be
--   found in <a>Language.KURE.Walker</a>. Several basic examples of using
--   KURE are provided in the source-code bundle. For a larger example, see
--   the HERMIT package.
@package kure
@version 2.4.2


-- | This module provides various monadic and arrow combinators that are
--   particularly useful when working with translations.
module Language.KURE.Combinators

-- | <a>Monad</a>s with a catch for <a>fail</a>. The following law is
--   expected to hold:
--   
--   <pre>
--   fail msg `catchM` f == f msg
--   </pre>
class Monad m => MonadCatch m
catchM :: MonadCatch m => m a -> (String -> m a) -> m a

-- | A monadic catch that ignores the error message.
(<<+) :: MonadCatch m => m a -> m a -> m a

-- | Select the first monadic computation that succeeds, discarding any
--   thereafter.
catchesM :: MonadCatch m => [m a] -> m a

-- | Catch a failing monadic computation, making it succeed with a constant
--   value.
tryM :: MonadCatch m => a -> m a -> m a

-- | Catch a failing monadic computation, making it succeed with
--   <a>mempty</a>.
mtryM :: (MonadCatch m, Monoid a) => m a -> m a

-- | Catch a failing monadic computation, making it succeed with an error
--   message.
attemptM :: MonadCatch m => m a -> m (Either String a)

-- | Determine if a monadic computation succeeds.
testM :: MonadCatch m => m a -> m Bool

-- | Fail if the <a>Monad</a> succeeds; succeed with <tt>()</tt> if it
--   fails.
notM :: MonadCatch m => m a -> m ()

-- | Modify the error message of a failing monadic computation. Successful
--   computations are unaffected.
modFailMsg :: MonadCatch m => (String -> String) -> m a -> m a

-- | Set the error message of a failing monadic computation. Successful
--   computations are unaffected.
setFailMsg :: MonadCatch m => String -> m a -> m a

-- | Add a prefix to the error message of a failing monadic computation.
--   Successful computations are unaffected.
prefixFailMsg :: MonadCatch m => String -> m a -> m a

-- | Use the given error message whenever a monadic pattern match failure
--   occurs.
withPatFailMsg :: MonadCatch m => String -> m a -> m a

-- | Similar to <a>guard</a>, but invokes <a>fail</a> rather than
--   <a>mzero</a>.
guardMsg :: Monad m => Bool -> String -> m ()

-- | As <a>guardMsg</a>, but with a default error message.
guardM :: Monad m => Bool -> m ()

-- | if-then-else lifted over a monadic predicate.
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | If the monadic predicate holds then perform the monadic action, else
--   fail.
whenM :: Monad m => m Bool -> m a -> m a

-- | If the monadic predicate holds then fail, else perform the monadic
--   action.
unlessM :: Monad m => m Bool -> m a -> m a

-- | <a>Category</a>s with failure and catching. The following law is
--   expected to hold:
--   
--   <pre>
--   failT msg `catchT` f == f msg
--   </pre>
class Category arr => CategoryCatch arr
failT :: CategoryCatch arr => String -> arr a b
catchT :: CategoryCatch arr => arr a b -> (String -> arr a b) -> arr a b

-- | Left-biased choice.
(<+) :: CategoryCatch arr => arr a b -> arr a b -> arr a b

-- | Look at the argument to the <a>Arrow</a> before choosing which
--   <a>Arrow</a> to use.
readerT :: ArrowApply arr => (a -> arr a b) -> arr a b

-- | Look at the argument to an <a>Arrow</a>, and choose to be either the
--   identity arrow or a failure.
acceptR :: (CategoryCatch arr, ArrowApply arr) => (a -> Bool) -> String -> arr a a

-- | Look at the argument to an <a>Arrow</a>, and choose to be either the
--   identity arrow or a failure. This is a generalisation of
--   <a>acceptR</a> to any <a>Arrow</a>.
accepterR :: (CategoryCatch arr, ArrowApply arr) => arr a Bool -> String -> arr a a

-- | Catch a failing <a>CategoryCatch</a>, making it into an identity.
tryR :: CategoryCatch arr => arr a a -> arr a a

-- | Catch a failing <a>Arrow</a>, making it succeed with a Boolean flag.
--   Useful when defining <a>anyR</a> instances.
attemptR :: (CategoryCatch arr, Arrow arr) => arr a a -> arr a (Bool, a)

-- | Makes an <a>Arrow</a> fail if the result value equals the argument
--   value.
changedR :: (CategoryCatch arr, ArrowApply arr, Eq a) => arr a a -> arr a a

-- | Repeat a <a>CategoryCatch</a> until it fails, then return the result
--   before the failure. Requires at least the first attempt to succeed.
repeatR :: CategoryCatch arr => arr a a -> arr a a

-- | Attempt two <a>Arrow</a>s in sequence, succeeding if one or both
--   succeed.
(>+>) :: (CategoryCatch arr, ArrowApply arr) => arr a a -> arr a a -> arr a a

-- | Sequence a list of <a>Arrow</a>s, succeeding if any succeed.
orR :: (CategoryCatch arr, ArrowApply arr) => [arr a a] -> arr a a

-- | Sequence a list of <a>Category</a>s, succeeding if all succeed.
andR :: Category arr => [arr a a] -> arr a a

-- | Select the first <a>CategoryCatch</a> that succeeds, discarding any
--   thereafter.
catchesT :: CategoryCatch arr => [arr a b] -> arr a b

-- | Apply a pure function to the result of an <a>Arrow</a>.
result :: Arrow arr => (b -> c) -> arr a b -> arr a c

-- | Apply a pure function to the argument to an <a>Arrow</a>.
argument :: Arrow arr => (a -> b) -> arr b c -> arr a c

-- | Apply an <a>Arrow</a> to the first element of a pair, discarding the
--   second element.
toFst :: Arrow arr => arr a b -> arr (a, x) b

-- | Apply an <a>Arrow</a> to the second element of a pair, discarding the
--   first element.
toSnd :: Arrow arr => arr a b -> arr (x, a) b

-- | A pure <a>Arrow</a> that swaps the elements of a pair.
swap :: Arrow arr => arr (a, b) (b, a)

-- | A pure <a>Arrow</a> that duplicates its argument.
fork :: Arrow arr => arr a (a, a)

-- | Tag the result of an <a>Arrow</a> with its argument.
forkFirst :: Arrow arr => arr a b -> arr a (b, a)

-- | Tag the result of an <a>Arrow</a> with its argument.
forkSecond :: Arrow arr => arr a b -> arr a (a, b)

-- | An arrow with a constant result.
constant :: Arrow arr => b -> arr a b


-- | This module defines the main KURE types: <a>Translate</a>,
--   <a>Rewrite</a> and <a>Lens</a>. <a>Rewrite</a> is just a special case
--   of <a>Translate</a>, and so any function that operates on
--   <a>Translate</a> is also applicable to <a>Rewrite</a>.
--   
--   This module also contains <a>Translate</a> instance declarations for
--   the <a>Monad</a> and <a>Arrow</a> type-class families. Given these
--   instances, many of the desirable combinators over <a>Translate</a> and
--   <a>Rewrite</a> are special cases of existing monadic or arrow
--   combinators. <a>Language.KURE.Combinators</a> provides some additional
--   combinators that aren't in the standard libraries.
module Language.KURE.Translate

-- | An abstract representation of a transformation from a value of type
--   <tt>a</tt> in a context <tt>c</tt> to a monadic value of type <tt>m
--   b</tt>. The <a>Translate</a> type is the basis of the entire KURE
--   library.
data Translate c m a b

-- | A <a>Translate</a> that shares the same source and target type.
type Rewrite c m a = Translate c m a a

-- | Apply a <a>Translate</a> to a value and its context.
apply :: Translate c m a b -> c -> a -> m b

-- | The primitive way of building a <a>Translate</a>.
translate :: (c -> a -> m b) -> Translate c m a b

-- | The primitive way of building a <a>Rewrite</a>.
rewrite :: (c -> a -> m a) -> Rewrite c m a

-- | Build a <a>Translate</a> that doesn't depend on the context.
contextfreeT :: (a -> m b) -> Translate c m a b

-- | Build a constant <a>Translate</a> from a monadic computation.
constT :: m b -> Translate c m a b

-- | Extract the current context.
contextT :: Monad m => Translate c m a c

-- | Expose the current context and value.
exposeT :: Monad m => Translate c m a (c, a)

-- | Map a <a>Translate</a> over a list.
mapT :: Monad m => Translate c m a b -> Translate c m [a] [b]

-- | An identity <a>Rewrite</a> with side-effects.
sideEffectR :: Monad m => (c -> a -> m ()) -> Rewrite c m a

-- | An undirected <a>Translate</a>.
data BiTranslate c m a b

-- | A <a>BiTranslate</a> that shares the same source and target type.
type BiRewrite c m a = BiTranslate c m a a

-- | Construct a <a>BiTranslate</a> from two opposite <a>Translate</a>s.
bidirectional :: Translate c m a b -> Translate c m b a -> BiTranslate c m a b

-- | Extract the foreward <a>Translate</a> from a <a>BiTranslate</a>.
forewardT :: BiTranslate c m a b -> Translate c m a b

-- | Extract the backward <a>Translate</a> from a <a>BiTranslate</a>.
backwardT :: BiTranslate c m a b -> Translate c m b a

-- | Try the <a>BiRewrite</a> forewards, then backwards if that fails.
--   Useful when you know which rule you want to apply, but not which
--   direction to apply it in.
whicheverR :: MonadCatch m => BiRewrite c m a -> Rewrite c m a

-- | Invert the forewards and backwards directions of a <a>BiTranslate</a>.
invert :: BiTranslate c m a b -> BiTranslate c m b a

-- | A <a>Lens</a> is a way to focus on a sub-structure of type <tt>b</tt>
--   from a structure of type <tt>a</tt>.
data Lens c m a b

-- | The primitive way of building a <a>Lens</a>. If the unfocussing
--   function is applied to the value focussed on then it should succeed,
--   and produce the same value as the original argument (of type
--   <tt>a</tt>).
lens :: Translate c m a ((c, b), b -> m a) -> Lens c m a b

-- | Convert a <a>Lens</a> into a <a>Translate</a> that produces a
--   sub-structure (and its context) and an unfocussing function.
lensT :: Lens c m a b -> Translate c m a ((c, b), b -> m a)

-- | Apply a <a>Rewrite</a> at a point specified by a <a>Lens</a>.
focusR :: Monad m => Lens c m a b -> Rewrite c m b -> Rewrite c m a

-- | Apply a <a>Translate</a> at a point specified by a <a>Lens</a>.
focusT :: Monad m => Lens c m a b -> Translate c m b d -> Translate c m a d

-- | Check if the focusing succeeds, and additionally whether unfocussing
--   from an unchanged value would succeed.
testLensT :: MonadCatch m => Lens c m a b -> Translate c m a Bool

-- | Construct a <a>Lens</a> from a <a>BiTranslate</a>.
bidirectionalL :: Monad m => BiTranslate c m a b -> Lens c m a b

-- | Construct a <a>Lens</a> from two pure functions.
pureL :: Monad m => (a -> b) -> (b -> a) -> Lens c m a b
instance MonadCatch m => CategoryCatch (Lens c m)
instance Monad m => Category (Lens c m)
instance Monad m => Category (BiTranslate c m)
instance (Monad m, Monoid b) => Monoid (Translate c m a b)
instance Monad m => ArrowApply (Translate c m)
instance MonadPlus m => ArrowPlus (Translate c m)
instance MonadPlus m => ArrowZero (Translate c m)
instance Monad m => Arrow (Translate c m)
instance MonadCatch m => CategoryCatch (Translate c m)
instance Monad m => Category (Translate c m)
instance MonadPlus m => MonadPlus (Translate c m a)
instance MonadCatch m => MonadCatch (Translate c m a)
instance Monad m => Monad (Translate c m a)
instance Alternative m => Alternative (Translate c m a)
instance Applicative m => Applicative (Translate c m a)
instance Functor m => Functor (Translate c m a)


-- | This module provides a type class for injective functions (and their
--   retractions), and some useful interactions with <a>Translate</a>.
--   
--   A particularly useful instance of <a>Injection</a> is from <tt>a</tt>
--   to <tt>Generic</tt> <tt>a</tt>, and that case is the primary purpose
--   of most of these combinators.
module Language.KURE.Injection

-- | A class of injective functions from <tt>a</tt> to <tt>b</tt>, and
--   their retractions. The following law is expected to hold:
--   
--   <pre>
--   retract (inject a) == Just a
--   </pre>
class Injection a b
inject :: Injection a b => a -> b
retract :: Injection a b => b -> Maybe a

-- | Injects a value and lifts it into a <a>Monad</a>.
injectM :: (Monad m, Injection a a') => a -> m a'

-- | Retracts a value and lifts it into a <a>MonadCatch</a>, with the
--   possibility of failure.
retractM :: (MonadCatch m, Injection a a') => a' -> m a

-- | Lifted <a>inject</a>.
injectT :: (Monad m, Injection a a') => Translate c m a a'

-- | Lifted <a>retract</a>, the <a>Translate</a> fails if the retraction
--   fails.
retractT :: (MonadCatch m, Injection a a') => Translate c m a' a

-- | Convert a <a>Translate</a> over an injected value into a
--   <a>Translate</a> over a non-injected value.
extractT :: (Monad m, Injection a a') => Translate c m a' b -> Translate c m a b

-- | Promote a <a>Translate</a> over a value into a <a>Translate</a> over
--   an injection of that value, (failing if that injected value cannot be
--   retracted).
promoteT :: (MonadCatch m, Injection a a') => Translate c m a b -> Translate c m a' b

-- | As <a>promoteT</a>, but takes a custom error message to use if
--   promotion fails.
promoteWithFailMsgT :: (MonadCatch m, Injection a a') => String -> Translate c m a b -> Translate c m a' b

-- | Convert a <a>Rewrite</a> over an injected value into a <a>Rewrite</a>
--   over a retraction of that value, (failing if that injected value
--   cannot be retracted).
extractR :: (MonadCatch m, Injection a a') => Rewrite c m a' -> Rewrite c m a

-- | Promote a <a>Rewrite</a> into over a value into a <a>Rewrite</a> over
--   an injection of that value, (failing if that injected value cannot be
--   retracted).
promoteR :: (MonadCatch m, Injection a a') => Rewrite c m a -> Rewrite c m a'

-- | As <a>extractR</a>, but takes a custom error message to use if
--   extraction fails.
extractWithFailMsgR :: (MonadCatch m, Injection a a') => String -> Rewrite c m a' -> Rewrite c m a

-- | As <a>promoteR</a>, but takes a custom error message to use if
--   promotion fails.
promoteWithFailMsgR :: (MonadCatch m, Injection a a') => String -> Rewrite c m a -> Rewrite c m a'

-- | A <a>Lens</a> to the injection of a value.
injectL :: (MonadCatch m, Injection a a') => Lens c m a a'

-- | A <a>Lens</a> to the retraction of a value.
retractL :: (MonadCatch m, Injection a a') => Lens c m a' a
instance Injection a (Maybe a)
instance Injection a a


-- | This module provides combinators that traverse a tree.
--   
--   Note that all traversals take place on the node, its children, or its
--   descendents. Deliberately, there is no mechanism for "ascending" the
--   tree.
module Language.KURE.Walker

-- | A <a>Node</a> is any node in the tree that you wish to be able to
--   traverse.
class (Injection a (Generic a), Generic a ~ Generic (Generic a)) => Node a where type family Generic a :: *
numChildren :: Node a => a -> Int

-- | Lifted version of <a>numChildren</a>.
numChildrenT :: (Monad m, Node a) => Translate c m a Int

-- | Check if a <a>Node</a> has a child of the specified index.
hasChild :: Node a => Int -> a -> Bool

-- | Lifted version of <a>hasChild</a>.
hasChildT :: (Monad m, Node a) => Int -> Translate c m a Bool

-- | <a>Walker</a> captures the ability to walk over a tree of
--   <a>Node</a>s, using a specific context <tt>c</tt> and a
--   <a>MonadCatch</a> <tt>m</tt>.
--   
--   Minimal complete definition: <a>childL</a>.
--   
--   Default definitions are provided for <a>allT</a>, <a>oneT</a>,
--   <a>allR</a>, <a>anyR</a> and <a>oneR</a>, but they may be overridden
--   for efficiency. For small numbers of interesting children this will
--   not be an issue, but for a large number, say for a list of children,
--   it may be.
class (MonadCatch m, Node a) => Walker c m a where allT t = modFailMsg ("allT failed: " ++) $ do { n <- numChildrenT; mconcat (childrenT n (const t)) } oneT t = setFailMsg "oneT failed" $ do { n <- numChildrenT; catchesT (childrenT n (const t)) } allR r = modFailMsg ("allR failed: " ++) $ do { n <- numChildrenT; andR (childrenR n (const r)) } anyR r = setFailMsg "anyR failed" $ do { n <- numChildrenT; orR (childrenR n (const r)) } oneR r = setFailMsg "oneR failed" $ do { n <- numChildrenT; catchesT (childrenR n (const r)) }
childL :: Walker c m a => Int -> Lens c m a (Generic a)
allT :: (Walker c m a, Monoid b) => Translate c m (Generic a) b -> Translate c m a b
oneT :: Walker c m a => Translate c m (Generic a) b -> Translate c m a b
allR :: Walker c m a => Rewrite c m (Generic a) -> Rewrite c m a
anyR :: Walker c m a => Rewrite c m (Generic a) -> Rewrite c m a
oneR :: Walker c m a => Rewrite c m (Generic a) -> Rewrite c m a

-- | Apply a <a>Rewrite</a> to a specified child.
childR :: Walker c m a => Int -> Rewrite c m (Generic a) -> Rewrite c m a

-- | Apply a <a>Rewrite</a> in a top-down manner, succeeding if they all
--   succeed.
alltdR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> in a bottom-up manner, succeeding if they all
--   succeed.
allbuR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> twice, in a top-down and bottom-up way, using
--   one single tree traversal, succeeding if they all succeed.
allduR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> in a top-down manner, succeeding if any
--   succeed.
anytdR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> in a bottom-up manner, succeeding if any
--   succeed.
anybuR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> twice, in a top-down and bottom-up way, using
--   one single tree traversal, succeeding if any succeed.
anyduR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> to the first <a>Node</a> for which it can
--   succeed, in a top-down traversal.
onetdR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Rewrite</a> to the first <a>Node</a> for which it can
--   succeed, in a bottom-up traversal.
onebuR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Attempt to apply a <a>Rewrite</a> in a top-down manner, pruning at
--   successful rewrites.
prunetdR :: (Walker c m a, a ~ Generic a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | A fixed-point traveral, starting with the innermost term.
innermostR :: (Walker c m a, Generic a ~ a) => Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Translate</a> to a specified child.
childT :: Walker c m a => Int -> Translate c m (Generic a) b -> Translate c m a b

-- | Fold a tree in a top-down manner, using a single <a>Translate</a> for
--   each <a>Node</a>.
foldtdT :: (Walker c m a, Monoid b, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | Fold a tree in a bottom-up manner, using a single <a>Translate</a> for
--   each <a>Node</a>.
foldbuT :: (Walker c m a, Monoid b, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | Apply a <a>Translate</a> to the first <a>Node</a> for which it can
--   succeed, in a top-down traversal.
onetdT :: (Walker c m a, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | Apply a <a>Translate</a> to the first <a>Node</a> for which it can
--   succeed, in a bottom-up traversal.
onebuT :: (Walker c m a, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | Attempt to apply a <a>Translate</a> in a top-down manner, pruning at
--   successes.
prunetdT :: (Walker c m a, Monoid b, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | An always successful top-down fold, replacing failures with
--   <a>mempty</a>.
crushtdT :: (Walker c m a, Monoid b, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | An always successful bottom-up fold, replacing failures with
--   <a>mempty</a>.
crushbuT :: (Walker c m a, Monoid b, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | An always successful traversal that collects the results of all
--   successful applications of a <a>Translate</a> in a list.
collectT :: (Walker c m a, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) [b]

-- | Like <a>collectT</a>, but does not traverse below successes.
collectPruneT :: (Walker c m a, a ~ Generic a) => Translate c m (Generic a) b -> Translate c m (Generic a) [b]

-- | A path from the root.
data AbsolutePath

-- | The (empty) <a>AbsolutePath</a> to the root.
rootAbsPath :: AbsolutePath

-- | Extend an <a>AbsolutePath</a> by one descent.
extendAbsPath :: Int -> AbsolutePath -> AbsolutePath

-- | Contexts that are instances of <a>PathContext</a> contain the current
--   <a>AbsolutePath</a>. Any user-defined combinators (typically
--   <a>childL</a> and congruence combinators) should update the
--   <a>AbsolutePath</a> using <a>extendAbsPath</a>.
class PathContext c
contextPath :: PathContext c => c -> AbsolutePath

-- | Find the <a>AbsolutePath</a> to the current <a>Node</a>.
absPathT :: (PathContext c, Monad m) => Translate c m a AbsolutePath

-- | A path is a route to descend the tree from an arbitrary <a>Node</a>.
type Path = [Int]

-- | Convert an <a>AbsolutePath</a> into a <a>Path</a> starting at the
--   root.
rootPath :: AbsolutePath -> Path

-- | Find the <a>Path</a>s to every <a>Node</a> that satisfies the
--   predicate.
pathsToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) [Path]

-- | Find the <a>Path</a> to the first <a>Node</a> that satisfies the
--   predicate (in a pre-order traversal).
onePathToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) Path

-- | Find the <a>Path</a> to the first descendent <a>Node</a> that
--   satisfies the predicate (in a pre-order traversal).
oneNonEmptyPathToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) Path

-- | Find the <a>Path</a>s to every <a>Node</a> that satisfies the
--   predicate, ignoring <a>Node</a>s below successes.
prunePathsToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) [Path]

-- | Find the <a>Path</a> to the <a>Node</a> that satisfies the predicate,
--   failing if that does not uniquely identify a <a>Node</a>.
uniquePathToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) Path

-- | Build a <a>Path</a> to the <a>Node</a> that satisfies the predicate,
--   failing if that does not uniquely identify a <a>Node</a> (ignoring
--   <a>Node</a>s below successes).
uniquePrunePathToT :: (PathContext c, Walker c m a, a ~ Generic a) => (Generic a -> Bool) -> Translate c m (Generic a) Path

-- | Construct a <a>Lens</a> by following a <a>Path</a>.
pathL :: (Walker c m a, a ~ Generic a) => Path -> Lens c m (Generic a) (Generic a)

-- | Construct a <a>Lens</a> that points to the last <a>Node</a> at which
--   the <a>Path</a> can be followed.
exhaustPathL :: (Walker c m a, a ~ Generic a) => Path -> Lens c m (Generic a) (Generic a)

-- | Repeat as many iterations of the <a>Path</a> as possible.
repeatPathL :: (Walker c m a, a ~ Generic a) => Path -> Lens c m (Generic a) (Generic a)

-- | Build a <a>Lens</a> from the root to a point specified by an
--   <a>AbsolutePath</a>.
rootL :: (Walker c m a, a ~ Generic a) => AbsolutePath -> Lens c m (Generic a) (Generic a)

-- | Apply a <a>Rewrite</a> at a point specified by a <a>Path</a>.
pathR :: (Walker c m a, a ~ Generic a) => Path -> Rewrite c m (Generic a) -> Rewrite c m (Generic a)

-- | Apply a <a>Translate</a> at a point specified by a <a>Path</a>.
pathT :: (Walker c m a, a ~ Generic a) => Path -> Translate c m (Generic a) b -> Translate c m (Generic a) b

-- | Check if it is possible to construct a <a>Lens</a> along this path
--   from the current <a>Node</a>.
testPathT :: (Walker c m a, a ~ Generic a) => Path -> Translate c m a Bool
instance PathContext AbsolutePath
instance Show AbsolutePath


-- | This module contains various utilities that can be useful to users of
--   KURE, but are not essential.
module Language.KURE.Utilities

-- | A basic error <a>Monad</a>. KURE users may use either <a>KureMonad</a>
--   or their own <a>Monad</a>(s).
data KureMonad a

-- | Eliminator for <a>KureMonad</a>.
runKureMonad :: (a -> b) -> (String -> b) -> KureMonad a -> b

-- | Get the value from a <a>KureMonad</a>, providing a function to handle
--   the error case.
fromKureMonad :: (String -> a) -> KureMonad a -> a

-- | A standard error message for when the child index is out of bounds.
missingChild :: Int -> String
allTgeneric :: (Walker c m a, Monoid b) => Translate c m (Generic a) b -> c -> a -> m b
oneTgeneric :: Walker c m a => Translate c m (Generic a) b -> c -> a -> m b
allRgeneric :: Walker c m a => Rewrite c m (Generic a) -> c -> a -> m (Generic a)
anyRgeneric :: Walker c m a => Rewrite c m (Generic a) -> c -> a -> m (Generic a)
oneRgeneric :: Walker c m a => Rewrite c m (Generic a) -> c -> a -> m (Generic a)
childLgeneric :: Walker c m a => Int -> c -> a -> m ((c, Generic a), Generic a -> m (Generic a))
attemptAny2 :: Monad m => (a1 -> a2 -> r) -> m (Bool, a1) -> m (Bool, a2) -> m r
attemptAny3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m (Bool, a1) -> m (Bool, a2) -> m (Bool, a3) -> m r
attemptAny4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m (Bool, a1) -> m (Bool, a2) -> m (Bool, a3) -> m (Bool, a4) -> m r
attemptAnyN :: Monad m => ([a] -> b) -> [m (Bool, a)] -> m b
attemptAny1N :: Monad m => (a1 -> [a2] -> r) -> m (Bool, a1) -> [m (Bool, a2)] -> m r

-- | Return the monadic result of a <a>Translate</a> and pair it with the
--   argument.
withArgumentT :: Monad m => Translate c m a b -> Translate c m a (m b, a)
attemptOne2 :: MonadCatch m => (a -> b -> r) -> m (m a, a) -> m (m b, b) -> m r
attemptOne3 :: MonadCatch m => (a -> b -> c -> r) -> m (m a, a) -> m (m b, b) -> m (m c, c) -> m r
attemptOne4 :: MonadCatch m => (a -> b -> c -> d -> r) -> m (m a, a) -> m (m b, b) -> m (m c, c) -> m (m d, d) -> m r
attemptOneN :: MonadCatch m => ([a] -> r) -> [m (m a, a)] -> m r
attemptOne1N :: MonadCatch m => (a -> [b] -> r) -> m (m a, a) -> [m (m b, b)] -> m r
childLaux :: (MonadCatch m, Node b) => (c, b) -> (b -> a) -> ((c, Generic b), Generic b -> m a)
childL0of1 :: (MonadCatch m, Node b) => (b -> a) -> (c, b) -> ((c, Generic b), Generic b -> m a)
childL0of2 :: (MonadCatch m, Node b0) => (b0 -> b1 -> a) -> (c, b0) -> b1 -> ((c, Generic b0), Generic b0 -> m a)
childL1of2 :: (MonadCatch m, Node b1) => (b0 -> b1 -> a) -> b0 -> (c, b1) -> ((c, Generic b1), Generic b1 -> m a)
childL0of3 :: (MonadCatch m, Node b0) => (b0 -> b1 -> b2 -> a) -> (c, b0) -> b1 -> b2 -> ((c, Generic b0), Generic b0 -> m a)
childL1of3 :: (MonadCatch m, Node b1) => (b0 -> b1 -> b2 -> a) -> b0 -> (c, b1) -> b2 -> ((c, Generic b1), Generic b1 -> m a)
childL2of3 :: (MonadCatch m, Node b2) => (b0 -> b1 -> b2 -> a) -> b0 -> b1 -> (c, b2) -> ((c, Generic b2), Generic b2 -> m a)
childL0of4 :: (MonadCatch m, Node b0) => (b0 -> b1 -> b2 -> b3 -> a) -> (c, b0) -> b1 -> b2 -> b3 -> ((c, Generic b0), Generic b0 -> m a)
childL1of4 :: (MonadCatch m, Node b1) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> (c, b1) -> b2 -> b3 -> ((c, Generic b1), Generic b1 -> m a)
childL2of4 :: (MonadCatch m, Node b2) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> b1 -> (c, b2) -> b3 -> ((c, Generic b2), Generic b2 -> m a)
childL3of4 :: (MonadCatch m, Node b3) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> b1 -> b2 -> (c, b3) -> ((c, Generic b3), Generic b3 -> m a)
childLMofN :: (MonadCatch m, Node b) => Int -> ([b] -> a) -> [(c, b)] -> ((c, Generic b), Generic b -> m a)
instance Eq a => Eq (KureMonad a)
instance Show a => Show (KureMonad a)
instance Applicative KureMonad
instance Functor KureMonad
instance MonadCatch KureMonad
instance Monad KureMonad


-- | This is the main import module for KURE, which exports all the major
--   components. The basic transformation functionality can be found in
--   <a>Language.KURE.Translate</a>, and the traversal functionality can be
--   found in <a>Language.KURE.Walker</a>.
--   
--   Note that <a>Language.KURE.Injection</a> and
--   <a>Language.KURE.Utilities</a> are not exported here, but can be
--   imported seperately.
module Language.KURE