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


-- | Combinators for Strategic Programming
--   
--   The Kansas University Rewrite Engine (KURE) is a domain-specific
--   language for strategic rewriting. KURE was inspired by Stratego and
--   StrategyLib, and has similarities with Scrap Your Boilerplate and
--   Uniplate.
--   
--   The basic transformation functionality can be found in
--   <a>Language.KURE.Transform</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 larger examples, see
--   the HERMIT or HTML-KURE packages.
--   
--   You can read about KURE in the following article:
--   
--   The Kansas University Rewrite Engine: A Haskell-Embedded Strategic
--   Programming Language with Custom Closed Universes. Neil Sculthorpe,
--   Nicolas Frisby and Andy Gill. Journal of Functional Programming.
--   Cambridge University Press, 2014.
--   <a>http://www.cs.swan.ac.uk/~csnas/papers_and_talks/kure.pdf</a>
@package kure
@version 2.16.4


-- | This module provides some utility arrow routing combinators.
module Language.KURE.Combinators.Arrow

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

-- | Apply a pure function to the argument to an arrow.
argument :: Arrow bi => (a -> b) -> bi b c -> bi a c

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

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

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

-- | A pure arrow that duplicates its argument.
fork :: Arrow bi => bi a (a, a)

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

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

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

-- | Sequence (from left to right) a collection of <a>Category</a>s.
serialise :: (Foldable f, Category bi) => f (bi a a) -> bi a a

-- | Apply a collection of arrows to the same input, combining their
--   results in a monoid.
parallelise :: (Foldable f, Arrow bi, Monoid b) => f (bi a b) -> bi a b


-- | This module provides conditional monadic combinators.
module Language.KURE.Combinators.Monad

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

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

-- | As <a>guardMsg</a>, but with an <tt>m Bool</tt> as argument.
guardMsgM :: Monad m => m Bool -> String -> 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


-- | This module provides classes for catch-like operations on
--   <a>Monad</a>s.
module Language.KURE.MonadCatch

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

-- | <a>KureM</a> is the minimal structure that can be an instance of
--   <a>MonadCatch</a>. The KURE user is free to either use <a>KureM</a> or
--   provide their own monad. <a>KureM</a> is essentially the same as
--   <a>Either</a> <a>String</a>, except that it supports a
--   <a>MonadCatch</a> instance which <a>Either</a> <a>String</a> does not
--   (because its <a>fail</a> method calls <a>error</a>) A major advantage
--   of this is that monadic pattern match failures are caught safely.
data KureM a

-- | Eliminator for <a>KureM</a>.
runKureM :: (a -> b) -> (String -> b) -> KureM a -> b

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

-- | Lift a <a>KureM</a> computation to any other monad.
liftKureM :: Monad m => KureM a -> m a

