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


-- | State variables
--   
@package StateVar
@version 1.0.1.0


-- | State variables are references in the IO monad, like <a>IORef</a>s or
--   parts of the OpenGL state. Note that state variables are not
--   neccessarily writable or readable, they may come in read-only or
--   write-only flavours, too. As a very simple example for a state
--   variable, consider an explicitly allocated memory buffer. This buffer
--   can easily be converted into a <a>StateVar</a>:
--   
--   <pre>
--   makeStateVarFromPtr :: Storable a =&gt; Ptr a -&gt; StateVar a
--   makeStateVarFromPtr p = makeStateVar (peek p) (poke p)
--   </pre>
--   
--   The example below puts 11 into a state variable (i.e. into the
--   buffer), increments the contents of the state variable by 22, and
--   finally prints the resulting content:
--   
--   <pre>
--   do p &lt;- malloc :: IO (Ptr Int)
--      let v = makeStateVarFromPtr p
--      v $= 11
--      v $~ (+ 22)
--      x &lt;- get v
--      print x
--   </pre>
--   
--   <a>IORef</a>s are state variables, too, so an example with them looks
--   extremely similiar:
--   
--   <pre>
--   do v &lt;- newIORef (0 :: Int)
--      v $= 11
--      v $~ (+ 22)
--      x &lt;- get v
--      print x
--   </pre>
module Data.StateVar

-- | The class of all readable state variables.
class HasGetter g
get :: HasGetter g => g a -> IO a

-- | A concrete implementation of a read-only state variable, carrying an
--   IO action to read the value.
newtype GettableStateVar a
GettableStateVar :: (IO a) -> GettableStateVar a

-- | Construct a <a>GettableStateVar</a> from an IO action.
makeGettableStateVar :: IO a -> GettableStateVar a

-- | The class of all writable state variables.
class HasSetter s
($=) :: HasSetter s => s a -> a -> IO ()

-- | A concrete implementation of a write-only state variable, carrying an
--   IO action to write the new value.
newtype SettableStateVar a
SettableStateVar :: (a -> IO ()) -> SettableStateVar a

-- | Construct a <a>SettableStateVar</a> from an IO action.
makeSettableStateVar :: (a -> IO ()) -> SettableStateVar a

-- | A concrete implementation of a readable and writable state variable,
--   carrying one IO action to read the value and another IO action to
--   write the new value.
data StateVar a
StateVar :: (GettableStateVar a) -> (SettableStateVar a) -> StateVar a

-- | Construct a <a>StateVar</a> from two IO actions, one for reading and
--   one for writing.
makeStateVar :: IO a -> (a -> IO ()) -> StateVar a

-- | A modificator convenience function, transforming the contents of a
--   state variable with a given funtion.
($~) :: (HasGetter v, HasSetter v) => v a -> (a -> a) -> IO ()

-- | A variant of <a>$=</a> which is strict in the value to be set.
($=!) :: HasSetter s => s a -> a -> IO ()

-- | A variant of <a>$~</a> which is strict in the transformed value.
($~!) :: (HasGetter v, HasSetter v) => v a -> (a -> a) -> IO ()
instance HasSetter StateVar
instance HasGetter StateVar
instance HasSetter SettableStateVar
instance HasSetter IORef
instance Monad GettableStateVar
instance Applicative GettableStateVar
instance Functor GettableStateVar
instance HasGetter GettableStateVar
instance HasGetter IORef