.. _jgdv.structs.strang._interface:
   
    
==============================
jgdv.structs.strang._interface
==============================
  

   
.. py:module:: jgdv.structs.strang._interface

.. autoapi-nested-parse::

   The Interface for Strang.

   Strang Enums:
   - StrangMarkAbstract_e

   Describes the internal data structs:
   - Sec_d : A Single section spec
   - Sections_d : Collects the sec_d's. ClassVar
   - Strang_d : Instance data of a strang beyond the normal str's

       
 

   
 

 

 
   
 
   
Type Aliases
------------

.. autoapisummary::
   
   jgdv.structs.strang._interface.FindSlice
   jgdv.structs.strang._interface.FullSlice
   jgdv.structs.strang._interface.ItemIndex
   jgdv.structs.strang._interface.MSlice
   jgdv.structs.strang._interface.MarkIndex
   jgdv.structs.strang._interface.PushVal
   jgdv.structs.strang._interface.SectionIndex
   jgdv.structs.strang._interface.WordIndex

        

 
 
   
Enums
-----

.. autoapisummary::

   jgdv.structs.strang._interface.StrangMarkAbstract_e

           

 
 

 
 

Protocols
---------

.. autoapisummary::

   jgdv.structs.strang._interface.Importable_p
   jgdv.structs.strang._interface.StrangFormatter_p
   jgdv.structs.strang._interface.StrangMod_p
   jgdv.structs.strang._interface.StrangUUIDs_p
   jgdv.structs.strang._interface.Strang_p

           
   
             
  
           
 
  
 
 
  

   
Classes
-------
  


.. autoapisummary::

    jgdv.structs.strang._interface.CodeRefHeadMarks_e
    jgdv.structs.strang._interface.DefaultBodyMarks_e
    jgdv.structs.strang._interface.DefaultHeadMarks_e
    jgdv.structs.strang._interface.Sec_d
    jgdv.structs.strang._interface.Sections_d
    jgdv.structs.strang._interface.Strang_d
           
 
      
 
Module Contents
===============

 
.. py:data:: FindSlice
   :type:  TypeAlias
   :value: str | StrangMarkAbstract_e | WordIndex | MarkIndex


 
.. py:data:: FullSlice
   :type:  TypeAlias
   :value: slice[None, None, None]


 
.. py:data:: ItemIndex
   :type:  TypeAlias
   :value: SectionIndex | FullSlice | MSlice | tuple[ItemIndex, ...]


 
.. py:data:: MSlice
   :type:  TypeAlias
   :value: slice[Maybe[int], Maybe[int], Maybe[int]]


 
.. py:data:: MarkIndex
   :type:  TypeAlias
   :value: tuple[SectionIndex, StrangMarkAbstract_e]


 
.. py:data:: PushVal
   :type:  TypeAlias
   :value: Maybe[str | StrangMarkAbstract_e | UUID]


 
.. py:data:: SectionIndex
   :type:  TypeAlias
   :value: str | int


 
.. py:data:: WordIndex
   :type:  TypeAlias
   :value: tuple[SectionIndex, int]


 
 

.. _jgdv.structs.strang._interface.StrangMarkAbstract_e:
   
.. py:class:: StrangMarkAbstract_e
   
   Bases: :py:obj:`enum.StrEnum` 
     
   Enum where members are also (and must be) strings

   
      
   .. py:method:: default() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: idempotent() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: implicit() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: skip() -> <Unknown>
      :classmethod:
      


 
 
 

.. _jgdv.structs.strang._interface.Importable_p:
   
.. py:class:: Importable_p
   
   Bases: :py:obj:`Protocol` 
     
   Marks a class as able to import code. Userd for CodeRef's.

   
      
   .. py:method:: _does_imports() -> <Unknown>
      


 
 
 

.. _jgdv.structs.strang._interface.StrangFormatter_p:
   
.. py:class:: StrangFormatter_p
   
   Bases: :py:obj:`Protocol` 
     
   A string.Formatter with some Strang-specific methods

   
      
   .. py:method:: convert_field(value, conversion) -> <Unknown>
      


      
   .. py:method:: expanded_str(data, *, stop = None) -> <Unknown>
      


      
   .. py:method:: format(format_string, /, *args, **kwargs) -> <Unknown>
      


      
   .. py:method:: get_value(key, args, kwargs) -> <Unknown>
      


 
 
 

.. _jgdv.structs.strang._interface.StrangMod_p:
   
.. py:class:: StrangMod_p
   
   Bases: :py:obj:`Protocol` 
     
   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto[T](Protocol):
           def meth(self) -> T:
               ...

   
      
   .. py:method:: pop(*, top = False) -> <Unknown>
      


      
   .. py:method:: push(*vals) -> <Unknown>
      


 
 
 

.. _jgdv.structs.strang._interface.StrangUUIDs_p:
   
.. py:class:: StrangUUIDs_p
   
   Bases: :py:obj:`Protocol` 
     
   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto[T](Protocol):
           def meth(self) -> T:
               ...

   
      
   .. py:method:: de_uniq() -> <Unknown>
      


      
   .. py:method:: to_uniq(*args) -> <Unknown>
      


 
 
 

.. _jgdv.structs.strang._interface.Strang_p:
   
