Documentation

examples/with_signals/ExcMLStateTests.hs

@@ -1,17 +1,24 @@
 {-# LANGUAGE DataKinds #-}
 
---
--- Example tests for the ML-style state runner in ExcMLState.
---
--- In this example, the runner might raise an exception
--- if one tries to dereference a non-existent memory location.
---
--- For instance, in `test5` and `test8` below we deliberately
--- leak references out of an `mlTopLevel` block and feed them
--- to the next such block, where the references of course do 
--- not exist any more in the heap (that's initialised empty).
---
+{-|
+Module      : ExcMLStateTests
+Description : Example use cases of the runner for ML-style state from `Control.SignalRunner.ExcMLState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner 
+for ML-style state from `Control.SignalRunner.ExcMLState`.
+
+In this example, the runner might raise an exception
+if one tries to dereference a non-existent memory location.
+
+For instance, below we deliberately leak references out of 
+an `mlTopLevel` block and feed them to the next such block, 
+where the references of course do not exist any more in the heap
+(that's initialised empty), and cause an exception to be raised.
+-}
 module ExcMLStateTests where
 
 import Control.SignalRunner

examples/with_signals/MonotonicMLStateTests.hs

@@ -1,14 +1,21 @@
 {-# LANGUAGE DataKinds #-}
 
---
--- Tests for the monotonic state runner in `MonotonicMLState`.
---
--- In these examples, the runner might raise a kill signal
--- (i)  if one tries to dereference a non-existent memory location;
---      this is inherited from the runner in `SignalMLState`, or
--- (ii) if one tries to assign while violating monotonicity.
---
+{-|
+Module      : MonotonicMLStateTests
+Description : Example use cases of the runner for ML-style state from `Control.SignalRunner.MonotonicMLState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner 
+for ML-style state from `Control.SignalRunner.MonotonicMLState`.
+
+In these examples, the runner might raise a kill signal
+(i)  if one tries to dereference a non-existent memory location;
+     this is inherited from the runner in `SignalMLState`, or
+(ii) if one tries to assign while violating monotonicity.
+-}
 module MonotonicMLStateTests where
 
 import Control.SignalRunner

examples/with_signals/SignalMLStateTests.hs

@@ -1,17 +1,24 @@
 {-# LANGUAGE DataKinds #-}
 
---
--- Example tests for the ML-style state runner in SignalMLState.
---
--- In this example, the runner might raise a kill signal
--- if one tries to dereference a non-existent memory location.
---
--- For instance, in `test5` and `test8` below we deliberately
--- leak references out of an `mlTopLevel` block and feed them
--- to the next such block, where the references of course do 
--- not exist any more in the heap (that's initialised empty).
---
+{-|
+Module      : SignalMLStateTests
+Description : Example use cases of the runner for ML-style state from `Control.SignalRunner.SignalMLState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner 
+for ML-style state from `Control.SignalRunner.SignalMLState`.
+
+In this example, the runner might raise a kill signal
+if one tries to dereference a non-existent memory location.
+
+For instance, below we deliberately leak references out of 
+an `mlTopLevel` block and feed them to the next such block, 
+where the references of course do not exist any more in the 
+heap (that's initialised empty), and cause a signal to be sent.
+-}
 module SignalMLStateTests where
 
 import Control.SignalRunner

examples/without_signals/AmbientsTests.hs

@@ -3,10 +3,17 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE RankNTypes #-}
 
---
--- Tests for ambient values and ambient functions implemented as a runner in Ambients.
---
+{-|
+Module      : AmbientsTests
+Description : Example use cases of the runner for ambient values and ambient functions from `Control.Runner.Ambients`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides some example use cases of the runner for
+ambient values and ambient functions from `Control.Runner.Ambients`.
+-}
 module AmbientsTests where
 
 import Control.Runner

examples/without_signals/FPStateTests.hs

@@ -1,10 +1,17 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE GADTs #-}
 
---
--- Example tests for the footprint-based state runner in FPState.
---
+{-|
+Module      : FPStateTests
+Description : Example use cases of the footprint-based runner for state from `Control.Runner.FPState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the footprint-based 
+runners for state from `Control.Runner.FPState`.
+-}
 module FPStateTests where
 
 import Control.Runner

examples/without_signals/FileIOAndMLStateTests.hs

@@ -1,9 +1,16 @@
 {-# LANGUAGE DataKinds #-}
 
---
--- Example tests for the combination of file IO and ML-style state.
---
+{-|
+Module      : FileIOAndMLStateTests
+Description : Example use cases of the combination of file IO and ML-style state from `Control.Runner.FileIOAndMLState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides some example use cases of the combination of 
+file IO and ML-style state from `Control.Runner.FileIOAndMLState`.
+-}
 module FileIOAndMLStateTests where
 
 import Control.Runner

examples/without_signals/FileIOTests.hs

@@ -2,10 +2,17 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE GADTs #-}
 
---
--- Example tests for the file-runner in FileIO.
---
+{-|
+Module      : FileIOTests
+Description : Example use cases of the runners for file IO from `Control.Runner.FileIO`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides some example use cases of the 
+runners for file IO from `Control.Runner.FileIO`.
+-}
 module FileIOTests where
 
 import Control.Runner

examples/without_signals/IntStateTests.hs

@@ -1,9 +1,16 @@
 {-# LANGUAGE DataKinds #-}
 
---
--- Example tests for the integer-state runners in IntState.
---
+{-|
+Module      : IntStateTests
+Description : Example use cases of the runner for integer-valued state from `Control.Runner.IntState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner for 
+integer-valued state from `Control.Runner.IntState`.
+-}
 module IntStateTests where
 
 import Control.Runner

examples/without_signals/MLFPStateFwdTests.hs

@@ -1,15 +1,17 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE GADTs #-}
 
---
--- Example tests for running programs only on a footprint of the whole ML-style memory.
---
--- Here we use the variant of the footprint-based memory that internally only stores
--- the corresponding ML-style references and immediately delegates/forwards all get  
--- and put operations to the external MLState world (this is in contrast to the 
--- transactional variant of ML-style memory in MLFPState and MLFPStateTests).
---
+{-|
+Module      : MLFPStateFwdTests
+Description : Example use cases of the runner for footprint-based use of ML-style state from `Control.Runner.MLFPStateFwd`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner for footprint-based 
+use of ML-style state from `Control.Runner.MLFPStateFwd`.
+-}
 module MLFPStateFwdTests where
 
 import Control.Runner

examples/without_signals/MLFPStateTests.hs

@@ -1,10 +1,17 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE GADTs #-}
 
---
--- Example tests for running programs only on a footprint of the whole ML-style memory.
---
+{-|
+Module      : MLFPStateTests
+Description : Example use cases of the runner for footprint-based use of ML-style state from `Control.Runner.MLFPState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner for footprint-based 
+use of ML-style state from `Control.Runner.MLFPState`.
+-}
 module MLFPStateTests where
 
 import Control.Runner

examples/without_signals/MLStateTests.hs

@@ -2,10 +2,17 @@
 {-# LANGUAGE KindSignatures #-}
 {-# LANGUAGE RankNTypes #-}
 
---
--- Example tests for the ML-style state runner in MLState.
---
+{-|
+Module      : MLStateTests
+Description : Example use cases of the runner for ML-style state from `Control.Runner.MLState`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides example use cases of the runner 
+for ML-style state from `Control.Runner.MLState`.
+-}
 module MLStateTests where
 
 import Control.Runner

examples/without_signals/OldFileIOTests.hs

@@ -2,10 +2,17 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE GADTs #-}
 
---
--- Example tests for the file-runners in OldFileIO.
---
+{-|
+Module      : OldFileIOTests
+Description : Example use cases of the runners for file IO from `Control.Runner.OldFileIO`
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides some example use cases of the 
+runners for file IO from `Control.Runner.OldFileIO`.
+-}
 module OldFileIOTests where
 
 import Control.Runner

examples/without_signals/TwoLevelStateTest.hs

@@ -2,23 +2,30 @@
 {-# LANGUAGE GADTs #-}
 {-# LANGUAGE KindSignatures #-}
 
---
--- Experiments with a runner for simple 2-level state, 
--- where the bigger state has 2 locations and the smaller
--- state has 1 location, and a runner mediates between them.
---
+{-|
+Module      : TwoLevelStateTest
+Description : Example use of runners on a simple two-location integer-valued state
+Copyright   : (c) Danel Ahman, 2019
+License     : MIT
+Maintainer  : danel.ahman@eesti.ee
+Stability   : experimental
 
+This module provides an example use of runners on a simple two-location 
+integer-valued state, showing how runners can be used to "focus" on a 
+fraction of some bigger external resource, in this case on one of the 
+two memory locations of the `BigState` effect.
+-}
 module TwoLevelStateTest where
 
 import Control.Runner
 
-data BigState :: * -> * where
+data BigState a where
   Get1 :: BigState Int
   Put1 :: Int -> BigState ()
   Get2 :: BigState String
   Put2 :: String -> BigState ()
 
-data SmallState :: * -> * where
+data SmallState a where
   Get :: SmallState Int
   Put :: Int -> SmallState ()
 
@@ -86,4 +93,4 @@ bigStateComp =
     )
     bigStateFinally
 
-test = pureTopLevel bigStateComp
+test = pureTopLevel bigStateComp -- expected result (49,"new value")