:mod:`snowmobile.core.utils.parsing`
====================================

.. py:module:: snowmobile.core.utils.parsing

.. autoapi-nested-parse::

   Contains parsing utilities used by:

   -   :class:`snowmobile.Script`
   -   :class:`snowmobile.core.Statement`
   -   :class:`snowmobile.core.Markup`
   -   :class:`snowmobile.core.Section`



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


Functions
~~~~~~~~~

.. autoapisummary::

   snowmobile.core.utils.parsing.rmerge_dicts
   snowmobile.core.utils.parsing.up
   snowmobile.core.utils.parsing.strip
   snowmobile.core.utils.parsing.dict_flatten
   snowmobile.core.utils.parsing.p


.. function:: rmerge_dicts(d1: Dict, d2: Dict) -> Dict

   Recursively merges dictionaries ``d1`` & ``d2``.

   Used for combining contents of **snowmobile.toml** and
   **snowmobile-ext.toml** at the appropriate level within a pair of nested
   dictionaries.

   .. note::
       The order of ``d1`` and ``d2`` matters; if an overlapping key at the
       same level exists in both dictionaries, the value within ``d1``
       will take precedent over the value in ``d2``.

       This function is invoked within the *__init__()* method of
       :class:`~snowmobile.core.Configuration` to merge ``snowmobile.toml``
       and ``snowmobile-ext.toml``, and the prioritization of overlapping
       values described above is the reason that specifications in
       ``snowmobile.toml`` will take precedent over any overlapping
       configurations in ``snowmobile.toml``.

   :param d1: First dictionary to merge.
   :type d1: dict
   :param d2: Second dictionary to merge.
   :type d2: dict

   Returns (dict):
       Dictionary containing recursively merged contents from ``d1`` and
       ``d2``


.. function:: up(nm: str)

   Utility to truncate upper-casing strings as opposed to str.upper().


.. function:: strip(val: str, trailing: bool = True, blanks: bool = True, whitespace: bool = False) -> str

   Utility to strip a variety whitespace from a string.


.. function:: dict_flatten(attrs: dict, delim: Optional[str] = None, indent_char: Optional[str] = None, bullet_char: Optional[str] = None) -> List[Tuple[str, str, str]]

   Recursively flattens dictionary to its atomic elements.

   Flattens a dictionary to its atomic state and performs parsing operations,
   separating each child key with a `delim` relative to its parent key.

   This flattening enables the parsing of a nested dictionary into a valid
   string of markdown containing correspondingly nested bullets.

   :param attrs: Dictionary of attributes; most likely the :attr:`attrs_parsed`
                 from :class:`Statement`.
   :type attrs: dict
   :param delim: Delimiter to use for separating nested keys; defaults to '~';
   :type delim: str
   :param indent_char: Character to use for indents; defaults to a tab ('  ).
   :type indent_char: str
   :param bullet_char: Character to use for bullets/sub-bullets; defaults to '-'.
   :type bullet_char: str

   Returns (List[Tuple[str, str, str]]):
       A list of tuples containing:
           1.  A string of the indentation to use; for 1st-level attributes,
               this will just be the `bullet_char`.
           2.  The fully stratified key, including parents; for 1st-level
               attributes this will mirror the original key that was pr.
           3.  The value of the associated key; this will always mirror the
               value that was pr.


.. function:: p(nm: str) -> Tuple[(str, str)]

   Utility to parse cfg from dot-prefixed object if included.