.. py:class:: Strang_p
   
   Bases: :py:obj:`StrangUUIDs_p`, :py:obj:`StrangMod_p`, :py:obj:`jgdv._abstract.protocols.str.String_p`, :py:obj:`Protocol` 
     
   The Main protocol describing a Strang.

   
      
   .. py:method:: args() -> <Unknown>
      


      
   .. py:method:: get(*args) -> <Unknown>
      


      
   .. py:method:: index(*sub, start = None, end = None) -> <Unknown>
      

      index

       Extended str.index, to handle marks and word slices

      :param sub:   The indices to slice
      :param start: The start of the slice to cover.
      :param end:   The end of the slice to cover.

      :returns: The index of the char



      
   .. py:method:: rindex(*sub, start = None, end = None) -> <Unknown>
      


      
   .. py:method:: section(arg) -> <Unknown>
      :classmethod:
      


      
   .. py:method:: sections() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: uuid() -> <Unknown>
      


      
   .. py:method:: words(idx, *, case = False) -> <Unknown>
      


   .. py:attribute:: _formatter
      :type:  ClassVar[string.Formatter]

   .. py:attribute:: _processor
      :type:  ClassVar[jgdv._abstract.protocols.pre_processable.PreProcessor_p]

   .. py:attribute:: _sections
      :type:  ClassVar[Sections_d]

   .. py:property:: base
      :type: Self


   .. py:attribute:: data
      :type:  Strang_d

   .. py:property:: shape
      :type: tuple[int, Ellipsis]


 
 
 

.. _jgdv.structs.strang._interface.CodeRefHeadMarks_e:
   
.. py:class:: CodeRefHeadMarks_e
   
   Bases: :py:obj:`StrangMarkAbstract_e` 
     
   Available Group values of CodeRef strang's

   
      
   .. py:method:: default() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: idempotent() -> <Unknown>
      :classmethod:
      


   .. py:attribute:: cls
      :value: 'cls'


   .. py:attribute:: fn
      :value: 'fn'


   .. py:attribute:: module
      :value: 'module'


   .. py:attribute:: val
      :value: 'value'


   .. py:attribute:: value
      :value: 'value'


      The value of the Enum member.

 
 
 

.. _jgdv.structs.strang._interface.DefaultBodyMarks_e:
   
.. py:class:: DefaultBodyMarks_e
   
   Bases: :py:obj:`StrangMarkAbstract_e` 
     
   Markers Used in a base Strang's body

   
      
   .. py:method:: default() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: idempotent() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: implicit() -> <Unknown>
      :classmethod:
      


      
   .. py:method:: skip() -> <Unknown>
      :classmethod:
      


   .. py:attribute:: empty
      :value: ''


   .. py:attribute:: extend
      :value: '+'


   .. py:attribute:: gen
      :value: '$gen$'


   .. py:attribute:: head
      :value: '$head$'


   .. py:attribute:: hide
      :value: '_'


 
 
 

.. _jgdv.structs.strang._interface.DefaultHeadMarks_e:
   
.. py:class:: DefaultHeadMarks_e
   
   Bases: :py:obj:`StrangMarkAbstract_e` 
     
   Markers used in a Strang's head

   
   .. py:attribute:: basic
      :value: '$basic$'


 
 
 

.. _jgdv.structs.strang._interface.Sec_d:
   
.. py:class:: Sec_d(name, case, end, types, marks, required = True, *, idx = -1)
   
    
   Data of a named Strang section

   for an example section 'a.2.c.+::d'
   - case      : the word boundary.                              = '.'
   - end       : the rhs end str.                                = '::'
   - types     : allowed types.                                  = str|int
   - marks     : StrangMarkAbstract_e of words with a meta meaning.  = '+'
   - required  : a strang errors if a required section isnt found

   - idx       : the index of the section

   TODO Maybe 'type_re' and 'mark_re'


   
   .. py:attribute:: case
      :type:  Final[jgdv.Maybe[str]]

   .. py:attribute:: end
      :type:  Final[jgdv.Maybe[str]]

   .. py:attribute:: idx
      :type:  int

   .. py:attribute:: marks
      :type:  Final[jgdv.Maybe[type[StrangMarkAbstract_e]]]

   .. py:attribute:: name
      :type:  Final[str]

   .. py:attribute:: required
      :type:  Final[bool]

   .. py:attribute:: types
      :type:  Final[type | types.UnionType]

 
 
 

.. _jgdv.structs.strang._interface.Sections_d:
   
.. py:class:: Sections_d(*sections)
   
    
   An object to hold information about word separation and sections,
   a strang type is structured into these

   Each Section is a Sec_d
   TODO add format conversion specs

   
   .. py:attribute:: named
      :type:  Final[dict[str, int]]

   .. py:attribute:: order
      :type:  Final[tuple[Sec_d, Ellipsis]]

   .. py:attribute:: types
      :type:  type | types.UnionType

 
 
 

.. _jgdv.structs.strang._interface.Strang_d:
   
.. py:class:: Strang_d(uuid = None)
   
    
   Extra Data of a Strang.
   Sections are accessed by their index, so use cls._sections.named[name] to get the index

   - sections  : tuple[slice, ...]      - Section boundaries
   - sec_words : tuple[tuple[int, ...]] - lookup of (sec, word) -> WordIndex
   - words     : tuple[slice, ...]      - Word Slices
   - meta      : tuple[Maybe, ...]      - Flat word level meta data


   
   .. py:attribute:: args
      :type:  jgdv.Maybe[tuple]

   .. py:attribute:: args_start
      :type:  jgdv.Maybe[int]

   .. py:attribute:: flat_idx
      :type:  tuple[tuple[int, int], Ellipsis]

   .. py:attribute:: meta
      :type:  tuple[jgdv.Maybe, Ellipsis]

   .. py:attribute:: sec_words
      :type:  tuple[tuple[int, Ellipsis], Ellipsis]

   .. py:attribute:: sections
      :type:  tuple[slice, Ellipsis]

   .. py:attribute:: uuid
      :type:  jgdv.Maybe[uuid.UUID]

   .. py:attribute:: words
      :type:  tuple[slice, Ellipsis]