diff --git a/docs/history.rst b/docs/history.rst index 12e764a..c0c1c35 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -7,6 +7,7 @@ History and release notes Unreleased ---------- * Fixed various type hints +* Fixed :meth:`Parser.desc` resetting the failure position of combined parsers. 2.2 - 2025-09-12 ---------------- diff --git a/docs/ref/methods_and_combinators.rst b/docs/ref/methods_and_combinators.rst index 2cce368..3ce9549 100644 --- a/docs/ref/methods_and_combinators.rst +++ b/docs/ref/methods_and_combinators.rst @@ -56,6 +56,16 @@ can be used and manipulated as below. >>> year.parse('123') ParseError: expected 4 digit year at 0:0 + For a combined parser, the description replaces the expected text while + retaining the furthest failure position of its component parsers. + + >>> pair = (string('a') >> string('b')).desc('a pair') + >>> pair.parse('ax') + ParseError: expected 'a pair' at 0:1 + + Successful results, including failure information retained from + backtracking, are unchanged. + .. method:: then(other_parser) Returns a parser which, if the initial parser succeeds, will continue parsing diff --git a/src/parsy/__init__.py b/src/parsy/__init__.py index c122283..1234c69 100644 --- a/src/parsy/__init__.py +++ b/src/parsy/__init__.py @@ -323,7 +323,7 @@ def sep_by(self, sep: Parser, *, min: int = 0, max: float = float("inf")) -> Par def desc(self, description: str) -> Parser: """ Returns a new parser with a description added, which is used in the error message - if parsing fails. + if parsing fails. The furthest failure position is preserved. """ @Parser @@ -332,7 +332,7 @@ def desc_parser(stream: str | bytes | list, index: int) -> Result: if result.status: return result else: - return Result.failure(index, description) + return Result.failure(result.furthest, description) return desc_parser diff --git a/tests/test_parsy.py b/tests/test_parsy.py index f699508..49f64da 100644 --- a/tests/test_parsy.py +++ b/tests/test_parsy.py @@ -233,6 +233,80 @@ def thing(): self.assertEqual(ex.stream, "x") self.assertEqual(ex.index, 0) + def test_desc_preserves_failure_location(self): + parser = (string("a") >> string("b")).desc("a pair") + with self.assertRaises(ParseError) as err: + parser.parse("ax") + + self.assertEqual(err.exception.index, 1) + self.assertEqual(err.exception.expected, frozenset(["a pair"])) + self.assertEqual(str(err.exception), "expected 'a pair' at 0:1") + + def test_desc_preserves_furthest_alternative(self): + parser = ((string("ab") >> string("c")) | string("z")).desc("a choice") + with self.assertRaises(ParseError) as err: + parser.parse("abx") + + self.assertEqual(err.exception.index, 2) + self.assertEqual(err.exception.expected, frozenset(["a choice"])) + + def test_desc_combines_alternatives_at_same_location(self): + parser = (string("a") >> string("b")).desc("a pair") | (string("a") >> string("c")) + with self.assertRaises(ParseError) as err: + parser.parse("ax") + + self.assertEqual(err.exception.index, 1) + self.assertEqual(err.exception.expected, frozenset(["a pair", "c"])) + + def test_desc_in_generate_preserves_line_and_column(self): + @generate + def document(): + yield string("heading\n") + yield (string("a") >> string("b")).desc("a pair") + + with self.assertRaises(ParseError) as err: + document.parse("heading\nax") + + self.assertEqual(err.exception.index, 9) + self.assertEqual(str(err.exception), "expected 'a pair' at 1:1") + + def test_generate_desc_preserves_failure_location(self): + @generate("a pair") + def pair(): + yield string("a") + yield string("b") + + with self.assertRaises(ParseError) as err: + pair.parse("ax") + + self.assertEqual(err.exception.index, 1) + self.assertEqual(err.exception.expected, frozenset(["a pair"])) + + def test_desc_preserves_bytes_and_token_locations(self): + cases = [ + (string(b"a") >> string(b"b"), b"ax"), + (match_item("a") >> match_item("b"), ["a", "x"]), + ] + for parser, stream in cases: + with self.subTest(stream=stream): + with self.assertRaises(ParseError) as err: + parser.desc("a pair").parse(stream) + self.assertEqual(err.exception.index, 1) + self.assertEqual(err.exception.expected, frozenset(["a pair"])) + + def test_desc_preserves_success_and_backtracking(self): + parser = (string("a") >> string("b")) | string("a") + described = parser.desc("a pair or a") + for stream in ["ab", "ax", "a"]: + with self.subTest(stream=stream): + self.assertEqual(described(stream, 0), parser(stream, 0)) + self.assertEqual(described.parse_partial(stream), parser.parse_partial(stream)) + + with self.assertRaises(ParseError) as err: + described.parse("ax") + self.assertEqual(err.exception.index, 1) + self.assertEqual(err.exception.expected, frozenset(["b", "EOF"])) + def test_generate_default_desc(self): # We shouldn't give a default desc, the messages from the internal # parsers should bubble up.