-- 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.0.0


-- | This module provides various monadic and arrow combinators that are
--   particularly useful when working with translations. Note that these
--   combinators assume that <a>mplus</a> behaves as a catch, for both
--   <a>fail</a> and <a>mzero</a>.
module Language.KURE.Combinators

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

-- | if-then-else lifted over a <a>Monad</a>.
condM :: Monad m => m Bool -> m a -> m a -> m a

-- | if-then lifted over a <a>Monad</a>.
whenM :: Monad m => m Bool -> m a -> m a

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

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

-- | Catch a failing monadic computation, making it succeed with
--   <a>Nothing</a>.
attemptM :: MonadPlus m => m a -> m (Maybe a)

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

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

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

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

-- | Synonym for <a>id</a>.
idR :: Category ~> => (a ~> a)

-- | Synonym for <a>&lt;+&gt;</a>.
(<+) :: ArrowPlus ~> => (a ~> b) -> (a ~> b) -> (a ~> b)

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

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

-- | Catch a failing <a>ArrowPlus</a>, making it into an identity.
tryR :: ArrowPlus ~> => (a ~> a) -> (a ~> a)

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

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

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

-- | Attempts two <tt>Arrows</tt>s in sequence, succeeding if one or both
--   succeed.
(>+>) :: (ArrowPlus ~>, ArrowApply ~>) => (a ~> a) -> (a ~> a) -> (a ~> a)

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

-- | Sequence a list of <a>Arrow</a>s, succeeding if they all succeed.
andR :: Arrow ~> => [a ~> a] -> (a ~> a)


-- | This module defines the main KURE types: <a>Translate</a>,
--   <a>Rewrite</a> and <a>Lens</a>. <a>Rewrite</a> and <a>Lens</a> are
--   just special cases of <a>Translate</a>, and so any function that
--   operates on <a>Translate</a> is also applicable to <a>Rewrite</a> and
--   <a>Lens</a> (although care should be taken in the <a>Lens</a> case).
--   
--   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

-- | <a>Translate</a> is a translation or strategy that translates from a
--   value in a context to a monadic value.
data Translate c m a b
Translate :: (c -> a -> m b) -> Translate c m a b

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

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

-- | 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]

-- | A <a>Lens</a> is a way to focus in on a particular point in a
--   structure.
type Lens c m a b = Translate c m a ((c, b), b -> m a)

-- | <a>lens</a> is the primitive way of building a <a>Lens</a>.
lens :: (c -> a -> m ((c, b), b -> m a)) -> Lens c m a b

-- | Identity <a>Lens</a>.
idL :: Monad m => Lens c m a a

-- | Catch a failing endo<a>Lens</a>, making it into an identity.
tryL :: MonadPlus m => Lens c m a a -> Lens c m a a

-- | Composition of <a>Lens</a>s.
composeL :: Monad m => Lens c m a b -> Lens c m b d -> Lens c m a d

-- | Sequence a list of endo<a>Lens</a>s.
sequenceL :: MonadPlus m => [Lens c m a a] -> Lens c m a a

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

