add .span() method and test for it

Author: tsani

src/parsy/__init__.py

@@ -50,6 +50,22 @@ def make_stream(data: str | bytes, source: Any):
         "location metadata.",
     )
 
+
+@dataclass
+class SourceSpan:
+    """Identifies a span of material from the data to parse.
+
+    Attributes:
+        source (str | None): the source of the data, e.g. a file path.
+        start ([int, int]): the start row and column of the span.
+        end ([int, int]): the end row and column of the span.
+    """
+
+    source: str | None
+    start: [int, int]
+    end: [int, int]
+
+
 def line_info_at(stream, index):
     if index > len(stream):
         raise ValueError("invalid index")
@@ -391,6 +407,9 @@ def mark(self) -> Parser:
         ((start_row, start_column),
          original_value,
          (end_row, end_column))
+
+        ``.span()'' is a more powerful version of this combinator, returning a
+        SourceSpan.
         """
 
         @generate
@@ -407,6 +426,28 @@ def marked():
 
         return marked
 
+    def span(self) -> Parser:
+        """
+        Returns a parser that augments the initial parser's result with a
+        SourceSpan capturing where that parser started and stopped.
+        The new value is a tuple:
+
+        (source_span, original_value)
+        """
+
+        @generate
+        def marked():
+            start = yield line_info
+            body = yield self
+            end = yield line_info
+            try:
+                source = start[2]
+            except IndexError:
+                source = None
+            return (SourceSpan(source, start[:2], end[:2]), body)
+
+        return marked
+
     def tag(self, name: str) -> Parser:
         """
         Returns a parser that wraps the produced value of the initial parser in a

tests/test_parsy.py

@@ -7,6 +7,7 @@
 
 from parsy import (
     ParseError,
+    SourceSpan,
     alt,
     any_char,
     char_from,
@@ -208,6 +209,35 @@ def test_mark(self):
         self.assertEqual(letters, ["q", "w", "e", "r"])
         self.assertEqual(end, (1, 4))
 
+    def test_span(self):
+        parser = (letter.many().span() << string("\n")).many()
+        source = "sample"
+
+        lines = parser.parse("asdf\nqwer\n", source=source)
+
+        self.assertEqual(len(lines), 2)
+
+        (span, letters) = lines[0]
+        self.assertEqual(span, SourceSpan(source, (0, 0), (0, 4)))
+        self.assertEqual(letters, ["a", "s", "d", "f"])
+
+        (span, letters) = lines[1]
+        self.assertEqual(span, SourceSpan(source, (1, 0), (1, 4)))
+
+    def test_span_no_source(self):
+        parser = (letter.many().span() << string("\n")).many()
+
+        lines = parser.parse("asdf\nqwer\n")
+
+        self.assertEqual(len(lines), 2)
+
+        (span, letters) = lines[0]
+        self.assertEqual(span, SourceSpan(None, (0, 0), (0, 4)))
+        self.assertEqual(letters, ["a", "s", "d", "f"])
+
+        (span, letters) = lines[1]
+        self.assertEqual(span, SourceSpan(None, (1, 0), (1, 4)))
+
     def test_tag(self):
         parser = letter.many().concat().tag("word")
         self.assertEqual(
@@ -692,6 +722,7 @@ def test_line_info_at(self):
         self.assertRaises(ValueError, lambda: line_info_at(text, 8))
 
 
+
 class TestForwardDeclaration(unittest.TestCase):
     def test_forward_declaration_1(self):
         # This is the example from the docs