Changeset 3249

Show
Ignore:
Timestamp:
05/15/05 12:13:50 (4 years ago)
Author:
scook0
svk:copy_cache_prev:
4802
Message:

Haddocks for Monads.hs

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • src/Pugs/Monads.hs

    r3148 r3249  
    88>   One Ring to bring them all 
    99>   and in the darkness bind them... 
     10 
     11    Note that the actual monads are defined elsewhere -- try looking at 
     12    "Pugs.AST.SIO" and "Pugs.AST.Internals". 
    1013-} 
    1114 
    … …  
    1518import Pugs.Context 
    1619import Pugs.Types 
    17  
    18 {-| 
    19     Note that the actual monads are defined elsewhere -- try looking at 
    20     "Pugs.AST.SIO" and "Pugs.AST.Internals". 
    21 -} 
    2220 
    2321-- |Perform the specified evaluation in a lexical scope that has been 
    … …  
    4644    enterLex [sym] action 
    4745 
    48 enterWhen :: Exp -> Eval Val -> Eval Val 
     46{-| 
     47Bind @&continue@ and @&break@ to subs that break out of the @when@ body 
     48and topicalising block respectively, then perform the given evaluation 
     49in the new lexical scope. 
     50 
     51Note that this function is /not/ responsible for performing the actual @when@ 
     52test, nor is it responsible for adding the implicit @break@ to the end of the 
     53@when@'s block--those are already taken care of by 'Pugs.Eval.reduce' 
     54(see the entry for @('Syn' \"when\" ... )@). 
     55-} 
     56enterWhen :: Exp      -- ^ The expression that @&break@ should be bound to 
     57          -> Eval Val -- ^ The @when@'s body block, as an evaluation 
     58          -> Eval Val 
    4959enterWhen break action = callCC $ \esc -> do 
    5060    env <- ask 
    … …  
    6979        enterLex [symLast, symNext] action 
    7080 
     81{-| 
     82Generate a new Perl6 operation from a Haskell function, give it a name, and 
     83generate a @('Pad' -> 'Pad')@ transformer that can be used to install it into 
     84a pad. 
     85 
     86This transformer is passed into a given \'action\' function, which is 
     87expected to apply the pad-transformer (e.g. in a new lexical scope), then 
     88perform some evaluation in that scope. 
     89 
     90Most of the time, this \'action\' is an anonymous function that passes its 
     91argument into 'enterLex'. 
     92-} 
    7193genSymPrim :: (MonadSTM m)  
    72            => String  
    73            -> ([Val] -> Eval Val)      
    74            -> ((Pad -> Pad) -> m t) 
    75            -> m t 
     94           => String                -- ^ Name installed in 'Pad' 
     95                                    --     (must have leading @&@ sigil) 
     96           -> ([Val] -> Eval Val)   -- ^ The actual primitive to wrap 
     97           -> ((Pad -> Pad) -> m t) -- ^ A (lambda) function that the 'Pad' 
     98                                    --     transformer is given to 
     99           -> m t -- ^ Result of passing the pad-transformer to the \'action\' 
    76100genSymPrim symName@('&':name) prim action = do 
    77101    newSym <- genSym symName . codeRef $ mkPrim 
    … …  
    82106genSymPrim _ _ _ = error "need a &name" 
    83107 
    84 genSymCC :: String 
    85          -> ((Pad -> Pad) -> Eval Val) 
    86          -> Eval Val 
     108{-| 
     109Generate a Perl6 primitive that, when called, will activate the /current/ 
     110continuation (i.e. one that can be used to immediately break out of whatever  
     111evaluation we are about to perform). This is great for @&last@ and the like. 
     112 
     113This produces a pad-transformer @('Pad' -> 'Pad')@. This transformer is given 
     114to an \'action\' function, which is expected to apply it (e.g. in a lexical 
     115scope), then perform some evaluation in that scope. 
     116-} 
     117genSymCC :: String -- ^ Name of the primitive in the symbol table ('Pad'). 
     118         -> ((Pad -> Pad) -> Eval Val) -- ^ An \'action\' function that will 
     119                                       --     take the pad-transformer and use 
     120                                       --     it to perform some evaluation  
     121         -> Eval Val -- ^ Result of passing the pad-transformer to the  
     122                     --     \'action\' 
    87123genSymCC symName action = callCC $ \esc -> do 
    88124    genSymPrim symName (const $ esc undef) action 
    89125 
    90126{-| 
    91 Perform the specified evaluation in a new lexical scope in which 
    92 @&?BLOCK_EXIT@ is bound to a continuation that will break out of the block 
    93 when called. (Actually, @&?BLOCK_EXIT@ is bound to a 'Prim' 'VCode' 
    94 that is /implemented/ using the continuation.) Used by 'Pugs.Eval.reduce' 
    95 when evaluating @('Syn' \"block\" ... )@ expressions. 
     127Create a Perl6 @&?BLOCK_EXIT@ function that, when activated, breaks out of 
     128the block scope by activating the current continuation. The block body 
     129evaluation is then performed in a new lexical scope with @&?BLOCK_EXIT@ 
     130installed. 
     131 
     132Used by 'Pugs.Eval.reduce' when evaluating @('Syn' \"block\" ... )@  
     133expressions. 
    96134-} 
    97135enterBlock :: Eval Val -> Eval Val