Changeset 6375

Timestamp:

08/20/05 14:21:35 (3 years ago)

Author:

scook0

svk:copy_cache_prev:

8581

Message:

* Haddocks for use/no/require in Parser.hs

Files:

• src/Pugs/Parser.hs (modified) (7 diffs)

src/Pugs/Parser.hs

@@ -594 +594 @@
         _      -> return $ Pad scope lexDiff rhs
 
+{-|
+Match a @no@ declaration, i.e. the opposite of @use@ (see
+'ruleUseDeclaration').
+
+Works by matching \'@no@\', then delegating to 'ruleUsePackage' with the flag
+set to @False@.
+-}
 ruleNoDeclaration :: RuleParser Exp
 ruleNoDeclaration = rule "no declaration" $ do
@@ -600 +607 @@
     return emptyExp
 
+{-|
+Match a @use@ declaration.
+
+Works by matching \'@use@\', then trying each of 'ruleUseVersion',
+'ruleUseJSANModule' and 'ruleUsePackage'.
+-}
 ruleUseDeclaration :: RuleParser Exp
 ruleUseDeclaration = rule "use declaration" $ do
@@ -621 +634 @@
     return ()
 
-ruleUsePackage :: Bool -> RuleParser ()
+{-|
+Match the package-name and import-list part of a @use@ or @no@ declaration.
+
+The parser itself does not yield a useful value; instead it modifies the
+'Pugs.AST.Internals.Env' part of the parser's state to reflect the results
+of the declaration.  (If the package is a Perl 5 package, the modification
+will be different.)
+
+It is assumed that the @use@ or @no@ has already been consumed by
+'ruleUseDeclaration' or 'ruleNoDeclaration'.
+-}
+ruleUsePackage :: Bool -- ^ @True@ for @use@; @False@ for @no@
+               -> RuleParser ()
 ruleUsePackage use = rule "use package" $ do
     lang    <- option "pugs" $ try $ do
@@ -655 +680 @@
     return ()
 
+{-|
+Match a JSAN module name, preceded by \'@jsan:@\'.  Returns an appropriate
+sub call 'Pugs.AST.Exp' that will load the module using subs defined in
+@PIL2JS::Internals@.
+
+Used by 'ruleUseDeclaration' after matching \'@use@\'.
+
+More info about JSAN can be found at <http://www.openjsan.org/>.
+
+(This parser is screaming out to be refactored and merged with
+'ruleUseVersion', but that might be a little hairy to actually do.)
+-}
 ruleUseJSANModule :: RuleParser Exp
 ruleUseJSANModule = do
@@ -673 +710 @@
         ] 
 
--- | The version part of a full class specification.
+-- | The version part of a fully-qualified package name.
 ruleVersionPart :: RuleParser String
 ruleVersionPart = do -- version - XXX
@@ -680 +717 @@
     return ('-':str)
 
--- | The author part of a full class specification.
+-- | The author part of a fully-qualified package name.
 ruleAuthorPart :: RuleParser String
 ruleAuthorPart = do -- author - XXX
@@ -697 +734 @@
         _ -> fail "not yet parsed"
 
+{-|
+Match a @require@ declaration, returning a sub call 'Pugs.AST.Exp' that will
+load the package at runtime.
+
+(This should probably be merged with 'ruleUseDeclaration' & friends, if
+anybody has some tuits.)
+-}
 ruleRequireDeclaration :: RuleParser Exp
 ruleRequireDeclaration = tryRule "require declaration" $ do