Comments

Author: paf31

docs/Text/Parsing/Parser.md

@@ -7,6 +7,8 @@ data ParseError
   = ParseError { message :: String, position :: Position }
 ```
 
+A parsing error, consisting of a message and position information.
+
 ##### Instances
 ``` purescript
 instance errorParseError :: Error ParseError
@@ -29,6 +31,10 @@ newtype ParserT s m a
   = ParserT (PState s -> m { input :: s, result :: Either ParseError a, consumed :: Boolean, position :: Position })
 ```
 
+The Parser monad transformer.
+
+The first type argument is the stream type. Typically, this is either `String`, or some sort of token stream.
+
 ##### Instances
 ``` purescript
 instance functorParserT :: (Functor m) => Functor (ParserT s m)
@@ -51,36 +57,48 @@ instance lazyParserT :: Lazy (ParserT s m a)
 unParserT :: forall m s a. ParserT s m a -> PState s -> m { input :: s, result :: Either ParseError a, consumed :: Boolean, position :: Position }
 ```
 
+Apply a parser by providing an initial state.
+
 #### `runParserT`
 
 ``` purescript
 runParserT :: forall m s a. (Monad m) => PState s -> ParserT s m a -> m (Either ParseError a)
 ```
 
+Apply a parser, keeping only the parsed result.
+
 #### `Parser`
 
 ``` purescript
 type Parser s a = ParserT s Identity a
 ```
 
+The `Parser` monad is a synonym for the parser monad transformer applied to the `Identity` monad.
+
 #### `runParser`
 
 ``` purescript
 runParser :: forall s a. s -> Parser s a -> Either ParseError a
 ```
 
+Apply a parser, keeping only the parsed result.
+
 #### `consume`
 
 ``` purescript
 consume :: forall s m. (Monad m) => ParserT s m Unit
 ```
 
+Set the consumed flag.
+
 #### `fail`
 
 ``` purescript
 fail :: forall m s a. (Monad m) => String -> ParserT s m a
 ```
 
+Fail with a message.
+
 #### `parseFailed`
 
 ``` purescript
