Add runSIO, changelog, version bump

yesod-test/ChangeLog.md

@@ -1,6 +1,6 @@
 # ChangeLog for yesod-test
 
-## TODO
+## 1.6.13
 
 * Add `Yesod.Test.Internal.SIO` module to expose the `SIO` type.
 

yesod-test/Yesod/Test/Internal/SIO.hs

@@ -15,7 +15,7 @@
 -- This module is internal. Breaking changes to this module will not be
 -- reflected in the major version of this package.
 --
--- @since TODO
+-- @since 1.6.13
 module Yesod.Test.Internal.SIO where
 
 import Control.Monad.Trans.Reader (ReaderT (..))
@@ -35,20 +35,54 @@ instance MS.MonadState s (SIO s)
   get = getSIO
   put = putSIO
 
+-- | Retrieve the current state in the 'SIO' type.
+--
+-- Equivalent to 'MS.get'
+--
+-- @since 1.6.13
 getSIO :: SIO s s
 getSIO = SIO $ ReaderT readIORef
 
+-- | Put the given @s@ into the 'SIO' state for later retrieval.
+--
+-- Equivalent to 'MS.put', but the value is evaluated to weak head normal
+-- form.
+--
+-- @since 1.6.13
 putSIO :: s -> SIO s ()
 putSIO s = SIO $ ReaderT $ \ref -> writeIORef ref $! s
 
+-- | Modify the underlying @s@ state.
+--
+-- This is strict in the function used, and is equivalent to 'MS.modify''.
+--
+-- @since 1.6.13
 modifySIO :: (s -> s) -> SIO s ()
 modifySIO f = SIO $ ReaderT $ \ref -> modifyIORef' ref f
 
+-- | Run an 'SIO' action with the intial state @s@ provided, returning the
+-- result, and discard the final state.
+--
+-- @since 1.6.13
 evalSIO :: SIO s a -> s -> IO a
-evalSIO (SIO (ReaderT f)) s = newIORef s >>= f
+evalSIO action =
+    fmap snd . runSIO action
 
+-- | Run an 'SIO' action with the initial state @s@ provided, returning the
+-- final state, and discarding the result.
+--
+-- @since 1.6.13
 execSIO :: SIO s () -> s -> IO s
-execSIO (SIO (ReaderT f)) s = do
+execSIO action =
-  ref <- newIORef s
+    fmap fst . runSIO action
-  f ref
+
-  readIORef ref
+-- | Run an 'SIO' action with the initial state provided, returning both
+-- the result of the computation as well as the final state.
+--
+-- @since 1.6.13
+runSIO :: SIO s a -> s -> IO (s, a)
+runSIO (SIO (ReaderT f)) s = do
+    ref <- newIORef s
+    a <- f ref
+    s' <- readIORef ref
+    pure (s', a)

yesod-test/yesod-test.cabal

@@ -1,5 +1,5 @@
 name:               yesod-test
-version:            1.6.12
+version:            1.6.13
 license:            MIT
 license-file:       LICENSE
 author:             Nubis <nubis@woobiz.com.ar>