polymerist.genutils.textual.delimiters
======================================

.. py:module:: polymerist.genutils.textual.delimiters

.. autoapi-nested-parse::

   Validation and parsing of text enclosed by opening and closing delimiters (i.e. parentheses-like behavior)



Attributes
----------

.. autoapisummary::

   polymerist.genutils.textual.delimiters.COMMON_DELIMITERS
   polymerist.genutils.textual.delimiters.validate_braces


Classes
-------

.. autoapisummary::

   polymerist.genutils.textual.delimiters.DelimiterBalanceState


Functions
---------

.. autoapisummary::

   polymerist.genutils.textual.delimiters.check_balanced_delimiters
   polymerist.genutils.textual.delimiters.parse_within_delimiters
   polymerist.genutils.textual.delimiters.delimit_substrs_from_regex
   polymerist.genutils.textual.delimiters.delimit_substrs_from_choices
   polymerist.genutils.textual.delimiters.validate_common_delimiters


Module Contents
---------------

.. py:class:: DelimiterBalanceState

   Bases: :py:obj:`enum.StrEnum`


   For indication the error state in a delimiter character pair closure check


   .. py:attribute:: BALANCED
      :value: 'balanced'



   .. py:attribute:: PREMATURE_CLOSURE
      :value: 'premature closure'



   .. py:attribute:: UNCLOSED_OPENING
      :value: 'unclosed opening'



.. py:function:: check_balanced_delimiters(string: str, start_char: str, end_char: str) -> tuple[bool, DelimiterBalanceState, int]

   Tests if parenthesis-like start and end delimiters within a string are balanced
   (i.e. there are just as many closures as opening, and no closure occurs before and opening)

   Return whether the string is balanced, and the index where an imbalance has occurred (-1 if no imbalance or at end)


.. py:function:: parse_within_delimiters(string: str, start_char: str, end_char: str) -> Generator[str, None, None]

   Generates substring contained by starting and ending delimiting characters (and depth of substring) via pushdown automaton mechanism


.. py:function:: delimit_substrs_from_regex(string: str, regex: Union[str, re.Pattern], start_char: str, end_char: str) -> str

   Place delimiters around any substrings of "string" which match the provided regular expression


.. py:function:: delimit_substrs_from_choices(string: str, choices: Iterable[str], start_char: str, end_char: str) -> str

   Place delimiters around any substrings of "string" which occur within "choices"


.. py:data:: COMMON_DELIMITERS

.. py:function:: validate_common_delimiters(string: str, pointer_char: str = '^') -> None

   For checking whether all braces-like delimiters (i.e. parenthesis, brackets, etc.) are fully opened and not closed early
   If an invalid delimiters are found, a ValueError is raised with a helpful error message that points to the location of the fault (and the reason)


.. py:data:: validate_braces