I went ahead and pushed these two, but I have some metacomments on the
haddock
Remove (unused) lazy parser monad
---------------------------------
haddock ReadMonads
------------------
> +-- | This module defines our parsing monad. In the past there have been lazy
> +-- and strict parsers in this module. Currently we have only the strict
> +-- variant and it is used for parsing patch files.
The historical note seems helpful because it hints at a possible path we
can explore later.
> +-- | 'lex_char' checks if the next space delimited token from
> +-- the input stream matches a specific 'Char'.
> +-- Uses 'Maybe' inside 'ParserM' to handle failed matches, so
> +-- | 'lex_string' fetches the next whitespace delimited token from
> +-- from the input and checks if it matches the 'String' input.
> +-- Uses 'Maybe' inside 'ParserM' to handle failed matches, so
> +-- that it always returns () on success.
> +-- | 'lex_eof' looks for optional spaces followed by the end of input.
> +-- Uses 'Maybe' inside 'ParserM' to handle failed matches, so
> +-- that it always returns () on success.
> +-- | Checks if any of the input 'String's match the next
> +-- space delimited token in the input stream.
> +-- Uses 'Maybe' inside 'ParserM' to handle failed matches,
> +-- on success it returns the matching 'String'.
There seems to be a bit of redundancy/repetition in these comments that
I think we can cut out.
It sounds like we just need one more general comment somewhere that the
parsers can fail, and for these functions that they return () or the
matching 'String' respectively. Also, it sounds like we could make a
more general statement that the lex_ functions work with
whitespace-delimited tokens.
I think cutting out that redundancy would give these comments more of
a high-level feel.
> +-- | 'my_lex' drops leading spaces and then breaks the string at the
> +-- next space. Returns 'Nothing' when the string is empty after
> +-- dropping leading spaces, otherwise it returns the first sequence
> +-- of non-spaces and the remainder of the input.
This also seems rather low-level and it seems like it may be implying
too much.
Would something like this be better, or are we saying too little/the
wrong thing?
'my_lex' returns the next whitespace-delimited token along with the
remainder of the input. If there are no more tokens, it fails.
Here, a token is just a string without whitespace.
> + -- | Applies a parsing function, that can return 'Nothing',
> + -- inside the 'ParserM' monad.
> maybe_work :: (B.ByteString -> Maybe (a, B.ByteString)) -> m (Maybe a)
Perhaps the point isn't that the function can return 'Nothing' -- that's
also true for 'work' -- but that the parsing still continues even if the
function returns Nothing (we carry on as if we had never tried the
function at all).
> +-- | 'parse_strictly' applies the parser functions to a string
> +-- and checks that each parser produced a result as it goes.
> +-- The strictness is in the 'ParserM' instance for 'SM'.
That last remark was helpful for me :-)
--
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
|
