Implement tryAhead and fix docs (#86)

* implement try ahead and fix docs

* update changelog

Author: chtenb

CHANGELOG.md

@@ -13,6 +13,7 @@ New features:
 Bugfixes:
 - Do not export `chainl'` and `chainr'` helper functions (#84 by @chtenb)
 - Issue #69: Fix regex parser to always wrap pattern inside `^(..)` (#80 by @chtenb)
+- Issue #73: lookAhead consumes input on failure. Introduce `tryAhead` and correct documentation for `lookAhead` (#86 by @chtenb)
 
 Other improvements:
 - Added `purs-tidy` formatter (#76 by @thomashoneyman)

src/Text/Parsing/StringParser.purs

@@ -96,15 +96,6 @@ instance lazyParser :: Lazy (Parser a) where
 fail :: forall a. String -> Parser a
 fail error = Parser \{ position } -> Left { pos: position, error }
 
--- | In case of error, the default behavior is to backtrack if no input was consumed.
--- |
--- | `try p` backtracks even if input was consumed.
-try :: forall a. Parser a -> Parser a
-try (Parser p) = Parser \s ->
-  case p s of
-    Left { error } -> Left { pos: s.position, error }
-    right -> right
-
 instance semigroupParser :: Semigroup a => Semigroup (Parser a) where
   append = lift2 append
 

src/Text/Parsing/StringParser/CodePoints.purs

@@ -35,8 +35,8 @@ import Data.String.CodePoints as SCP
 import Data.String.CodeUnits as SCU
 import Data.String.Regex as Regex
 import Data.String.Regex.Flags (noFlags)
-import Text.Parsing.StringParser (Parser(..), try, fail)
-import Text.Parsing.StringParser.Combinators (many, (<?>))
+import Text.Parsing.StringParser (Parser(..), fail)
+import Text.Parsing.StringParser.Combinators (try, many, (<?>))
 import Text.Parsing.StringParser.CodeUnits as CodeUnitsParser
 
 -- | Match the end of the file.

src/Text/Parsing/StringParser/CodeUnits.purs

@@ -34,8 +34,8 @@ import Data.String.CodeUnits (charAt, singleton)
 import Data.String.CodeUnits as SCU
 import Data.String.Regex as Regex
 import Data.String.Regex.Flags (noFlags)
-import Text.Parsing.StringParser (Parser(..), try, fail)
-import Text.Parsing.StringParser.Combinators (many, (<?>))
+import Text.Parsing.StringParser (Parser(..), fail)
+import Text.Parsing.StringParser.Combinators (try, many, (<?>))
 
 -- | Match the end of the file.
 eof :: Parser Unit

src/Text/Parsing/StringParser/Combinators.purs

@@ -1,6 +1,9 @@
 -- | This module defines combinators for building string parsers.
 module Text.Parsing.StringParser.Combinators
-  ( many
+  ( try
+  , lookAhead
+  , tryAhead
+  , many
   , many1
   , withError
   , (<?>)
@@ -21,7 +24,6 @@ module Text.Parsing.StringParser.Combinators
   , choice
   , manyTill
   , many1Till
-  , lookAhead
   , module Control.Lazy
   ) where
 
@@ -39,13 +41,26 @@ import Data.Maybe (Maybe(..))
 import Data.NonEmpty ((:|))
 import Text.Parsing.StringParser (Parser(..), fail)
 
--- | Read ahead without consuming input.
+-- | `try p` means: run `p` but do not consume input in case of failure.
+try :: forall a. Parser a -> Parser a
+try (Parser p) = Parser \s ->
+  case p s of
+    Left { error } -> Left { pos: s.position, error }
+    right -> right
+
+-- | `lookAhead p` means: run `p` but do not consume input in case of success.
+-- | In most cases you will probably want to use `tryAhead` instead.
 lookAhead :: forall a. Parser a -> Parser a
 lookAhead (Parser p) = Parser \s ->
   case p s of
     Right { result } -> Right { result, suffix: s }
     left -> left
 
+-- | Read ahead without consuming input.
+-- | `tryAhead p` means: succeed if what comes next is of the form `p`; fail otherwise.
+tryAhead :: forall a. Parser a -> Parser a
+tryAhead = try <<< lookAhead
+
 -- | Match zero or more times.
 many :: forall a. Parser a -> Parser (List a)
 many = manyRec

test/BasicSpecs.purs

@@ -12,9 +12,9 @@ import Data.Traversable (traverse)
 import Effect (Effect)
 import Effect.Class.Console (log)
 import Test.Assert (assert')
-import Text.Parsing.StringParser (Parser, runParser, try)
+import Text.Parsing.StringParser (Parser, runParser)
 import Text.Parsing.StringParser.CodePoints (anyChar, anyDigit, anyLetter, char, eof, skipSpaces, string)
-import Text.Parsing.StringParser.Combinators (between, chainl, chainl1, endBy, endBy1, lookAhead, many, many1, manyTill, sepBy, sepBy1, sepEndBy, sepEndBy1)
+import Text.Parsing.StringParser.Combinators (try, tryAhead, between, chainl, chainl1, endBy, endBy1, lookAhead, many, many1, manyTill, sepBy, sepBy1, sepEndBy, sepEndBy1)
 
 type TestInputs = { successes :: Array String, failures :: Array String }
 type TestCase = { name :: String, parser :: AnyParser, inputs :: TestInputs }
@@ -57,7 +57,11 @@ testCases =
     }
   , { name: "lookAhead"
     , parser: mkAnyParser $ lookAhead (char 'a') *> anyLetter
-    , inputs: { successes: [ "a" ], failures: [ "", "b" ] }
+    , inputs: { successes: [ "a" ], failures: [ "", "b", "ab" ] }
+    }
+  , { name: "tryAhead"
+    , parser: mkAnyParser $ tryAhead (char 'a' *> anyDigit) *> (anyChar *> anyChar) <|> (anyDigit *> anyDigit)
+    , inputs: { successes: [ "a6", "66" ], failures: [ "", "b", "-", "6", "aa", "a6aa", "aa66" ] }
     }
   , { name: "many"
     , parser: mkAnyParser $ many (char 'a')

test/CodePoints.purs

@@ -15,9 +15,9 @@ import Data.Unfoldable (replicate)
 import Effect (Effect)
 import Effect.Class.Console (log)
 import Test.Assert (assert', assert)
-import Text.Parsing.StringParser (ParseError, Parser(..), PosString, runParser, try)
+import Text.Parsing.StringParser (ParseError, Parser(..), PosString, runParser)
 import Text.Parsing.StringParser.CodePoints (anyDigit, char, eof, string, anyChar, regex)
-import Text.Parsing.StringParser.Combinators (many1, endBy1, sepBy1, optionMaybe, many, manyTill, many1Till, chainl, fix, between)
+import Text.Parsing.StringParser.Combinators (try, many1, endBy1, sepBy1, optionMaybe, many, manyTill, many1Till, chainl, fix, between)
 import Text.Parsing.StringParser.Expr (Assoc(..), Operator(..), buildExprParser)
 
 parens :: forall a. Parser a -> Parser a

test/CodeUnits.purs

@@ -15,9 +15,9 @@ import Data.Unfoldable (replicate)
 import Effect (Effect)
 import Effect.Class.Console (log)
 import Test.Assert (assert', assert)
-import Text.Parsing.StringParser (Parser, runParser, try)
+import Text.Parsing.StringParser (Parser, runParser)
 import Text.Parsing.StringParser.CodeUnits (anyDigit, eof, string, anyChar, regex)
-import Text.Parsing.StringParser.Combinators (many1, endBy1, sepBy1, optionMaybe, many, manyTill, many1Till, chainl, fix, between)
+import Text.Parsing.StringParser.Combinators (try, many1, endBy1, sepBy1, optionMaybe, many, manyTill, many1Till, chainl, fix, between)
 import Text.Parsing.StringParser.Expr (Assoc(..), Operator(..), buildExprParser)
 
 parens :: forall a. Parser a -> Parser a