@@ -89,6 +107,7 @@ parseFailed :: forall s a. s -> Position -> String -> { input :: s, result :: Ei
 
 Creates a failed parser state for the remaining input `s` and current position
 with an error message.
+
 Most of the time, `fail` should be used instead.
 
 

docs/Text/Parsing/Parser/Combinators.md

@@ -1,5 +1,7 @@
 ## Module Text.Parsing.Parser.Combinators
 
+Combinators for creating parsers.
+
 #### `(<?>)`
 
 ``` purescript
@@ -8,90 +10,138 @@
 
 _left-associative / precedence -1_
 
+Provide an error message in the case of failure.
+
 #### `between`
 
 ``` purescript
 between :: forall m s a open close. (Monad m) => ParserT s m open -> ParserT s m close -> ParserT s m a -> ParserT s m a
 ```
 
+Wrap a parser with opening and closing markers.
+
+For example:
+
+```purescript
+parens = between (string "(") (string ")")
+```
+
 #### `option`
 
 ``` purescript
 option :: forall m s a. (Monad m) => a -> ParserT s m a -> ParserT s m a
 ```
 
+Provide a default result in the case where a parser fails without consuming input.
+
 #### `optional`
 
 ``` purescript
 optional :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m Unit
 ```
 
+Optionally parse something, failing quietly.
+
 #### `optionMaybe`
 
 ``` purescript
-optionMaybe :: forall m s a. (Functor m, Monad m) => ParserT s m a -> ParserT s m (Maybe a)
+optionMaybe :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (Maybe a)
 ```
 
+Return `Nothing` in the case where a parser fails without consuming input.
+
 #### `try`
 
 ``` purescript
 try :: forall m s a. (Functor m) => ParserT s m a -> ParserT s m a
 ```
 
+In case of failure, reset the stream to the unconsumed state.
+
 #### `sepBy`
 
 ``` purescript
 sepBy :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited by a separator.
+
+For example:
+
+```purescript
+digit `sepBy` string ","
+```
+
 #### `sepBy1`
 
 ``` purescript
 sepBy1 :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited by a separator, requiring at least one match.
+
 #### `sepEndBy`
 
 ``` purescript
 sepEndBy :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited and optionally terminated by a separator.
+
 #### `sepEndBy1`
 
 ``` purescript
 sepEndBy1 :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited and optionally terminated by a separator, requiring at least one match.
+
 #### `endBy1`
 
 ``` purescript
 endBy1 :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited and terminated by a separator, requiring at least one match.
+
 #### `endBy`
 
 ``` purescript
 endBy :: forall m s a sep. (Monad m) => ParserT s m a -> ParserT s m sep -> ParserT s m (List a)
 ```
 
+Parse phrases delimited and terminated by a separator.
+
 #### `chainr`
 
 ``` purescript
 chainr :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a) -> a -> ParserT s m a
 ```
 
+Parse phrases delimited by a right-associative operator.
+
+For example:
+
+```purescript
+chainr digit (string "+" *> add) 0
+```
+
 #### `chainl`
 
 ``` purescript
 chainl :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a) -> a -> ParserT s m a
 ```
 
+Parse phrases delimited by a left-associative operator.
+
 #### `chainl1`
 
 ``` purescript
 chainl1 :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a) -> ParserT s m a
 ```
 
+Parse phrases delimited by a left-associative operator, requiring at least one match.
+
 #### `chainl1'`
 
 ``` purescript
@@ -104,6 +154,8 @@ chainl1' :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a
 chainr1 :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a) -> ParserT s m a
 ```
 
+Parse phrases delimited by a right-associative operator, requiring at least one match.
+
 #### `chainr1'`
 
 ``` purescript
@@ -116,40 +168,54 @@ chainr1' :: forall m s a. (Monad m) => ParserT s m a -> ParserT s m (a -> a -> a
 choice :: forall f m s a. (Foldable f, Monad m) => f (ParserT s m a) -> ParserT s m a
 ```
 
+Parse one of a set of alternatives.
+
 #### `skipMany`
 
 ``` purescript
 skipMany :: forall s a m. (Monad m) => ParserT s m a -> ParserT s m Unit
 ```
 
+Skip many instances of a phrase.
+
 #### `skipMany1`
 
 ``` purescript
 skipMany1 :: forall s a m. (Monad m) => ParserT s m a -> ParserT s m Unit
 ```
 
+Skip at least one instance of a phrase.
+
 #### `lookAhead`
 
 ``` purescript
 lookAhead :: forall s a m. (Monad m) => ParserT s m a -> ParserT s m a
 ```
 
+Parse a phrase, without modifying the consumed state or stream position.
+
 #### `notFollowedBy`
 
 ``` purescript
 notFollowedBy :: forall s a m. (Monad m) => ParserT s m a -> ParserT s m Unit
 ```
 
+Fail if the specified parser matches.
+
 #### `manyTill`
 
 ``` purescript
 manyTill :: forall s a m e. (Monad m) => ParserT s m a -> ParserT s m e -> ParserT s m (List a)
 ```
 
+Parse several phrases until the specified terminator matches.
+
 #### `many1Till`
 
 ``` purescript
 many1Till :: forall s a m e. (Monad m) => ParserT s m a -> ParserT s m e -> ParserT s m (List a)
 ```
 
+Parse several phrases until the specified terminator matches, requiring at least one match.
+
 

docs/Text/Parsing/Parser/Expr.md

@@ -24,16 +24,22 @@ data Operator m s a
 type OperatorTable m s a = Array (Array (Operator m s a))
 ```
 
-#### `SplitAccum`
+#### `buildExprParser`
 
 ``` purescript
-type SplitAccum m s a = { rassoc :: List (ParserT s m (a -> a -> a)), lassoc :: List (ParserT s m (a -> a -> a)), nassoc :: List (ParserT s m (a -> a -> a)), prefix :: List (ParserT s m (a -> a)), postfix :: List (ParserT s m (a -> a)) }
+buildExprParser :: forall m s a. (Monad m) => OperatorTable m s a -> ParserT s m a -> ParserT s m a
 ```
 
-#### `buildExprParser`
+Build a parser from an `OperatorTable`.
 
-``` purescript
-buildExprParser :: forall m s a. (Monad m) => OperatorTable m s a -> ParserT s m a -> ParserT s m a
+For example:
+
+```purescript
+buildExprParser [ [ Infix (string "/" $> div) AssocRight ]
+                , [ Infix (string "*" $> mul) AssocRight ]
+                , [ Infix (string "-" $> sub) AssocRight ]
+                , [ Infix (string "+" $> add) AssocRight ]
+                ] digit
 ```
 
 

docs/Text/Parsing/Parser/Pos.md

@@ -8,6 +8,7 @@ data Position
 ```
 
 `Position` represents the position of the parser in the input.
+
 - `line` is the current line in the input
 - `column` is the column of the next character in the current line that will be parsed