diff --git a/Control/Monad/Queue/Allison.hs b/Control/Monad/Queue/Allison.hs
--- a/Control/Monad/Queue/Allison.hs
+++ b/Control/Monad/Queue/Allison.hs
@@ -15,8 +15,9 @@
--
--
-- For an explanation of the library implementation, see
--- /Lloyd Allison's Corecursive Queue: Why Continuations Matter/
--- by Leon P Smith, in /The Monad Reader/ issue 14.
+-- /Lloyd Allison's Corecursive Queues: Why Continuations Matter/
+-- by Leon P Smith, in /The Monad Reader/ issue 14. This library
+-- corresponds to @CorecQ@ in that paper.
--
-----------------------------------------------------------------------------
@@ -28,16 +29,16 @@
module Control.Monad.Queue.Allison
( Q()
, LenType
+ , runQueue
, enQ
- , peekQ
- , peekQn
- , peekQs
, deQ
, deQs
, deQ_break
+ , peekQ
+ , peekQn
+ , peekQs
, lenQ
, lenQ_
- , runQueue
, callCC
) where
@@ -56,9 +57,11 @@
callCC :: ((a -> forall b. Q e b) -> Q e a) -> Q e a
callCC f = Q (\k -> unQ (f (\a -> Q (\_ -> k a))) k)
+-- | Enqueues an element to the queue
enQ :: e -> Q e ()
enQ e = Q (\k n q -> e : (k () $! n+1) q)
+-- | Dequeues an element, returns 'Nothing' if the queue is empty.
deQ :: Q e (Maybe e)
deQ = Q delta
where
@@ -68,6 +71,7 @@
[] -> error "Control.Monad.Queue.Allison.deQ: empty list"
(e:q') -> (k (Just e) $! n-1) q'
+-- | Dequeues an element: terminates the queue computation if the queue is empty.
deQ_break :: Q e e
deQ_break = Q delta
where
@@ -77,6 +81,7 @@
[] -> error "Control.Monad.Queue.Allison.deQ_break: empty list"
(e:q') -> (k e $! n-1) q'
+-- | Dequeues up to @len@ elements from the queue
deQs :: Integral len => len -> Q e [e]
deQs i = Q delta
where
@@ -85,6 +90,7 @@
(res,q') = genericSplitAt i' q
in (k res $! n-i') q'
+-- | Examines the front element of the queue without removing it.
peekQ :: Q e (Maybe e)
peekQ = Q delta
where
@@ -94,6 +100,7 @@
[] -> error "Control.Monad.Queue.Allison.peekQ: empty list"
(e:_q') -> k (Just e) n q
+-- | Examines the element currently at position @index@ in the queue, indexing starts with @0@, like '!!'.
peekQn :: (Integral index) => index -> Q e (Maybe e)
peekQn i_ = Q delta
where
@@ -103,18 +110,22 @@
| n < i = k Nothing n q
| otherwise = k (Just (genericIndex q i)) n q
-peekQs :: (Integral len) => len -> Q e [e]
+-- | Examines up to @maxlen@ elements of the queue without removing them.
+peekQs :: (Integral maxlen) => maxlen -> Q e [e]
peekQs i_ = Q delta
where
i = fromIntegral i_
delta k n q = k (genericTake (min i n) q) n q
+-- | Returns the length of the queue
lenQ_ :: Q e LenType
lenQ_ = Q (\k n q -> k n n q)
+-- | Returns the length of the queue
lenQ :: Integral len => Q e len
lenQ = Q (\k n q -> k (fromIntegral n) n q)
+-- | Returns a list of all elements enqueued during the queue computation
runQueue :: Q e a -> [e]
runQueue m = q
where
diff --git a/Control/Monad/Queue/Class.hs b/Control/Monad/Queue/Class.hs
--- a/Control/Monad/Queue/Class.hs
+++ b/Control/Monad/Queue/Class.hs
@@ -18,12 +18,19 @@
import Control.Monad.Queue.Util
class Monad q => MonadQueue e q | q -> e where
+ -- | Enqueue an element to a queue
enQ :: e -> q ()
+ -- | Dequeue an element, returns 'Nothing' if the queue is empty.
+ deQ :: q (Maybe e)
+ -- | Dequeue up to @maxlen@ elements.
+ deQs :: Integral maxlen => maxlen -> q [e]
+ -- | Examines the front element of the queue without removing it.
peekQ :: q (Maybe e)
+ -- | Examines up to @maxlen@ elements of the queue without removing them.
peekQs :: Integral maxlen => maxlen -> q [e]
+ -- | Examines the element currently at position @index@, indexing starts at @0@.
peekQn :: Integral index => index -> q (Maybe e)
- deQ :: q (Maybe e)
- deQs :: Integral maxlen => maxlen -> q [e]
+ -- | Returns the current length of the queue
lenQ :: Integral len => q len
deQ = do
diff --git a/Control/Monad/Queue/Corec.hs b/Control/Monad/Queue/Corec.hs
--- a/Control/Monad/Queue/Corec.hs
+++ b/Control/Monad/Queue/Corec.hs
@@ -9,7 +9,10 @@
-- Portability : portable
--
-- Corecursive queues with return values. This is a straightforward
--- generalization of Control.Monad.Queue.Allison.
+-- generalization of Control.Monad.Queue.Allison. It corresponds to
+-- @CorecQW@ in the paper
+-- /Lloyd Allison's Corecursive Queues: Why Continuations Matter/ by
+-- Leon P Smith in the Monad Reader issue 14.
--
-----------------------------------------------------------------------------
@@ -18,21 +21,21 @@
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE RankNTypes #-}
-module Control.Monad.Queue.Corec
+module Control.Monad.Queue.Corec
( Q()
, LenType
+ , runResultQueue
+ , runResult
+ , runQueue
, enQ
- , peekQ
- , peekQn
- , peekQs
, deQ
, deQ_break
, deQs
+ , peekQ
+ , peekQn
+ , peekQs
, lenQ
, lenQ_
- , runQueue
- , runResult
- , runResultQueue
, mapQW
, callCC
) where
@@ -52,10 +55,12 @@
callCC :: ((a -> forall b. Q w e b) -> Q w e a) -> Q w e a
callCC f = Q $ \c -> unQ (f (\a -> Q $ \_ -> c a)) c
+-- | Enqueues an element to the queue
enQ :: e -> Q w e ()
enQ e = Q (\k n q -> let (w,es) = (k () $! n+1) q
in (w,e:es))
+-- | Dequeues and element: returns 'Nothing' if the queue is empty.
deQ :: Q w e (Maybe e)
deQ = Q delta
where
@@ -65,6 +70,7 @@
[] -> error "Control.Monad.Queue.Corec.deQ: empty list"
(e:q') -> (k (Just e) $! n-1) q'
+-- | Dequeues an element: terminates the computation with the final result @w@ if the queue is empty.
deQ_break :: w -> Q w e e
deQ_break w = Q delta
where
@@ -74,6 +80,7 @@
[] -> error "Control.Monad.Queue.Corec.deQ_break: empty list"
(e:q') -> (k e $! n-1) q'
+-- | Dequeues up to @len@ elements from the queue
deQs :: Integral len => len -> Q w e [e]
deQs i = Q delta
where
@@ -82,6 +89,7 @@
(res,q') = genericSplitAt i' q
in (k res $! n-i') q'
+-- | Examines the front element of the queue without removing it.
peekQ :: Q w e (Maybe e)
peekQ = Q delta
where
@@ -91,6 +99,7 @@
[] -> error "Control.Monad.Queue.Corec.peekQ: empty list"
(e:q') -> k (Just e) n q
+-- | Examines the element currently at position @index@ in the queue, indexing starts from @0@, like '!!'
peekQn :: (Integral index) => index -> Q w e (Maybe e)
peekQn i_ = Q delta
where
@@ -100,31 +109,39 @@
| n < i = k Nothing n q
| otherwise = k (Just (genericIndex q i)) n q
+-- | Looks at up to the first @len@ elements of the queue, like 'deQs' except without removing them.
peekQs :: (Integral len) => len -> Q w e [e]
peekQs i_ = Q delta
where
i = fromIntegral i_
delta k n q = k (genericTake (min i n) q) n q
+-- | Returns the length of the queue
lenQ_ :: Q w e LenType
lenQ_ = Q (\k n q -> k n n q)
+-- | Returns the length of the queue
lenQ :: Integral len => Q w e len
lenQ = Q (\k n q -> k (fromIntegral n) n q)
-
+-- | Applies a function to the final return value of the entire computation, like 'Control.Monad.Cont.mapCont'
mapQW :: (w -> w) -> Q w e a -> Q w e a
mapQW f m = Q (\k n q -> let (w,es) = unQ m k n q
- in (f w, es))
+ in (f w, es))
+-- | Runs the computation, returns the result of the computation and a list of all elements enqueued
runResultQueue :: Q a e a -> (a,[e])
runResultQueue m = st
where
st@(_a,q) = unQ m (\a _ _ -> (a,[])) 0 q
+
+-- | Runs the computation, returns the result of the computation
+--
runResult :: Q a e a -> a
runResult = fst . runResultQueue
+-- | Runs the computation, returns a list of all elements enqueued
runQueue :: Q a e a -> [e]
runQueue = snd . runResultQueue
diff --git a/Control/Monad/Queue/Util.hs b/Control/Monad/Queue/Util.hs
--- a/Control/Monad/Queue/Util.hs
+++ b/Control/Monad/Queue/Util.hs
@@ -14,4 +14,4 @@
import Data.Word
-type LenType = Word32
+type LenType = Word
diff --git a/control-monad-queue.cabal b/control-monad-queue.cabal
--- a/control-monad-queue.cabal
+++ b/control-monad-queue.cabal
@@ -1,5 +1,5 @@
Name: control-monad-queue
-Version: 0.0.9
+Version: 0.0.9.1
Description: Corecursive Queues
License: BSD3
License-file: LICENSE
@@ -7,7 +7,7 @@
Maintainer: Leon P Smith
Build-Type: Simple
Category: Control
-Synopsis: Resuable corecursive queues, via continuations.
+Synopsis: Reusable corecursive queues, via continuations.
Cabal-Version: >=1.2
Library