Docs

Also slipping in one intDecimal regex change

Author: jamesdbrock

README.md

@@ -89,15 +89,15 @@ There are other `String` parsers in the module `Parsing.String.Basic`, for examp
 
 Parser combinators are in this package in the module `Parsing.Combinators`.
 
-A parser combinator is a function which takes a parser as an argument and returns a new parser. The `Data.Array.many` combinator, for example, will repeat a parser as many times as it can. So the parser `many letter` will have type `Parser String (Array Char)`.
+A parser combinator is a function which takes a parser as an argument and returns a new parser. The `many` combinator, for example, will repeat a parser as many times as it can. So the parser `many letter` will have type `Parser String (List Char)`.
 
 Running the parser
 
 ```purescript
 runParser "aBabaB" (many ayebee)
 ```
 
-will return `Right [true, false, true]`.
+will return `Right (true : false : true : Nil)`.
 
 ### Stack-safety
 
@@ -114,15 +114,15 @@ stack-safe.
 
 The original short classic [FUNCTIONAL PEARLS *Monadic Parsing in Haskell*](https://www.cs.nott.ac.uk/~pszgmh/pearl.pdf) by Graham Hutton and Erik Meijer 1998.
 
-[*Revisiting Monadic Parsing in Haskell*](https://vaibhavsagar.com/blog/2018/02/04/revisiting-monadic-parsing-haskell/) by Vaibhav Sagar is a reflection on the Hutton, Meijer FUNCTIONAL PEARL.
+[*Parsec: Direct Style Monadic Parser Combinators For The Real World*](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/parsec-paper-letter.pdf) by Daan Leijen and Erik Meijer 2001.
 
 [*Parse, don't validate*](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) by Alexis King is about what it means to “parse” something, without any mention of monads.
 
+[*Revisiting Monadic Parsing in Haskell*](https://vaibhavsagar.com/blog/2018/02/04/revisiting-monadic-parsing-haskell/) by Vaibhav Sagar is a reflection on the Hutton, Meijer FUNCTIONAL PEARL.
+
 [*Parsec: “try a <|> b” considered harmful*](http://blog.ezyang.com/2014/05/parsec-try-a-or-b-considered-harmful/) by Edward Z. Yang is about how to decide when to backtrack
 from a failed alternative.
 
-[*Parsec: Direct Style Monadic Parser Combinators For The Real World*](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/parsec-paper-letter.pdf) by Daan Leijen and Erik Meijer 2001.
-
 [*Parser Combinators in Haskell*](https://serokell.io/blog/parser-combinators-in-haskell) by Heitor Toledo Lassarote de Paula.
 
 There are lots of other great monadic parsing tutorials on the internet.

src/Parsing/String/Basic.purs

@@ -71,12 +71,12 @@ alphaNum = satisfyCP isAlphaNum <?> "letter or digit"
 
 -- | Parser based on the __Data.Number.fromString__ function.
 -- |
--- | This should be the inverse of `show :: String -> Number`.
+-- | This should be the inverse of `show :: Number -> String`.
 -- |
 -- | Examples of strings which can be parsed by this parser:
 -- | * `"3"`
 -- | * `"3.0"`
--- | * `"0.3"`
+-- | * `".3"`
 -- | * `"-0.3"`
 -- | * `"+0.3"`
 -- | * `"-3e-1"`
@@ -91,24 +91,26 @@ number =
     , string "-Infinity" *> pure (negate infinity)
     , string "NaN" *> pure nan
     , tryRethrow $ do
+        -- This primitiv-ish parser should always backtrack on fail.
+        -- Currently regex allows some illegal inputs, like "."
+        -- The important thing is that the regex will find the correct
+        -- boundary of a candidate string to pass to fromString.
         section <- numberRegex
         -- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat
         case Data.Number.fromString section of
           Nothing -> fail $ "Number.fromString failed"
-          -- Maybe this parser should set consumed flag if regex matches but fromString fails?
-          -- But currently regex allows some illegal inputs, like "."
-          -- Anyway this primitiv-ish parser should always backtrack on fail.
           Just x -> pure x
     ] <|> fail "Expected Number"
 
+-- Non-exported regex is compiled at startup time.
 numberRegex :: forall m. ParserT String m String
 numberRegex = either unsafeCrashWith identity $ regex pattern mempty
   where
   pattern = "[+-]?[0-9]*(\\.[0-9]*)?([eE][+-]?[0-9]*(\\.[0-9]*))?"
 
 -- | Parser based on the __Data.Int.fromString__ function.
 -- |
--- | This should be the inverse of `show :: String -> Int`.
+-- | This should be the inverse of `show :: Int -> String`.
 -- |
 -- | Examples of strings which can be parsed by this parser:
 -- | * `"3"`
@@ -121,10 +123,11 @@ intDecimal = tryRethrow do
     Nothing -> fail $ "Int.fromString failed"
     Just x -> pure x
 
+-- Non-exported regex is compiled at startup time.
 intDecimalRegex :: forall m. ParserT String m String
 intDecimalRegex = either unsafeCrashWith identity $ regex pattern mempty
   where
-  pattern = "[+-]?[0-9]*"
+  pattern = "[+-]?[0-9]+"
 
 -- | Helper function
 satisfyCP :: forall m. (CodePoint -> Boolean) -> ParserT String m Char

src/Parsing/String/Replace.purs

@@ -113,8 +113,8 @@ breakCapT input sep = hush <$> runParserT input go
 
 -- | #### Break on and capture one pattern
 -- |
--- | Find the first occurence of a pattern in a text stream, capture the found
--- | pattern, and break the input text stream on the found pattern.
+-- | Find the first occurence of a pattern in the input `String`, capture the found
+-- | pattern, and break the input `String` on the found pattern.
 -- |
 -- | This function can be used instead of
 -- | [Data.String.indexOf](https://pursuit.purescript.org/packages/purescript-strings/docs/Data.String#v:indexOf)
@@ -139,8 +139,8 @@ breakCapT input sep = hush <$> runParserT input go
 -- |
 -- | #### Access the matched section of text
 -- |
--- | If you want to capture the matched string, then combine the pattern
--- | parser `sep` with `match`.
+-- | To capture the matched string combine the pattern
+-- | parser `sep` with the `match` combinator.
 -- |
 -- | With the matched string, we can reconstruct the input string.
 -- | For all `input`, `sep`, if
@@ -317,8 +317,8 @@ splitCapCombinator sep = tailRecM accum { carry: Nothing, rlist: Nil, arraySize:
 
 -- | #### Split on and capture all patterns
 -- |
--- | Find all occurences of the pattern parser `sep`, split the input string,
--- | capture all the patterns and the splits.
+-- | Find all occurences of the pattern parser `sep`, split the
+-- | input `String`, capture all the matched patterns and the splits.
 -- |
 -- | This function can be used instead of
 -- | [Data.String.Common.split](https://pursuit.purescript.org/packages/purescript-strings/docs/Data.String.Common#v:split)
@@ -332,11 +332,11 @@ splitCapCombinator sep = tailRecM accum { carry: Nothing, rlist: Nil, arraySize:
 -- | The input string will be split on every leftmost non-overlapping occurence
 -- | of the pattern `sep`. The output list will contain
 -- | the parsed result of input string sections which match the `sep` pattern
--- | in `Right`, and non-matching sections in `Left`.
+-- | in `Right a`, and non-matching sections in `Left String`.
 -- |
 -- | #### Access the matched section of text
 -- |
--- | If you want to capture the matched strings, then combine the pattern
+-- | To capture the matched strings combine the pattern
 -- | parser `sep` with the `match` combinator.
 -- |
 -- | With the matched strings, we can reconstruct the input string.
@@ -491,7 +491,7 @@ replaceT input sep = do
 -- | of the leftmost non-overlapping sections of the input string which match
 -- | the pattern parser `sep`, and
 -- | replace them with the result of the parser.
--- | The `sep` parser must return a result of type `String`.
+-- | The `sep` parser must return a result of type `String` for the replacement.
 -- |
 -- | This function can be used instead of
 -- | [Data.String.replaceAll](https://pursuit.purescript.org/packages/purescript-strings/docs/Data.String#v:replaceAll)
@@ -500,11 +500,11 @@ replaceT input sep = do
 -- |
 -- | #### Access the matched section of text in the `editor`
 -- |
--- | To get access to the matched string for the replacement
+-- | To get access to the matched string for calculating the replacement,
 -- | combine the pattern parser `sep`
--- | with `match`.
+-- | with the `match` combinator.
 -- | This allows us to write a `sep` parser which can choose to not
--- | edit the match and just leave it as it is.
+-- | replace the match and just leave it as it is.
 -- |
 -- | So, for all `sep`:
 -- |