add .span() method

Author: tsani

src/parsy/__init__.py

@@ -32,6 +32,21 @@ def __getitem__(self, i):
             return self.data[i]
 
 
+@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: Stream, index):
     if index > len(stream):
         raise ValueError("invalid index")
@@ -368,6 +383,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
@@ -379,6 +397,24 @@ 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():
+            source, *start = yield line_info
+            body = yield self
+            _, *end = yield line_info
+            return (SourceSpan(source, tuple(start), tuple(end)), body)
+
+        return marked
+
     def tag(self, name: str) -> Parser:
         """
         Returns a parser that wraps the produced value of the initial parser in a