From be703465b4ef6ec10ca10bdb95b0cb14dd98b325 Mon Sep 17 00:00:00 2001 From: Jacob Errington Date: Sun, 19 Jan 2025 08:18:44 -0500 Subject: [PATCH] document .span() and SourceSpan --- docs/ref/methods_and_combinators.rst | 45 ++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/docs/ref/methods_and_combinators.rst b/docs/ref/methods_and_combinators.rst index 5ef0a2e..7d2375b 100644 --- a/docs/ref/methods_and_combinators.rst +++ b/docs/ref/methods_and_combinators.rst @@ -23,7 +23,7 @@ can be used and manipulated as below. The following methods are for actually **using** the parsers that you have created: - .. method:: parse(string_or_list) + .. method:: parse(string_or_list[, source=None]) Attempts to parse the given string (or list). If the parse is successful and consumes the entire string, the result is returned - otherwise, a @@ -36,7 +36,11 @@ can be used and manipulated as below. library will work with tokens just as well. See :doc:`/howto/lexing` for more information. - .. method:: parse_partial(string_or_list) + When a non-None ``source`` is given, this name is reported automatically + in parse errors. Typically, this is the file path or URL where the data + to parse originates from. + + .. method:: parse_partial(string_or_list[, source=None]) Similar to ``parse``, except that it does not require the entire string (or list) to be consumed. Returns a tuple of @@ -401,6 +405,20 @@ can be used and manipulated as below. ` and want subsequent parsing of the token stream to be able to report original positions in error messages etc. + .. method:: span() + + Returns a parser that augments the initial parser's result with a :class:`SourceSpan` + containing information about where that parser started and stopped within the + source data. The new value is a tuple: + + .. code:: python + + (source_span, original_value) + + This enables reporting of custom errors involving source locations, such as when + using parsy as a :doc:`lexer` or when building a syntax tree that will be + further analyzed. + .. _operators: Parser operators @@ -594,3 +612,26 @@ Parsy does not try to include every possible combinator - there is no reason why you cannot create your own for your needs using the built-in combinators and primitives. If you find something that is very generic and would be very useful to have as a built-in, please :doc:`submit ` as a PR! + +Auxiliary data structures +========================= + +.. class:: SourceSpan + + Identifies a span of material from the data being parsed by its start row and column and its end + row and column. If the data stream was equipped with a source, that value is also available in + this object. + + .. attribute:: start + + The starting position of this span as a tuple (row, col) + + .. attribute:: end + + The stopping position of this span as a tuple (row, col) + + .. attribute:: source + + The name of the source the data was parsed from. This is the same value + that was passed to :meth:`Parser.parse` or :meth:`Parser.parse_partial`, + or `None` if no value was given.