pipeworks_mud_mapper.services.exit_utils
========================================

.. py:module:: pipeworks_mud_mapper.services.exit_utils

.. autoapi-nested-parse::

   Exit parsing helpers for local vs cross-zone exits.

   This module centralizes the tiny bits of exit parsing logic used by the
   UI, validation, and map rendering layers. It keeps the rules for detecting
   cross-zone exits ("zone_id:room_id") consistent across the codebase.



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.services.exit_utils.split_exits_by_scope
   pipeworks_mud_mapper.services.exit_utils.parse_zone_exit
   pipeworks_mud_mapper.services.exit_utils.format_zone_exit


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

.. py:function:: split_exits_by_scope(exits)

   Split exits into local (same-zone) and zone (cross-zone) mappings.

   :param exits: Exit mapping from a room. Values that contain ":" are treated as
                 cross-zone exits ("zone_id:room_id"). All others are local exits.
   :type exits: :py:class:`dict[Direction`, :py:class:`str] | None`

   :returns: (local_exits, zone_exits) where each dict is keyed by direction.
   :rtype: :py:class:`tuple[dict[Direction`, :py:class:`str]`, :py:class:`dict[Direction`, :py:class:`str]]`

   .. admonition:: Notes

      This is deliberately small and conservative: we only treat values as
      cross-zone exits if they include a colon. Any other value is treated
      as local, even if it might be malformed.


.. py:function:: parse_zone_exit(target)

   Parse a cross-zone exit target into (zone_id, room_id).

   :param target: Exit target string, expected in "zone_id:room_id" format.
   :type target: :py:class:`str | None`

   :returns: (zone_id, room_id). Returns (None, None) if the input is missing
             or does not contain a valid colon-separated pair.
   :rtype: :py:class:`tuple[str | None`, :py:class:`str | None]`


.. py:function:: format_zone_exit(zone_id, room_id)

   Format a zone + room selection into the stored exit value.

   :param zone_id: Selected zone ID.
   :type zone_id: :py:class:`str | None`
   :param room_id: Selected room ID.
   :type room_id: :py:class:`str | None`

   :returns: "zone_id:room_id" if both parts are present; otherwise None.
   :rtype: :py:class:`str | None`