New module Parsing.Combinators.Array

For fast combinator variations which return Array.

Author: jamesdbrock

CHANGELOG.md

@@ -8,6 +8,8 @@ Breaking changes:
 
 New features:
 
+- Add `Array` combinators in a new `Combinators.Array` module (#199 by @jamesdbrock)
+
 Bugfixes:
 
 Other improvements:

README.md

@@ -90,15 +90,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 `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)`.
+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 (Array Char)`.
 
 Running the parser
 
 ```purescript
 runParser "aBabaB" (many ayebee)
 ```
 
-will return `Right (true : false : true : Nil)`.
+will return `Right [true, false, true]`.
 
 ## Stack-safety
 

bench/Main.purs

@@ -70,6 +70,7 @@ import Effect.Exception (throw)
 import Effect.Unsafe (unsafePerformEffect)
 import Parsing (runParser)
 import Parsing.Combinators (chainl, chainr, many, manyTill, manyTill_, sepBy, sepEndBy1, skipMany)
+import Parsing.Combinators.Array as Combinators.Array
 import Parsing.String (anyChar, eof, string)
 import Parsing.String.Basic (digit)
 import Performance.Minibench (benchWith)
@@ -160,6 +161,8 @@ main = do
     $ \_ -> throwLeft $ runParser string23_10000 (many anyChar)
   htmlTableWrap "runParser Array.many anyChar 10000" $ benchWith 50
     $ \_ -> throwLeft $ runParser string23_10000 (Array.many anyChar)
+  htmlTableWrap "runParser Combinators.Array.many anyChar 10000" $ benchWith 50
+    $ \_ -> throwLeft $ runParser string23_10000 (Combinators.Array.many anyChar)
 
   log "<th><h2>skipMany anyChar 10000</h2></th>"
   htmlTableWrap "runParser skipMany anyChar 10000" $ benchWith 50

src/Parsing/Combinators.purs

@@ -15,8 +15,8 @@
 -- |
 -- | ### Data.Array
 -- |
--- | Expect better parsing speed from the `List`-based combinators in this
--- | module than from `Array`-based combinators.
+-- | The `many` and `many1` combinators in the __Parsing.Combinators.Array__
+-- | module are faster.
 -- |
 -- | * [Data.Array.many](https://pursuit.purescript.org/packages/purescript-arrays/docs/Data.Array#v:many)
 -- | * [Data.Array.some](https://pursuit.purescript.org/packages/purescript-arrays/docs/Data.Array#v:some)
@@ -204,15 +204,15 @@ lookAhead (ParserT k1) = ParserT
         (mkFn2 \_ res -> runFn2 done state1 res)
   )
 
--- | Match the parser `p` as many times as possible.
+-- | Match the phrase `p` as many times as possible.
 -- |
 -- | If `p` never consumes input when it
 -- | fails then `many p` will always succeed,
 -- | but may return an empty list.
 many :: forall s m a. ParserT s m a -> ParserT s m (List a)
 many = List.manyRec
 
--- | Match one or more times.
+-- | Match the phrase `p` as many times as possible, at least once.
 many1 :: forall m s a. ParserT s m a -> ParserT s m (NonEmptyList a)
 many1 p = NEL.cons' <$> p <*> List.manyRec p
 
@@ -434,14 +434,13 @@ manyTill_ :: forall s a m e. ParserT s m a -> ParserT s m e -> ParserT s m (Tupl
 manyTill_ p end = tailRecM go Nil
   where
   go :: List a -> ParserT s m (Step (List a) (Tuple (List a) e))
-  go xs =
+  go xs = alt
     do
       t <- end
       pure (Done (Tuple (reverse xs) t))
-      <|>
-        do
-          x <- p
-          pure (Loop (x : xs))
+    do
+      x <- p
+      pure (Loop (x : xs))
 
 -- | Parse the phrase as many times as possible, at least *N* times, but no
 -- | more than *M* times.
@@ -462,17 +461,15 @@ manyIndex from to p =
   go (Tuple i xs) =
     if i >= to then
       pure (Done (Tuple i (reverse xs)))
-    else
-      ( do
-          x <- p i
-          pure (Loop (Tuple (i + 1) (x : xs)))
-      )
-        <|>
-          ( if i >= from then
-              pure (Done (Tuple i (reverse xs)))
-            else
-              fail "Expected more phrases"
-          )
+    else alt
+      do
+        x <- p i
+        pure (Loop (Tuple (i + 1) (x : xs)))
+      do
+        if i >= from then
+          pure (Done (Tuple i (reverse xs)))
+        else
+          fail "Expected more phrases"
 
 -- | If the parser succeeds without advancing the input stream position,
 -- | then force the parser to fail.

src/Parsing/Combinators/Array.purs

@@ -0,0 +1,96 @@
+-- | These combinators will produce `Array`s, as opposed to the other combinators
+-- | of the same names in the __Parsing.Combinators__ module
+-- | which mostly produce `List`s. These `Array` combinators will run in a bit
+-- | less time (*~85% runtime*) than the similar `List` combinators, and they will run in a
+-- | lot less time (*~10% runtime*) than the similar combinators in __Data.Array__.
+-- |
+-- | If there is some other combinator which returns
+-- | a `List` but we want an `Array`, and there is no `Array` version of the
+-- | combinator in this module, then we can rely on the
+-- | [__`Data.Array.fromFoldable`__](https://pursuit.purescript.org/packages/purescript-arrays/docs/Data.Array#v:fromFoldable)
+-- | function for a pretty fast transformation from `List` to `Array`.
+module Parsing.Combinators.Array
+  ( many
+  , many1
+  , manyTill_
+  , manyIndex
+  ) where
+
+import Prelude
+
+import Control.Alt (alt)
+import Control.Monad.Rec.Class (Step(..), tailRecM)
+import Data.Array as Array
+import Data.Array.NonEmpty (NonEmptyArray)
+import Data.Array.NonEmpty as Array.NonEmpty
+import Data.List (List(..), (:))
+import Data.Maybe (Maybe(..))
+import Data.Tuple (Tuple(..))
+import Parsing (ParserT, fail)
+import Parsing.Combinators (try)
+
+-- | Match the phrase `p` as many times as possible.
+-- |
+-- | If `p` never consumes input when it
+-- | fails then `many p` will always succeed,
+-- | but may return an empty array.
+many :: forall s m a. ParserT s m a -> ParserT s m (Array a)
+many p = do
+  rlist <- flip tailRecM Nil $ \xs -> alt
+    do
+      x <- try p
+      pure (Loop (x : xs))
+    do
+      pure (Done xs)
+  pure $ Array.reverse $ Array.fromFoldable rlist
+
+-- | Match the phrase `p` as many times as possible, at least once.
+many1 :: forall s m a. ParserT s m a -> ParserT s m (NonEmptyArray a)
+many1 p = do
+  xs <- many p
+  case Array.NonEmpty.fromArray xs of
+    Nothing -> fail "Expected at least 1"
+    Just xs' -> pure xs'
+
+-- | Parse many phrases until the terminator phrase matches.
+-- | Returns the list of phrases and the terminator phrase.
+manyTill_ :: forall s a m e. ParserT s m a -> ParserT s m e -> ParserT s m (Tuple (Array a) e)
+manyTill_ p end = do
+  Tuple rlist e <- flip tailRecM Nil \xs -> alt
+    do
+      t <- end
+      pure (Done (Tuple xs t))
+    do
+      x <- p
+      pure (Loop (x : xs))
+  pure $ Tuple (Array.reverse $ Array.fromFoldable rlist) e
+
+-- | Parse the phrase as many times as possible, at least *N* times, but no
+-- | more than *M* times.
+-- | If the phrase can’t parse as least *N* times then the whole
+-- | parser fails. If the phrase parses successfully *M* times then stop.
+-- | The current phrase index, starting at *0*, is passed to the phrase.
+-- |
+-- | Returns the array of parse results and the number of results.
+-- |
+-- | `manyIndex n n (\_ -> p)` is equivalent to `replicateA n p`.
+manyIndex :: forall s m a. Int -> Int -> (Int -> ParserT s m a) -> ParserT s m (Tuple Int (Array a))
+manyIndex from to p =
+  if from > to || from < 0 then
+    pure (Tuple 0 [])
+  else do
+    Tuple n rlist <- tailRecM go (Tuple 0 Nil)
+    pure $ Tuple n $ Array.reverse $ Array.fromFoldable rlist
+  where
+  go (Tuple i xs) =
+    if i >= to then
+      pure (Done (Tuple i xs))
+    else alt
+      do
+        x <- p i
+        pure (Loop (Tuple (i + 1) (x : xs)))
+      do
+        if i >= from then
+          pure (Done (Tuple i xs))
+        else
+          fail "Expected more phrases"

test/Main.purs

@@ -35,6 +35,7 @@ import Effect.Unsafe (unsafePerformEffect)
 import Node.Process (lookupEnv)
 import Parsing (ParseError(..), Parser, ParserT, Position(..), consume, fail, initialPos, parseErrorMessage, parseErrorPosition, position, region, runParser)
 import Parsing.Combinators (advance, between, chainl, chainl1, chainr, chainr1, choice, empty, endBy, endBy1, lookAhead, many, many1, many1Till, many1Till_, manyIndex, manyTill, manyTill_, notFollowedBy, optionMaybe, sepBy, sepBy1, sepEndBy, sepEndBy1, skipMany, skipMany1, try, (<?>), (<??>), (<~?>))
+import Parsing.Combinators.Array as Combinators.Array
 import Parsing.Expr (Assoc(..), Operator(..), buildExprParser)
 import Parsing.Language (haskellDef, haskellStyle, javaStyle)
 import Parsing.String (anyChar, anyCodePoint, anyTill, char, eof, match, regex, rest, satisfy, string, takeN)
@@ -594,6 +595,7 @@ main = do
 
   parseTest "(((a)))" 3 nested
   parseTest "aaa" (Cons "a" (Cons "a" (Cons "a" Nil))) $ many (string "a")
+  parseTest "abc-" [ 'a', 'b', 'c' ] $ Combinators.Array.many letter
   parseTest "(ab)" (Just "b") $ parens do
     _ <- string "a"
     optionMaybe $ string "b"