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


-- | Partial isomorphisms
--   
--   Partial isomorphisms
@package Piso
@version 0.2

module Data.Piso

-- | Bidirectional isomorphism that is total when applied in the forward
--   direction (<tt>a -&gt; b</tt>), but partial when applied in the
--   backward direction (<tt>b -&gt; Maybe a</tt>).
--   
--   This can be used to express constructor-deconstructor pairs. For
--   example:
--   
--   <pre>
--   nil :: Piso t ([a] :- t)
--   nil = Piso f g
--     where
--       f        t  = [] :- t
--       g ([] :- t) = Just t
--       g _         = Nothing
--   
--   cons :: Piso (a :- [a] :- t) ([a] :- t)
--   cons = Piso 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.
--   
--   Module <tt>Data.Piso.Common</tt> contains <tt>Piso</tt>s for some
--   common datatypes.
--   
--   Modules <tt>Data.Piso.Generic</tt> and <tt>Data.Piso.TH</tt> offer
--   generic ways of deriving <tt>Piso</tt>s for custom datatypes.
data Piso a b
Piso :: (a -> b) -> (b -> Maybe a) -> Piso a b

-- | Apply an isomorphism in forward direction.
forward :: Piso a b -> a -> b

-- | Apply an isomorphism in backward direction.
backward :: Piso a b -> b -> Maybe a

-- | A type class that expresses that a category is able to embed
--   <a>Piso</a> values.
class Category cat => FromPiso cat
fromPiso :: FromPiso cat => Piso a b -> cat a b

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

module Data.Piso.Generic

-- | Derive a list of partial isomorphisms, one for each constructor in the
--   <a>Generic</a> datatype <tt>a</tt>. The list is wrapped in the unary
--   constructor <tt>PisoList</tt>. Within that constructor, the
--   isomorphisms are separated by the right-associative binary infix
--   constructor <tt>:&amp;</tt>. Finally, the individual isomorphisms 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 isomorphisms <tt>nil</tt> and
--   <tt>cons</tt> for <tt>[a]</tt>, which is an instance of
--   <tt>Generic</tt>:
--   
--   <pre>
--   nil  :: Piso              t  ([a] :- t)
--   cons :: Piso (a :- [a] :- t) ([a] :- t)
--   (nil, cons) = (nil', cons')
--     where
--       PisoList (I nil' :&amp; I cons') = mkPisoList
--   </pre>
--   
--   GHC 7.6.3 requires the extra indirection through <tt>nil'</tt> and
--   <tt>cons'</tt>, due to bug 7268
--   (<a>http://ghc.haskell.org/trac/ghc/ticket/7268</a>). When it is
--   fixed, the example above can be written in a more direct way:
--   
--   <pre>
--   nil  :: Piso              t  ([a] :- t)
--   cons :: Piso (a :- [a] :- t) ([a] :- t)
--   PisoList (I nil :&amp; I cons) = mkPisoList
--   </pre>
--   
--   If you are familiar with the generic representations from
--   <tt>Data.Generic</tt>, you might be interested in the exact types of
--   the various constructors in which the isomorphisms are wrapped:
--   
--   <pre>
--   I        :: (forall t. Piso (PisoLhs f t) (a :- t)) -&gt; PisoList (M1 C c f) a
--   (:&amp;)     :: PisoList f a -&gt; PisoList g a -&gt; PisoList (f :+: g) a
--   PisoList :: PisoList f a -&gt; PisoList (M1 D c f) a
--   </pre>
--   
--   The type constructor <tt>PisoLhs</tt> that appears in the type of
--   <tt>I</tt> is an internal type family that builds the proper
--   heterogenous list of types (using <a>:-</a>) based on the
--   constructor's fields.
mkPisoList :: (Generic a, MkPisoList (Rep a)) => PisoList (Rep a) a
instance Data.Piso.Generic.MkPisoList f => Data.Piso.Generic.MkPisoList (GHC.Generics.M1 GHC.Generics.D c f)
instance (Data.Piso.Generic.MkPisoList f, Data.Piso.Generic.MkPisoList g) => Data.Piso.Generic.MkPisoList (f GHC.Generics.:+: g)
instance Data.Piso.Generic.MkPiso f => Data.Piso.Generic.MkPisoList (GHC.Generics.M1 GHC.Generics.C c f)
instance Data.Piso.Generic.MkPiso GHC.Generics.U1
instance Data.Piso.Generic.MkPiso (GHC.Generics.K1 i a)
instance Data.Piso.Generic.MkPiso f => Data.Piso.Generic.MkPiso (GHC.Generics.M1 i c f)
instance (Data.Piso.Generic.MkPiso f, Data.Piso.Generic.MkPiso g) => Data.Piso.Generic.MkPiso (f GHC.Generics.:*: g)

module Data.Piso.TH

-- | Derive partial isomorphisms for a given datatype. The resulting
--   expression is a tuple with one isomorphism element for each
--   constructor in the datatype.
--   
--   For example:
--   
--   <pre>
--   nothing :: Piso t (Maybe a :- t)
--   just    :: Piso (a :- t) (Maybe a :- t)
--   (nothing, just) = $(derivePisos ''Maybe)
--   </pre>
--   
--   Deriving isomorphisms this way requires <tt>-XNoMonoPatBinds</tt>.
derivePisos :: Name -> Q Exp


-- | Constructor-destructor isomorphisms for some common datatypes.
module Data.Piso.Common
unit :: Piso t (() :- t)
tup :: Piso (a :- (b :- t)) ((a, b) :- t)
tup3 :: Piso (a :- (b :- (c :- t))) ((a, b, c) :- t)
nothing :: Piso t (Maybe a :- t)
just :: Piso (a :- t) (Maybe a :- t)
nil :: Piso t ([a] :- t)
cons :: Piso (a :- ([a] :- t)) ([a] :- t)
left :: Piso (a :- t) (Either a b :- t)
right :: Piso (b :- t) (Either a b :- t)
false :: Piso t (Bool :- t)
true :: Piso t (Bool :- t)