Merge pull request purescript-contrib#17 from kRITZCREEK/master

Extend Combinator Documentation

Author: paf31

docs/Text/Parsing/Parser/Combinators.md

@@ -2,6 +2,25 @@
 
 Combinators for creating parsers.
 
+### Notes:
+A few of the known combinators from Parsec are missing in this module. That
+is because they have already been defined in other libraries.
+
+```purescript
+Text.Parsec.many  = Data.(Array|List).many
+Text.Parsec.many1 = Data.(Array|List).some
+Text.Parsec.(<|>) = Control.Alt.alt (<|>)
+```
+
+Because Strings are not Char Arrays in PureScript `many` and `some` on Char Parsers need to
+be used in conjunction with `Data.String.fromCharArray` to achieve "Parsec-like" results.
+
+```purescript
+Text.Parsec.many  (char 'x') <=> fromCharArray <$> Data.Array.many (char 'x')
+```
+
+===
+
 #### `(<?>)`
 
 ``` purescript

src/Text/Parsing/Parser/Combinators.purs

@@ -1,4 +1,23 @@
 -- | Combinators for creating parsers.
+-- |
+-- | ### Notes:
+-- | A few of the known combinators from Parsec are missing in this module. That
+-- | is because they have already been defined in other libraries.
+-- |
+-- | ```purescript
+-- | Text.Parsec.many  = Data.(Array|List).many
+-- | Text.Parsec.many1 = Data.(Array|List).some
+-- | Text.Parsec.(<|>) = Control.Alt.alt (<|>)
+-- | ```
+-- |
+-- | Because Strings are not Char Arrays in PureScript `many` and `some` on Char Parsers need to
+-- | be used in conjunction with `Data.String.fromCharArray` to achieve "Parsec-like" results.
+-- |
+-- | ```purescript
+-- | Text.Parsec.many  (char 'x') <=> fromCharArray <$> Data.Array.many (char 'x')
+-- | ```
+-- |
+-- | ===
 
 module Text.Parsing.Parser.Combinators where
 
@@ -30,7 +49,7 @@ import Text.Parsing.Parser
 -- | Wrap a parser with opening and closing markers.
 -- |
 -- | For example:
--- | 
+-- |
 -- | ```purescript
 -- | parens = between (string "(") (string ")")
 -- | ```
@@ -64,7 +83,7 @@ try p = ParserT $ \(PState { input: s, position: pos }) -> try' s pos <$> unPars
 -- | Parse phrases delimited by a separator.
 -- |
 -- | For example:
--- | 
+-- |
 -- | ```purescript
 -- | digit `sepBy` string ","
 -- | ```
@@ -109,7 +128,7 @@ endBy p sep = many $ do
 -- | Parse phrases delimited by a right-associative operator.
 -- |
 -- | For example:
--- | 
+-- |
 -- | ```purescript
 -- | chainr digit (string "+" *> add) 0
 -- | ```