API Primitives
==============

Several parts of Avulto are useful with all of its APIs.

.. class:: Path

   :class:`Path` wraps type paths and provides several useful methods and
   properties for manipulating and comparing paths::

    >>> from avulto import Path as p

    >>> p('/obj/machinery').parent_of('/obj/machinery/oven')
    True

    >>> p('/turf').child_of('/turf', strict=True)
    False

    >>> p('/obj/machinery') / 'microwave'
    /obj/machinery/microwave

    >>> p('/obj/machinery/microwave').parent
    /obj/machinery

    >>> p('/obj/machinery/microwave').stem
    "microwave"

   .. property:: abs
      :type: str

      Returns the *absolute* representation of the path, rooted at ``/datum``.

      .. code-block:: python

         >>> p('/obj/foo').abs
         '/datum/atom/movable/obj/foo'

         >>> p('/foo').abs
         '/datum/foo'

   .. property:: rel
      :type: str

      Returns the *relative* or *declared* representation of the path.

      .. code-block:: python

         >>> p('/obj/foo').rel
         '/obj/foo'

         >>> p('/datum/foo').rel
         '/datum/foo'

         >>> p('/foo').rel
         '/foo'

   .. property:: parent
      :type: Path

      Returns the immediate parent path of ourselves.

   .. property:: stem
      :type: str

      Returns the last part of our path.

   .. property:: is_root
      :type: bool

      Returns whether the path is ``/``.

   .. method:: parent_of(path: Path | str, strict=False)

      Returns whether we are a parent of *path*. If *strict* is :const:`True`, a
      path will not count as a parent of itself.

   .. method:: child_of(path: Path | str, strict=False)

      Returns whether we are a child of *path*. If *strict* is :const:`True`, a
      path will not count as a child of itself.

.. class:: SourceLoc

   :class:`SourceLoc` contains source file information about types, procs, and
   vars. This is useful for tasks like linters which want to show line and
   column-level information about a finding.

   .. property:: file_path
      :type: pathlib.Path

      The file path of the source location.

   .. property:: line
      :type: int

      The line number.

   .. property:: column
      :type: int

      The column number.

.. class:: Coord3

   A three-dimensional integer coordinate. These are currently only returned by
   certain :class:`DMM` properties, and are not constructable.

   .. property:: x
      :type: int

   .. property:: y
      :type: int

   .. property:: z
      :type: int

.. class:: Dmlist

   A primitive, read-only representation of a DM list. This is used when
   returning constant values of lists from the AST walker, and prefab values
   from the DMM reader. They are not constructable.

   Dmlists only support iterating over keys, and indexing with keys.

   .. method:: keys()

      Returns an interator over the list's keys.

.. class:: Dir

   Representation of BYOND directions.

   .. property:: NORTH
   .. property:: SOUTH
   .. property:: EAST
   .. property:: WEST
   .. property:: NORTHEAST
   .. property:: NORTHWEST
   .. property:: SOUTHEAST
   .. property:: SOUTHWEST