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


-- | Specify that lifted values were forced to WHNF or NF.
--   
--   Alternative to bang patterns using CBV functions and unlifted data
--   types. Tag your values to maintain the invariant that they were
--   forced. Avoid liveness leaks on long lived data structures.
--   
--   Main tutorial on the only module. Here is a taste of how it will look
--   like.
--   
--   <pre>
--   {-# Language QualifiedDo #-}
--   
--   import qualified Data.Forced as DF
--   import Data.Forced hiding (pure, fmap, (\&lt;*\&gt;), return, (&gt;&gt;=), (&gt;&gt;))
--   import Data.Map.Lazy qualified as ML
--   
--   noThunksForWHNF :: IO ()
--   noThunksForWHNF = do
--     -- map0 actually evaluated on here.
--     let map0 :: Demand (ML.Map Char (ForcedWHNF Int))
--         map0 = DF.do
--           v &lt;- demandWHNF (const (2 + 2) 'a')
--           DF.pure $ ML.insert 'a' v ML.empty
--   
--     map1 &lt;- extractDemand map0
--     go (ML.lookup 'a' map1)
--   
--   -- pattern matching for de-structuring, no construction allowed.
--   go :: ForcedWHNF Int -&gt; IO ()
--   go (ForcedWHNF i) =  print i
--   </pre>
@package data-forced
@version 0.3.0.0

module Data.Forced

-- | Contains a value of type <tt>a</tt> that has been forced to
--   <b>W</b>eak <b>H</b>ead <b>N</b>ormal <b>F</b>orm. Constructor not
--   exported (so no <a>coerce</a>).
data ForcedWHNF a

-- | The only way to extract the underlying value.
pattern ForcedWHNF :: forall a. a -> ForcedWHNF a

-- | Contains a value of type <tt>a</tt> that has been forced to
--   <b>N</b>ormal <b>F</b>orm. Constructor not exported (so no
--   <a>coerce</a>).
data ForcedNF a

-- | The only way to extract the underlying value.
pattern ForcedNF :: forall a. a -> ForcedNF a

-- | A strict identity monad of <a>UnliftedType</a> kind. To be used via
--   <tt>-XQualifiedDo</tt>.
data Demand (a :: LiftedType) :: UnliftedType

-- | This is a CBV function. Evaluates the argument to WHNF before
--   returning.
demandWHNF :: forall a. a -> Demand (ForcedWHNF a)

-- | This is a CBV function. Evaluates the argument to NF before returning.
demandNF :: forall a. NFData a => a -> Demand (ForcedNF a)

-- | We don't ship the constructor of <a>Demand</a>. The only way to
--   extract a <a>Demand</a> is to sequence to a know point on <a>IO</a>.
--   From the PoV of the rest of the program, the tagged values with
--   <a>ForcedWHNF</a> or <a>ForcedNF</a> will have been demanded.
extractDemand :: Demand a -> IO a

-- | <a>fmap</a> analogue for <a>Demand</a>s which are of the
--   <a>UnliftedType</a> kind.
fmap :: (a -> b) -> Demand a -> Demand b

-- | Places <b>no</b> demand on the value. <a>pure</a> analogue for
--   <a>Demand</a>s which are of the <a>UnliftedType</a> kind.
pure :: a -> Demand a

-- | <a>&lt;*&gt;</a> analogue for <a>Demand</a>s which are of the
--   <a>UnliftedType</a> kind.
(<*>) :: Demand (a -> b) -> Demand a -> Demand b

-- | <a>return</a> analogue for <a>Demand</a>s which are of the
--   <a>UnliftedType</a> kind. Same as <a>pure</a>.
return :: a -> Demand a

-- | <a>&gt;&gt;=</a> analogue for <a>Demand</a>s which are of the
--   <a>UnliftedType</a> kind.
(>>=) :: Demand a -> (a -> Demand b) -> Demand b

-- | <a>&gt;&gt;</a> analogue for <a>Demand</a>s which are of the
--   <a>UnliftedType</a> kind.
(>>) :: Demand a -> Demand b -> Demand b
instance GHC.Show.Show a => GHC.Show.Show (Data.Forced.ForcedNF a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Forced.ForcedWHNF a)