-- | Lift a computation from the <a>IO</a> monad, catching failures in the
--   target monad.
liftAndCatchIO :: (MonadCatch m, MonadIO m) => IO 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 :: (Foldable f, MonadCatch m) => f (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 monadic computation 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
instance Eq a => Eq (KureM a)
instance Show a => Show (KureM a)
instance MonadCatch IO
instance Applicative KureM
instance Functor KureM
instance MonadCatch KureM
instance Monad KureM


-- | This module defines <a>Transform</a> and <a>Rewrite</a>, the main KURE
--   types. <a>Rewrite</a> is just a special case of <a>Transform</a>, and
--   so any function that operates on <a>Transform</a> is also applicable
--   to <a>Rewrite</a>.
--   
--   <a>Transform</a> is an instance of the <a>Monad</a> and <a>Arrow</a>
--   type-class families, and consequently many of the desirable
--   combinators over <a>Transform</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.Transform

-- | 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>Transform</a> type is the basis of the entire KURE
--   library.
data Transform c m a b

-- | A deprecated synonym for <a>Transform</a>.
type Translate c m a b = Transform c m a b

-- | A transformation that shares the same source and target type.
type Rewrite c m a = Transform c m a a

-- | Apply a transformation to a value and its context.
applyT :: Transform c m a b -> c -> a -> m b

-- | Apply a rewrite to a value and its context.
applyR :: Rewrite c m a -> c -> a -> m a

-- | A deprecated synonym for <a>applyT</a>.

-- | <i>Deprecated: Please use <a>applyT</a> instead. </i>
apply :: Transform c m a b -> c -> a -> m b

-- | The primitive way of building a transformation.
transform :: (c -> a -> m b) -> Transform c m a b

-- | A deprecated synonym for <a>transform</a>.

-- | <i>Deprecated: Please use <a>transform</a> instead. </i>
translate :: (c -> a -> m b) -> Translate c m a b

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

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

-- | Build a <a>Transform</a> that doesn't depend on the value.
contextonlyT :: (c -> m b) -> Transform c m a b

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

-- | Build a <a>Transform</a> that doesn't perform any monadic effects.
effectfreeT :: Monad m => (c -> a -> b) -> Transform c m a b
instance (Monad m, Monoid b) => Monoid (Transform c m a b)
instance Monad m => ArrowApply (Transform c m)
instance MonadPlus m => ArrowPlus (Transform c m)
instance MonadPlus m => ArrowZero (Transform c m)
instance Monad m => Arrow (Transform c m)
instance Monad m => Category (Transform c m)
instance MonadIO m => MonadIO (Transform c m a)
instance MonadPlus m => MonadPlus (Transform c m a)
instance MonadCatch m => MonadCatch (Transform c m a)
instance Monad m => Monad (Transform c m a)
instance Alternative m => Alternative (Transform c m a)
instance Applicative m => Applicative (Transform c m a)
instance Functor m => Functor (Transform c m a)


-- | This module provides a type class for injective functions (and their
--   projections), and some useful interactions with <a>Transform</a>.
module Language.KURE.Injection

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

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

-- | Projects a value and lifts it into a <a>Monad</a>, with the
--   possibility of failure.
projectM :: (Monad m, Injection a g) => g -> m a

-- | As <a>projectM</a>, but takes a custom error message to use if
--   projection fails.
projectWithFailMsgM :: (Monad m, Injection a g) => String -> g -> m a

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

-- | Lifted <a>project</a>, the transformation fails if the projection
--   fails.
projectT :: (Monad m, Injection a g) => Transform c m g a

-- | Convert a transformation over an injected value into a transformation
--   over a non-injected value.
extractT :: (Monad m, Injection a g) => Transform c m g b -> Transform c m a b

-- | Promote a transformation over a value into a transformation over an
--   injection of that value, (failing if that injected value cannot be
--   projected).
promoteT :: (Monad m, Injection a g) => Transform c m a b -> Transform c m g b

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

-- | Convert a rewrite over an injected value into a rewrite over a
--   projection of that value, (failing if that injected value cannot be
--   projected).
extractR :: (Monad m, Injection a g) => Rewrite c m g -> Rewrite c m a

-- | Promote a rewrite over a value into a rewrite over an injection of
--   that value, (failing if that injected value cannot be projected).
promoteR :: (Monad m, Injection a g) => Rewrite c m a -> Rewrite c m g

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

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


-- | A bi-directional transformation is a transformation that can be
--   applied in either direction.
module Language.KURE.BiTransform

-- | An undirected <a>Transform</a>.
data BiTransform c m a b

-- | A deprecated synonym for <a>BiTranslate</a>.
type BiTranslate c m a b = BiTransform c m a b

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

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

-- | Extract the forward <a>Transform</a> from a <a>BiTransform</a>.
forwardT :: BiTransform c m a b -> Transform c m a b

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

-- | Try the <a>BiRewrite</a> forwards, 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 forwards and backwards directions of a <a>BiTransform</a>.
invertBiT :: BiTransform c m a b -> BiTransform c m b a

-- | Perform the argument transformation before <i>either</i> direction of
--   the bidirectional rewrite.
beforeBiR :: Monad m => Transform c m a b -> (b -> BiRewrite c m a) -> BiRewrite c m a

-- | Apply the argument rewrite to the result of <i>either</i> direction of
--   the bidirectional rewrite.
afterBiR :: Monad m => BiRewrite c m a -> Rewrite c m a -> BiRewrite c m a
instance Monad m => Category (BiTransform c m)


-- | This module provides a variety of combinators over <a>Transform</a>
--   and <a>Rewrite</a>.
module Language.KURE.Combinators.Transform

-- | The identity rewrite.
idR :: Monad m => Rewrite c m a

-- | An always successful transformation.
successT :: Monad m => Transform c m a ()

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

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

-- | Lift a transformation to operate on a derived context.
liftContext :: (c -> c') -> Transform c' m a b -> Transform c m a b

-- | Look at the argument to the transformation before choosing which
--   <a>Transform</a> to use.
readerT :: (a -> Transform c m a b) -> Transform c m a b

-- | Convert the monadic result of a transformation into a result in
--   another monad.
resultT :: (m b -> n d) -> Transform c m a b -> Transform c n a d

-- | Attempt each trransformation until one succeeds, then return that
--   result and discard the rest of the transformations.
catchesT :: MonadCatch m => [Transform c m a b] -> Transform c m a b

-- | Map a transformation over a list.
mapT :: (Traversable t, Monad m) => Transform c m a b -> Transform c m (t a) (t b)

-- | An identity transformation that resembles a monadic <a>join</a>.
joinT :: Transform c m (m a) a

-- | Fail if the Boolean is False, succeed if the Boolean is True.
guardT :: Monad m => Transform c m Bool ()

-- | Catch a failing rewrite, making it into an identity.
tryR :: MonadCatch m => Rewrite c m a -> Rewrite c m a

-- | Perform a collection of rewrites in sequence, requiring all to
--   succeed.
andR :: (Foldable f, Monad m) => f (Rewrite c m a) -> Rewrite c m a

-- | Perform a collection of rewrites in sequence, succeeding if any
--   succeed.
orR :: (Functor f, Foldable f, MonadCatch m) => f (Rewrite c m a) -> Rewrite c m a

-- | Perform two rewrites in sequence, succeeding if one or both succeed.
(>+>) :: MonadCatch m => Rewrite c m a -> Rewrite c m a -> Rewrite c m a

-- | Repeat a rewrite until it fails, then return the result before the
--   failure. Requires at least the first attempt to succeed.
repeatR :: MonadCatch m => Rewrite c m a -> Rewrite c m a

-- | Look at the argument to a rewrite, and choose to be either <a>idR</a>
--   or a failure.
acceptR :: Monad m => (a -> Bool) -> Rewrite c m a

-- | As <a>acceptR</a>, but takes a custom failure message.
acceptWithFailMsgR :: Monad m => (a -> Bool) -> String -> Rewrite c m a

-- | A generalisation of <a>acceptR</a> where the predicate is a
--   <a>Transform</a>.
accepterR :: Monad m => Transform c m a Bool -> Rewrite c m a

-- | Makes an rewrite fail if the result value equals the argument value.
changedR :: (MonadCatch m, Eq a) => Rewrite c m a -> Rewrite c m a

-- | Makes a rewrite fail if the result value and the argument value
--   satisfy the equality predicate. This is a generalisation of
--   <a>changedR</a>. <tt>changedR = changedByR (<a>==</a>)</tt>
changedByR :: MonadCatch m => (a -> a -> Bool) -> Rewrite c m a -> Rewrite c m a

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

-- | The <a>AnyR</a> transformer, in combination with <a>wrapAnyR</a> and
--   <a>unwrapAnyR</a>, causes a sequence of rewrites to succeed if at
--   least one succeeds, converting failures to identity rewrites.
data AnyR m a

-- | Wrap a <a>Rewrite</a> using the <a>AnyR</a> monad transformer.
wrapAnyR :: MonadCatch m => Rewrite c m a -> Rewrite c (AnyR m) a

-- | Unwrap a <a>Rewrite</a> from the <a>AnyR</a> monad transformer.
unwrapAnyR :: Monad m => Rewrite c (AnyR m) a -> Rewrite c m a

-- | The <a>OneR</a> transformer, in combination with <a>wrapOneR</a> and
--   <a>unwrapOneR</a>, causes a sequence of rewrites to only apply the
--   first success, converting the remainder (and failures) to identity
--   rewrites.
data OneR m a

-- | Wrap a <a>Rewrite</a> using the <a>OneR</a> monad transformer.
wrapOneR :: MonadCatch m => Rewrite c m g -> Rewrite c (OneR m) g

-- | Unwrap a <a>Rewrite</a> from the <a>OneR</a> monad transformer.
unwrapOneR :: Monad m => Rewrite c (OneR m) a -> Rewrite c m a
instance MonadCatch m => MonadCatch (OneR m)
instance Monad m => Monad (OneR m)
instance Monad m => Applicative (OneR m)
instance Monad m => Functor (OneR m)
instance MonadCatch m => MonadCatch (AnyR m)
instance Monad m => Monad (AnyR m)
instance Monad m => Applicative (AnyR m)
instance Monad m => Functor (AnyR m)
instance Functor PBool


-- | This module provides various monadic and arrow combinators that are
--   useful when working with <a>Transform</a>s and <a>Rewrite</a>s.
module Language.KURE.Combinators


-- | This module provides several Path abstractions, used for denoting a
--   path through the tree.
module Language.KURE.Path

-- | A <a>Path</a> is just a list. The intent is that a path represents a
--   route through the tree from an arbitrary node.
type Path crumb = [crumb]

-- | A <a>SnocPath</a> is a list stored in reverse order.
newtype SnocPath crumb
SnocPath :: [crumb] -> SnocPath crumb

-- | A class of things that can be extended by crumbs. Typically,
--   <tt>c</tt> is a context type. The typical use is to extend an
--   <a>AbsolutePath</a> stored in the context (during tree traversal).
--   Note however, that if an <a>AbsolutePath</a> is not stored in the
--   context, an instance can still be declared with <tt>(<a>@@</a>
--   crumb)</tt> as an identity operation.
class ExtendPath c crumb | c -> crumb
(@@) :: ExtendPath c crumb => c -> crumb -> c

-- | Convert a <a>SnocPath</a> to a <a>Path</a>. O(n).
snocPathToPath :: SnocPath crumb -> Path crumb

-- | Convert a <a>Path</a> to a <a>SnocPath</a>. O(n).
pathToSnocPath :: Path crumb -> SnocPath crumb
singletonSnocPath :: crumb -> SnocPath crumb

-- | Get the last crumb from a <a>SnocPath</a>. O(1).
lastCrumb :: SnocPath crumb -> Maybe crumb

-- | A <a>SnocPath</a> from a local origin.
type LocalPath = SnocPath

-- | A <a>SnocPath</a> from the root.
type AbsolutePath = SnocPath

-- | A class for contexts that store the current <a>AbsolutePath</a>,
--   allowing transformations to depend upon it.
class ReadPath c crumb | c -> crumb
absPath :: ReadPath c crumb => c -> AbsolutePath crumb

-- | Lifted version of <a>lastCrumb</a>.
lastCrumbT :: (ReadPath c crumb, Monad m) => Transform c m a crumb

-- | Lifted version of <a>absPath</a>.
absPathT :: (ReadPath c crumb, Monad m) => Transform c m a (AbsolutePath crumb)
instance Eq crumb => Eq (SnocPath crumb)
instance ReadPath (AbsolutePath crumb) crumb
instance ExtendPath (SnocPath crumb) crumb
instance Show crumb => Show (SnocPath crumb)
instance Functor SnocPath
instance Monoid (SnocPath crumb)


-- | This module provides a utility data type for extending an existing
--   context with extra information. The idea is that, after defining class
--   instances for any user-specific contextual operations, it can be used
--   for any ad-hoc context extensions. See the treatment of
--   <a>ExtendPath</a> as an example.
module Language.KURE.ExtendableContext

-- | A context transformer, for augmenting a context with additional
--   information.
data ExtendContext c e

-- | Extend a context with some additional information.
extendContext :: e -> c -> ExtendContext c e

-- | Retrieve the base context (without the extra information).
baseContext :: ExtendContext c e -> c

-- | Retrieve the extra contextual information.
extraContext :: ExtendContext c e -> e
instance (ExtendPath c crumb, ExtendPath e crumb) => ExtendPath (ExtendContext c e) crumb


-- | This module provides (unsafe) debugging/tracing combinators.
module Language.KURE.Debug

-- | Trace output of the value being rewritten; use for debugging only.
debugR :: (Monad m, Show a) => Int -> String -> Rewrite c m a


-- | This module defines the KURE <a>Lens</a> type, along with some useful
--   operations.
module Language.KURE.Lens

-- | 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 :: Transform c m a ((c, b), b -> m a) -> Lens c m a b

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

-- | Apply a rewrite 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 transformation at a point specified by a <a>Lens</a>.
focusT :: Monad m => Lens c m a b -> Transform c m b d -> Transform c m a d

-- | Construct a <a>Lens</a> from two pure functions.
pureL :: Monad m => (a -> b) -> (b -> a) -> Lens c m a b

-- | The failing <a>Lens</a>.
failL :: Monad m => String -> Lens c m a b

-- | A <a>Lens</a> is deemed to have failed (and thus can be caught) if
--   either it fails on the way down, or, crucially, if it would fail on
--   the way up for an unmodified value. However, actual failure on the way
--   up is not caught (as by then it is too late to use an alternative
--   <a>Lens</a>). This means that, in theory, a use of <a>catchL</a> could
--   cause a succeeding <a>Lens</a> application to fail. But provided
--   <a>lens</a> is used correctly, this should never happen.
catchL :: MonadCatch m => Lens c m a b -> (String -> Lens c m a b) -> Lens c m a b

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

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

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

-- | A <a>Lens</a> to the projection of a value.
projectL :: (Monad m, Injection a g) => Lens c m g a
instance Monad m => Category (Lens c m)


-- | 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>Walker</a> captures the ability to walk over a tree containing
--   nodes of type <tt>u</tt>, using a specific context <tt>c</tt>.
--   
--   Minimal complete definition: <a>allR</a>.
--   
--   Default definitions are provided for <a>anyR</a>, <a>oneR</a>,
--   <a>allT</a>, <a>oneT</a>, and <a>childL</a>, but they may be
--   overridden for efficiency.
class Walker c u where allT = unwrapAllT . allR . wrapAllT oneT = unwrapOneT . allR . wrapOneT anyR = unwrapAnyR . allR . wrapAnyR oneR = unwrapOneR . allR . wrapOneR childL = childL_default
allR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u
allT :: (Walker c u, MonadCatch m, Monoid b) => Transform c m u b -> Transform c m u b
oneT :: (Walker c u, MonadCatch m) => Transform c m u b -> Transform c m u b
anyR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u
oneR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u
childL :: (Walker c u, ReadPath c crumb, Eq crumb, MonadCatch m) => crumb -> Lens c m u u

-- | Apply a rewrite to a specified child.
childR :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => crumb -> Rewrite c m u -> Rewrite c m u

-- | Apply a transformation to a specified child.
childT :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => crumb -> Transform c m u b -> Transform c m u b

-- | Apply a rewrite in a top-down manner, succeeding if they all succeed.
alltdR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

-- | Apply a rewrite in a bottom-up manner, succeeding if they all succeed.
allbuR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

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

-- | Apply a rewrite in a top-down manner, succeeding if any succeed.
anytdR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

-- | Apply a rewrite in a bottom-up manner, succeeding if any succeed.
anybuR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

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

-- | Apply a rewrite to the first node for which it can succeed, in a
--   top-down traversal.
onetdR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

-- | Apply a rewrite to the first node for which it can succeed, in a
--   bottom-up traversal.
onebuR :: (Walker c u, MonadCatch m) => Rewrite c m u -> Rewrite c m u

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

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

-- | Apply a rewrite to the largest node(s) that satisfy the predicate,
--   requiring all to succeed.
allLargestR :: (Walker c u, MonadCatch m) => Transform c m u Bool -> Rewrite c m u -> Rewrite c m u

-- | Apply a rewrite to the largest node(s) that satisfy the predicate,
--   succeeding if any succeed.
anyLargestR :: (Walker c u, MonadCatch m) => Transform c m u Bool -> Rewrite c m u -> Rewrite c m u

-- | Apply a rewrite to the first node for which it can succeed among the
--   largest node(s) that satisfy the predicate.
oneLargestR :: (Walker c u, MonadCatch m) => Transform c m u Bool -> Rewrite c m u -> Rewrite c m u

-- | Fold a tree in a top-down manner, using a single <a>Transform</a> for
--   each node.
foldtdT :: (Walker c u, MonadCatch m, Monoid b) => Transform c m u b -> Transform c m u b

-- | Fold a tree in a bottom-up manner, using a single <a>Transform</a> for
--   each node.
foldbuT :: (Walker c u, MonadCatch m, Monoid b) => Transform c m u b -> Transform c m u b

-- | Apply a transformation to the first node for which it can succeed, in
--   a top-down traversal.
onetdT :: (Walker c u, MonadCatch m) => Transform c m u b -> Transform c m u b

-- | Apply a transformation to the first node for which it can succeed, in
--   a bottom-up traversal.
onebuT :: (Walker c u, MonadCatch m) => Transform c m u b -> Transform c m u b

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

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

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

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

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

-- | Apply a transformation to the largest node(s) that satisfy the
--   predicate, combining the results in a monoid.
allLargestT :: (Walker c u, MonadCatch m, Monoid b) => Transform c m u Bool -> Transform c m u b -> Transform c m u b

-- | Apply a transformation to the first node for which it can succeed
--   among the largest node(s) that satisfy the predicate.
oneLargestT :: (Walker c u, MonadCatch m) => Transform c m u Bool -> Transform c m u b -> Transform c m u b

-- | List the children of the current node.
childrenT :: (ReadPath c crumb, Walker c u, MonadCatch m) => Transform c m u [crumb]

-- | Test if the type of the current node summand matches the type of the
--   argument. Note that the argument <i>value</i> is never inspected, it
--   is merely a proxy for a type argument.
summandIsTypeT :: (MonadCatch m, Injection a u) => a -> Transform c m u Bool

-- | Construct a <a>Lens</a> by following a <a>Path</a>.
pathL :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Lens c m u u

-- | Build a <a>Lens</a> from the root to a point specified by a
--   <a>LocalPath</a>.
localPathL :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => LocalPath crumb -> Lens c m u u

-- | Construct a <a>Lens</a> that points to the last node at which the
--   <a>Path</a> can be followed.
exhaustPathL :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Lens c m u u

-- | Repeat as many iterations of the <a>Path</a> as possible.
repeatPathL :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Lens c m u u

-- | Apply a rewrite at a point specified by a <a>Path</a>.
pathR :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Rewrite c m u -> Rewrite c m u

-- | Apply a transformation at a point specified by a <a>Path</a>.
pathT :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Transform c m u b -> Transform c m u b

-- | Apply a rewrite at a point specified by a <a>LocalPath</a>.
localPathR :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => LocalPath crumb -> Rewrite c m u -> Rewrite c m u

-- | Apply a transformation at a point specified by a <a>LocalPath</a>.
localPathT :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => LocalPath crumb -> Transform c m u b -> Transform c m u b

-- | Check if it is possible to construct a <a>Lens</a> along this path
--   from the current node.
testPathT :: (ReadPath c crumb, Eq crumb, Walker c u, MonadCatch m) => Path crumb -> Transform c m u Bool
instance MonadCatch (GetChild c u)
instance Monad (GetChild c u)
instance Applicative (GetChild c u)
instance Functor (GetChild c u)
instance MonadCatch m => MonadCatch (OneT w m)
instance Monad m => Monad (OneT w m)
instance (Monoid w, Monad m) => Applicative (OneT w m)
instance (Monoid w, Monad m) => Functor (OneT w m)
instance (Monoid w, MonadCatch m) => MonadCatch (AllT w m)
instance (Monoid w, Monad m) => Monad (AllT w m)
instance (Monoid w, Monad m) => Applicative (AllT w m)
instance (Monoid w, Monad m) => Functor (AllT w m)


-- | This module provides combinators to find <a>LocalPath</a>s sub-nodes
--   specified by a predicate.
module Language.KURE.Pathfinder

-- | A context transformer that adds a <a>LocalPath</a> (from the current
--   node) to the context.
type WithLocalPath c crumb = ExtendContext c (LocalPath crumb)

-- | Apply a transformation that stores a <a>LocalPath</a> in the context
--   (starting at the current node).
withLocalPathT :: Transform (WithLocalPath c crumb) m a b -> Transform c m a b

-- | Extract the current <a>LocalPath</a> from the context.
exposeLocalPathT :: Monad m => Transform (WithLocalPath c crumb) m a (LocalPath crumb)

-- | Return the current <a>LocalPath</a> if the predicate transformation
--   succeeds.
acceptLocalPathT :: Monad m => Transform c m u Bool -> Transform (WithLocalPath c crumb) m u (LocalPath crumb)

-- | Find the <a>LocalPath</a>s to every node that satisfies the predicate.
pathsToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u [LocalPath crumb]

-- | Find the <a>LocalPath</a> to the first node that satisfies the
--   predicate (in a pre-order traversal).
onePathToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u (LocalPath crumb)

-- | Find the <a>LocalPath</a> to the first descendent node that satisfies
--   the predicate (in a pre-order traversal).
oneNonEmptyPathToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u (LocalPath crumb)

-- | Find the <a>LocalPath</a>s to every node that satisfies the predicate,
--   ignoring nodes below successes.
prunePathsToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u [LocalPath crumb]

-- | Find the <a>LocalPath</a> to the node that satisfies the predicate,
--   failing if that does not uniquely identify a node.
uniquePathToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u (LocalPath crumb)

-- | Build a <a>LocalPath</a> to the node that satisfies the predicate,
--   failing if that does not uniquely identify a node (ignoring nodes
--   below successes).
uniquePrunePathToT :: (Walker (WithLocalPath c crumb) u, MonadCatch m) => Transform c m u Bool -> Transform c m u (LocalPath crumb)


-- | 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.Transform</a>, and the traversal functionality can be
--   found in <a>Language.KURE.Walker</a>.
module Language.KURE