-- | 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
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 Monad m => Category (Translate c m)
instance MonadPlus m => MonadPlus (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>MonadPlus</a>, producing
--   <a>mzero</a> if the retraction fails.
retractM :: (MonadPlus 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 :: (MonadPlus 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 :: (MonadPlus m, Injection a a') => 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 :: (MonadPlus 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 :: (MonadPlus m, Injection a a') => Rewrite c m a -> Rewrite c m a'

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

-- | A <a>Lens</a> to the retraction of a value.
retractL :: (MonadPlus 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. There is no mechanism for "ascending" the tree.
module Language.KURE.Walker

-- | A <a>Term</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)) => Term a where type family Generic a :: *
numChildren :: Term a => a -> Int

-- | <a>Walker</a> captures the ability to walk over a <a>Term</a> applying
--   <a>Rewrite</a>s, using a specific context <tt>c</tt> and a
--   <a>MonadPlus</a> <tt>m</tt>.
--   
--   Minimal complete definition: <a>childL</a>.
--   
--   Default instances are provided for <a>allT</a>, <a>allR</a> and
--   <a>anyR</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 (MonadPlus m, Term a) => Walker c m a where allT t = do { n <- arr numChildren; mconcat [childT i t | i <- [0 .. (n - 1)]] } allR r = do { n <- arr numChildren; andR [childR i r | i <- [0 .. (n - 1)]] } anyR r = do { n <- arr numChildren; orR [childR i r | i <- [0 .. (n - 1)]] }
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
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

-- | Apply a <a>Rewrite</a> to a specific 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 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 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> 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 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> 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)

-- | Attempt to apply a <a>Rewrite</a> in a top-down manner, prunning at
--   successful rewrites.
tdpruneR :: (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 specific 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 node.
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 node.
foldbuT :: (Walker c m a, Monoid b, 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, prunning at
--   successes.
tdpruneT :: (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

-- | A <a>Path</a> is a list of <a>Int</a>s, where each <a>Int</a>
--   specifies which interesting child to descend to at each step.
type Path = [Int]

-- | 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 node 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)


-- | This module contains several utility functions that can be useful to
--   users of KURE, when definining instances of the KURE classes.
module Language.KURE.Utilities
allTgeneric :: (Walker c m a, Monoid b) => 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)
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
attemptAnyN :: Monad m => ([a] -> b) -> [m (Bool, a)] -> m b
attemptAny1N :: Monad m => (a1 -> [a2] -> r) -> m (Bool, a1) -> [m (Bool, a2)] -> m r

-- | A failing <a>Lens</a> with a standard error message for when the child
--   index is out of bounds.
missingChildL :: Monad m => Int -> Lens c m a b
childLaux :: (MonadPlus m, Term b) => (c, b) -> (b -> a) -> ((c, Generic b), Generic b -> m a)
childL0of1 :: (MonadPlus m, Term b) => (b -> a) -> (c, b) -> ((c, Generic b), Generic b -> m a)
childL0of2 :: (MonadPlus m, Term b0) => (b0 -> b1 -> a) -> (c, b0) -> b1 -> ((c, Generic b0), Generic b0 -> m a)
childL1of2 :: (MonadPlus m, Term b1) => (b0 -> b1 -> a) -> b0 -> (c, b1) -> ((c, Generic b1), Generic b1 -> m a)
childL0of3 :: (MonadPlus m, Term b0) => (b0 -> b1 -> b2 -> a) -> (c, b0) -> b1 -> b2 -> ((c, Generic b0), Generic b0 -> m a)
childL1of3 :: (MonadPlus m, Term b1) => (b0 -> b1 -> b2 -> a) -> b0 -> (c, b1) -> b2 -> ((c, Generic b1), Generic b1 -> m a)
childL2of3 :: (MonadPlus m, Term b2) => (b0 -> b1 -> b2 -> a) -> b0 -> b1 -> (c, b2) -> ((c, Generic b2), Generic b2 -> m a)
childL0of4 :: (MonadPlus m, Term b0) => (b0 -> b1 -> b2 -> b3 -> a) -> (c, b0) -> b1 -> b2 -> b3 -> ((c, Generic b0), Generic b0 -> m a)
childL1of4 :: (MonadPlus m, Term b1) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> (c, b1) -> b2 -> b3 -> ((c, Generic b1), Generic b1 -> m a)
childL2of4 :: (MonadPlus m, Term b2) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> b1 -> (c, b2) -> b3 -> ((c, Generic b2), Generic b2 -> m a)
childL3of4 :: (MonadPlus m, Term b3) => (b0 -> b1 -> b2 -> b3 -> a) -> b0 -> b1 -> b2 -> (c, b3) -> ((c, Generic b3), Generic b3 -> m a)
childLMofN :: (MonadPlus m, Term b) => Int -> ([b] -> a) -> [(c, b)] -> ((c, Generic b), Generic b -> m a)


-- | 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