Changeset 6359

Timestamp:

08/19/05 13:37:26 (3 years ago)

Author:

scook0

svk:copy_cache_prev:

8581

Message:

* Some docs for Lexer.hs and Parser/Types.hs
* Tweak DrIFT/Binary.hs so it doesn't confuse poor Haddock

Location:

src

Files:

• DrIFT/Binary.hs (modified) (4 diffs)
• Pugs/Lexer.hs (modified) (3 diffs)
• Pugs/Parser/Types.hs (modified) (3 diffs)

src/DrIFT/Binary.hs

@@ -108 +108 @@
 -}
 
--- #define SIZEOF_HSINT 4
+--  #define SIZEOF_HSINT 4
 
 type BinArray = IOUArray Int Word8
@@ -401 +401 @@
 
 instance Binary Int where
--- #if SIZEOF_HSINT == 4
+--  #if SIZEOF_HSINT == 4
     put_ bh i = put_ bh (fromIntegral i :: Int32)
     get  bh = do
         x <- get bh
         return $! (fromIntegral (x :: Int32))
--- #elif SIZEOF_HSINT == 8
+--  #elif SIZEOF_HSINT == 8
 --    put_ bh i = put_ bh (fromIntegral i :: Int64)
 --    get  bh = do
 --      x <- get bh
 --      return $! (fromIntegral (x :: Int64))
--- #else
--- #error "unsupported sizeof(HsInt)"
--- #endif
+--  #else
+--  #error "unsupported sizeof(HsInt)"
+--  #endif
 
 instance Binary ClockTime where
@@ -559 +559 @@
 
 -} 
--- #ifdef __GLASGOW_HASKELL__
+--  #ifdef __GLASGOW_HASKELL__
 
 instance Binary Integer where
@@ -625 +625 @@
     put_ bh (a :% b) = do put_ bh a; put_ bh b
     get bh = do a <- get bh; b <- get bh; return (a :% b)
--- #endif
+--  #endif
 
 instance Binary (Bin a) where

src/Pugs/Lexer.hs

@@ -136 +136 @@
     aheadSym x   y   = y `elem` ";!" || x /= y
 
-interpolatingStringLiteral :: RuleParser String    -- ^ Opening delimiter
-                              -> RuleParser String   -- ^ Closing delimiter 
-                              -> RuleParser Exp -- ^ Interpolator
-                              -> RuleParser Exp -- ^ Entire string
-                                                -- ^ (without delims)
+interpolatingStringLiteral :: RuleParser String -- ^ Opening delimiter
+                           -> RuleParser String -- ^ Closing delimiter 
+                           -> RuleParser Exp    -- ^ Interpolator
+                           -> RuleParser Exp    -- ^ Entire string
+                                                --     (without delims)
 interpolatingStringLiteral startrule endrule interpolator = do
     list <- stringList 0
@@ -154 +154 @@
     
     stringList :: Int -> RuleParser [Exp]
-    stringList i = try (do
-               parse <- interpolator
-               rest  <- stringList i
-               return (parse:rest))
-           <|> try (do
-               ch <- endrule
-               if i == 0 then return []
-                         else do rest <- stringList (i-1)
-                                 return (Val (VStr ch):rest))
-           <|> try (do
-               ch <- startrule
-               rest <- stringList (i+1)
-               return (Val (VStr ch):rest))
-           <|> do
-               char <- anyChar
-               rest <- stringList i
-               return (Val (VStr [char]):rest)
-
--- | backslahed nonalphanumerics (except for \^) translate into themselves
+    stringList i = tryChoice
+        [ do
+            parse <- interpolator
+            rest  <- stringList i
+            return (parse:rest)
+        , do
+            ch <- endrule
+            if i == 0
+                then return []
+                else do
+                    rest <- stringList (i-1)
+                    return (Val (VStr ch):rest)
+        , do
+            ch <- startrule
+            rest <- stringList (i+1)
+            return (Val (VStr ch):rest)
+        , do
+            char <- anyChar
+            rest <- stringList i
+            return (Val (VStr [char]):rest)
+        ]
+
+-- | Backslashed non-alphanumerics (except for @\^@) translate into themselves.
 escapeCode      :: GenParser Char st Char
 escapeCode      = charEsc <|> charNum <|> charAscii <|> charControl <|> anyChar
