Changeset 3904

Timestamp:

05/26/05 11:56:40 (3 years ago)

Author:

scook0

svk:copy_cache_prev:

5482

Message:

* Haddocks for Internals.hs
* Renamed 'enterLoop' to 'enterWhile'

Location:

src/Pugs

Files:

• Eval.hs (modified) (2 diffs)
• Internals.hs (modified) (4 diffs)
• Monads.hs (modified) (2 diffs)

src/Pugs/Eval.hs

@@ -676 +676 @@
     doWhileUntil f = do
         let [cond, body] = exps
-        enterLoop . fix $ \runLoop -> do
+        enterWhile . fix $ \runLoop -> do
             vbool <- enterEvalContext (cxtItem "Bool") cond
             vb    <- fromVal vbool
@@ -1181 +1181 @@
 
 doFetch :: (Val -> Eval (IVar VScalar))
-            -> (Val -> Eval Val)
-            -> (forall v. (Value v) => Eval v)
-            -> Bool -> Bool
-            -> Eval Val
+        -> (Val -> Eval Val)
+        -> (forall v. (Value v) => Eval v)
+        -> Bool
+        -> Bool
+        -> Eval Val
 doFetch fetchElem fetchVal fetchIdx isLV isSV = case (isLV, isSV) of
     (True, True) -> do

src/Pugs/Internals.hs

@@ -165 +165 @@
     bytes = map (toEnum . ord) str
 
-forM :: (Monad m) => [a] -> (a -> m b) -> m [b]
+{-|
+Take a list of values, and a monad-producing function, and apply that function
+to each element of the list. The resulting monads are combined into a single
+monad producing a list of the resulting values.
+
+(This is just @mapM@ with the arguments reversed.)
+-}
+forM :: (Monad m) 
+     => [a]        -- ^ List of values to loop over
+     -> (a -> m b) -- ^ The \'body\' of the for loop
+     -> m [b]      -- ^ Monad containing a list of the results
 forM = flip mapM
 
-forM_ :: (Monad m) => [a] -> (a -> m b) -> m ()
+{-|
+Take a list of values, and a monad-producing function, and apply that function
+to each element of the list in sequence. The values produced by the monadic
+function are discarded.
+
+(This is just @mapM_@ with the arguments reversed.)
+-}
+forM_ :: (Monad m) 
+      => [a]        -- ^ List of values to loop over
+      -> (a -> m b) -- ^ The \'body\' of the for loop
+      -> m ()
 forM_ = flip mapM_
 
@@ -174 +194 @@
 tryIO err = liftIO . (`catch` (const $ return err))
 
-combine :: [a->a] -> a -> a
+{-|
+Compose a list of @(a -> a)@ transformer functions into a single chained
+function, using @foldr@ via the @(.)@ operator.
+
+Note that the transformations are applied to the eventual argument in 
+right-to-left order.
+-}
+combine :: [a -> a] -- ^ List of transformer functions
+        -> (a -> a) -- ^ The final combined transformer
 combine = foldr (.) id
 
@@ -180 +208 @@
 unsafePerformSTM = unsafePerformIO . atomically
 
-modifyTVar :: TVar a -> (a -> a) -> STM ()
+{-|
+Read an STM variable, apply some transformation function to it, and write the
+transformed value back to the same variable.
+-}
+modifyTVar :: TVar a 
+           -> (a -> a) 
+           -> STM ()
 modifyTVar var f = do
     x <- readTVar var
@@ -188 +222 @@
 --     liftIO = unsafeIOToSTM
 
-maybeM :: (FunctorM f, Monad m) => m (f a) -> (a -> m b) -> m (f b)
+{-|
+Extract a @Maybe@ value from the first argument (a monad).
+
+If it's a @Just@ (i.e. it contains a value), apply the second argument
+(a monad-producing function) to it, and @return@ the contents of /that/ 
+wrapped in a @Just@.
+
+Otherwise, merely @return Nothing@.
+
+(Strictly speaking, this function can operate with any @FunctorM@, not just
+@Maybe@, but it helps to have a concrete example to explain things.)
+-}
+maybeM :: (FunctorM f, Monad m) 
+       => m (f a)    -- ^ A @Maybe@ value encapsulated in a monad
+       -> (a -> m b) -- ^ Action to perform on the first arg /if/ it contains
+                     --     a value
+       -> m (f b)    -- ^ Monad containing (@Just@ /result/) or @Nothing@
 maybeM f m = fmapM m =<< f
 
 {-|
-Transform an operator name, for example @&infix:<+>@ or @&prefix:«[+]»@, into
-its internal name (@&infix:+@ and @&prefix:[+]@ respectively).
+Transform an operator name, for example @&infix:\<+\>@ or @&prefix:«[+]»@, 
+into its internal name (@&infix:+@ and @&prefix:[+]@ respectively).
 -}
 possiblyFixOperatorName :: String -> String

src/Pugs/Monads.hs

@@ -92 +92 @@
         }
 
-enterLoop :: Eval Val -> Eval Val
-enterLoop action = genSymCC "&last" $ \symLast -> do
+{-|
+Bind @&last@ and @&next@ to subs that respectively break-out-of and repeat the 
+@while@\/@until@, then perform the given evaluation in the new lexical scope.
+
+Note that this function is /not/ responsible for performing the actual
+@while@\/@until@ test; it is the responsibility of the caller to add such a
+test to the top of the body evaluation.
+-}
+enterWhile :: Eval Val -- ^ Evaluation representing loop test & body
+           -> Eval Val
+enterWhile action = genSymCC "&last" $ \symLast -> do
     genSymPrim "&next" (const action) $ \symNext -> do
         enterLex [symLast, symNext] action
@@ -231 +240 @@
         } ]
 
+-- | (This doesn't seem to be used at the moment...)
 caller :: Int -> Eval Env
 caller n = do