:orphan:

:mod:`snowmobile.core.name`
===========================

.. py:module:: snowmobile.core.name

.. autoapi-nested-parse::

   Decomposes a statement into parts and generates a name given its content
   and position within the script.



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

Classes
~~~~~~~

.. autoapisummary::

   snowmobile.core.name.Name



.. class:: Name(configuration: snowmobile.core.Configuration, nm_pr: Optional[str] = None, sql: Optional[str] = None, index: Optional[int] = None)


   Bases: :class:`snowmobile.core.Generic`

   Handles the decomposition/parsing of statement name.

   Should never be instantiated directly by the user-facing API but its
   attributes are likely to be accessed often as part of :class:`Statement`
   and derived classes.

   .. attribute:: cfg

      :class:`snowmobile.Configuration` object; represents fully parsed
      **snowmobile.toml** file.

      :type: snowmobile.Configuration

   .. attribute:: patt

      :class:`snowmobile.Schema.Pattern` object; represents
      ``script.patterns`` section of **snowmobile.toml**.

      :type: snowmobile.Schema.Pattern

   .. attribute:: _nm_pr

      Provided wrap name for a given :class:`Statement`; can be empty.

      :type: str

   .. attribute:: index

      Statement index position within :class:`Script`; can be empty.

      :type: int

   .. attribute:: is_included

      Indicator of whether or not the combination of all scopes for this
      statement wrap is included within a given context.

      :type: bool

   .. attribute:: incl_idx_in_desc

      Indicator of whether or not to include the statement index in the
      `description` component of the wrap; defaults to `True` so that all
      generated statement tags are guaranteed to be unique for a given
      script.
          *   Mainly included for testing purposes where setting to
              `False` enables comparing generated to provided statement
              tags without having to change the index position of the
              hard-coded/pr statement wrap when adding/removing tests.

      :type: bool

   .. attribute:: first_line_remainder

      The remainder of the first line once excluding the
      :attr:`first_keyword` and stripping repeating whitespace.

      :type: str

   .. attribute:: scopes

      Combination of all scopes for a given wrap; this is essentially the
      all possible combinations of including/excluding any of the `kw`,
      `nm`, `obj`, `desc`, and `anchor` for a given instance of :class:`Name`.

      :type: set[Scope]

   .. method:: scope(self, **kwargs) -> bool

      Evaluates all component's of a wrap's scope against a set of filter args.

          **kwargs:
              Keyword arguments passed to :class:`Script.filter()` (e.g.
              `incl_kw`, `excl_kw`, ..)

      Returns (bool):
          Value indicating whether or not the statement should be included
          based on the outcome of the evaluation of all of its components.


   .. method:: nm(self, ge: bool = False, pr: bool = False, og: bool = True) -> str

      The final statement's **name** that is used by the API.

      This will be the full statement name if a tag exists and a
      parsed/generated name otherwise.


   .. method:: kw(self, ge: bool = False, pr: bool = False)

      The final statement's **keyword** that is used by the API.

      This will be the provided keyword if a statement wrap exists and a
      parsed/ge keyword otherwise.


   .. method:: obj(self, ge: bool = False, pr: bool = False)

      The final statement's **object** that is used by the API.

      This will be the object within a wrap if a statement wrap exists and
      follows the correct structure and a parsed/ge object otherwise.


   .. method:: desc(self, ge: bool = False, pr: bool = False)

      The final statement's **description** that is used by the API.

      This will be the description within a wrap if a statement wrap exists
      and follows the correct structure and a parsed/ge description
      otherwise.


   .. method:: anchor(self, ge: bool = False, pr: bool = False)

      The final statement's **anchor** that is used by the API.

      This will be the anchor within a wrap if a statement wrap exists
      and follows the correct structure and a parsed/ge wrap name
      otherwise.


   .. method:: set(self, key, value) -> snowmobile.core.name.Name

      Custom attribute setting.