@@ -306 +310 @@
     return (lead:rest)
 
-tryChoice :: [GenParser tok st a] -> GenParser tok st a
+{-|
+Attempt each of the given parsers in turn until one succeeds, but if one of
+them fails we backtrack (i.e. retroactively consume no input) before trying
+the next one.
+-}
+tryChoice :: [GenParser tok st a] -- ^ List of candidate parsers
+          -> GenParser tok st a
 tryChoice = choice . map try
 
+{-|
+Match '@(@', followed by the given parser, followed by '@)@'.
+-}
 verbatimParens :: GenParser Char st a -> GenParser Char st a
 verbatimParens = between (lexeme $ char '(') (char ')')
 
+{-|
+Match '@\[@', followed by the given parser, followed by '@\]@'.
+-}
 verbatimBrackets :: GenParser Char st a -> GenParser Char st a
 verbatimBrackets = between (lexeme $ char '[') (char ']')
 
+{-|
+Match '@{@', followed by the given parser, followed by '@}@'.
+-}
 verbatimBraces :: GenParser Char st a -> GenParser Char st a
 verbatimBraces = between (lexeme $ char '{') (char '}')

src/Pugs/Parser/Types.hs

@@ -13 +13 @@
 import Pugs.Internals
 
+{-|
+Cache holding dynamically-generated parsers for user-defined operators.  This
+means we don't have to rebuild them for each token.
+
+The cache is generated inside 'Pugs.Parser.parseOpWith'.
+It is cleared each time we do compile-time evaluation with
+'Pugs.Parser.Unsafe.unsafeEvalExp', by calling 'clearDynParsers'.
+
+Stored inside 'RuleState', the state component of 'RuleParser'.
+-}
 data DynParsers = MkDynParsersEmpty | MkDynParsers
     { dynParseOp       :: !(RuleParser Exp)
@@ -19 +29 @@
     }
 
+{-|
+State object that gets passed around during the parsing process.
+-}
 data RuleState = MkRuleState
     { ruleEnv           :: !Env
-    , ruleDynParsers    :: !DynParsers
+    , ruleDynParsers    :: !DynParsers -- ^ Cache for dynamically-generated
+                                       --     parsers
     }
 
+{-|
+A parser that operates on @Char@s, and maintains state in a 'RuleState'.
+-}
 type RuleParser a = GenParser Char RuleState a
+
 data ParensOption = ParensMandatory | ParensOptional
     deriving (Show, Eq)
@@ -35 +53 @@
 type RuleOperatorTable a = OperatorTable Char RuleState a
 
+{-|
+Retrieve the 'Pugs.AST.Internals.Env' from the current state of the parser.
+-}
 getRuleEnv :: RuleParser Env
 getRuleEnv = gets ruleEnv
 
+{-|
+Update the 'Pugs.AST.Internals.Env' in the parser's state by applying a transformation function.
+-}
 modifyRuleEnv :: (MonadState RuleState m) => (Env -> Env) -> m ()
 modifyRuleEnv f = modify $ \state -> state{ ruleEnv = f (ruleEnv state) }
 
+{-|
+Replace the 'Pugs.AST.Internals.Env' in the parser's state with a new one.
+-}
 putRuleEnv :: Env -> RuleParser ()
 putRuleEnv = modifyRuleEnv . const
 
+{-|
+Clear the parser's cache of dynamically-generated parsers for user-defined
+operators.
+
+These will be re-generated by 'Pugs.Parser.parseOpWith' when needed.
+-}
 clearDynParsers :: RuleParser ()
 clearDynParsers = modify $ \state -> state{ ruleDynParsers = MkDynParsersEmpty }