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


-- | Stack prisms
--   
--   Haskell lens prisms that use stack types
@package stack-prism
@version 0.1

module Data.StackPrism

-- | A stack prism is a bidirectional isomorphism that is partial in the
--   backward direction. These prisms are compatible with the <tt>lens</tt>
--   library.
--   
--   This can be used to express constructor-deconstructor pairs. For
--   example:
--   
--   <pre>
--   nil :: StackPrism t ([a] :- t)
--   nil = stackPrism f g
--     where
--       f        t  = [] :- t
--       g ([] :- t) = Just t
--       g _         = Nothing
--   
--   cons :: StackPrism (a :- [a] :- t) ([a] :- t)
--   cons = stackPrism f g
--     where
--       f (x :- xs  :- t) = (x : xs) :- t
--       g ((x : xs) :- t) = Just (x :- xs :- t)
--       g _               = Nothing
--   </pre>
--   
--   Here <a>:-</a> can be read as 'cons', forming a stack of values. For
--   example, <tt>nil</tt> pushes <tt>[]</tt> onto the stack; or, in the
--   backward direction, tries to remove <tt>[]</tt> from the stack.
--   Representing constructor-destructor pairs as stack manipulators allows
--   them to be composed more easily.
--   
--   Modules <a>Data.StackPrism.Generic</a> and <a>Data.StackPrism.TH</a>
--   offer generic ways of deriving <tt>StackPrism</tt>s for custom
--   datatypes.
type StackPrism a b = forall p f. (Choice p, Applicative f) => p a (f a) -> p b (f b)

-- | Construct a prism.
stackPrism :: (a -> b) -> (b -> Maybe a) -> StackPrism a b

-- | Apply a prism in forward direction.
forward :: StackPrism a b -> a -> b

-- | Apply a prism in backward direction.
backward :: StackPrism a b -> b -> Maybe a

-- | Heterogenous stack with a head and a tail. Or: an infix way to write
--   <tt>(,)</tt>.
data (:-) h t
(:-) :: h -> t -> :- h t
instance (Eq h, Eq t) => Eq (h :- t)
instance (Show h, Show t) => Show (h :- t)
instance Functor ((:-) h)

module Data.StackPrism.TH

-- | Derive stack prisms for a given datatype.
--   
--   For example:
--   
--   <pre>
--   deriveStackPrisms ''Maybe
--   </pre>
--   
--   will create
--   
--   <pre>
--   _Just :: StackPrism (a :- t) (Maybe a :- t)
--   _Nothing :: StackPrism t (Nothing :- t)
--   </pre>
--   
--   together with their implementations.
deriveStackPrisms :: Name -> Q [Dec]

-- | Derive stack prisms given a function that derives variable names from
--   constructor names.
deriveStackPrismsWith :: (String -> String) -> Name -> Q [Dec]

-- | Derive stack prisms given a list of variable names, one for each
--   constructor.
deriveStackPrismsFor :: [String] -> Name -> Q [Dec]

module Data.StackPrism.Generic
type StackPrisms a = PrismList (Rep a) a

-- | Derive a list of stack prisms, one for each constructor in the
--   <a>Generic</a> datatype <tt>a</tt>. The list is wrapped in the unary
--   constructor <tt>PrismList</tt>. Within that constructor, the prisms
--   are separated by the right-associative binary infix constructor
--   <tt>:&amp;</tt>. Finally, the individual prisms are wrapped in the
--   unary constructor <tt>I</tt>. These constructors are all exported by
--   this module, but no documentation is generated for them by Hackage.
--   
--   As an example, here is how to define the prisms <tt>nil</tt> and
--   <tt>cons</tt> for <tt>[a]</tt>, which is an instance of
--   <tt>Generic</tt>:
--   
--   <pre>
--   nil  :: StackPrism              t  ([a] :- t)
--   cons :: StackPrism (a :- [a] :- t) ([a] :- t)
--   PrismList (P nil :&amp; P cons) = mkPrismList :: StackPrisms [a]
--   </pre>
mkPrismList :: (Generic a, MkPrismList (Rep a)) => StackPrisms a
instance (MkStackPrism f, MkStackPrism g) => MkStackPrism (f :*: g)
instance MkStackPrism f => MkStackPrism (M1 i c f)
instance MkStackPrism (K1 i a)
instance MkStackPrism U1
instance MkStackPrism f => MkPrismList (M1 C c f)
instance (MkPrismList f, MkPrismList g) => MkPrismList (f :+: g)
instance MkPrismList f => MkPrismList (M1 D c f)