:py:mod:`raesl.utils`
=====================

.. py:module:: raesl.utils

.. autoapi-nested-parse::

   Generic utility functions.



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


Functions
~~~~~~~~~

.. autoapisummary::

   raesl.utils.get_esl_paths
   raesl.utils.check_output_path
   raesl.utils.get_location
   raesl.utils.cleanup_path
   raesl.utils.uri_to_path
   raesl.utils.path_to_uri
   raesl.utils.split_first_dot
   raesl.utils.get_first_namepart
   raesl.utils.get_scoped_nodes
   raesl.utils.yield_subtree



.. py:function:: get_esl_paths(*paths: Union[str, pathlib.Path]) -> List[pathlib.Path]

   Get a sorted list of ESL file paths from multiple file or directory paths.


.. py:function:: check_output_path(fpath: Union[str, pathlib.Path], force: bool) -> pathlib.Path

   Check output filepath versus force overwrite status.


.. py:function:: get_location(uri: str = 'Unknown', start_line: int = 0, start_character: int = 0, end_line: Optional[int] = None, end_character: Optional[int] = None) -> raesl.types.Location

   Generation utility to quickly drum up a location.

   :param uri: Location uri.
   :param start_line: Location's range start line.
   :param start_character: Location's range start offset.
   :param end_line: Optional Location's range end line (otherwise identical to start.)
   :param end_character: Optional Location's range end offset (otherwise identical to
                         start.)

   :returns: Newly created location instance.


.. py:function:: cleanup_path(path: Union[str, pathlib.Path]) -> pathlib.Path

   Cleanup pathname for some typical mistakes.


.. py:function:: uri_to_path(uri: str) -> pathlib.Path

   Convert a file URI to a regular path.


.. py:function:: path_to_uri(path: Union[str, pathlib.Path]) -> str

   Convert a path to a file URI.


.. py:function:: split_first_dot(name: str) -> Tuple[str, str, int]

   Split the provided name on the first dot if it exists, return both parts, and
   the length of the dot.


.. py:function:: get_first_namepart(name: str) -> str

   Return the name upto and excluding the first dot.


.. py:function:: get_scoped_nodes(graph: ragraph.graph.Graph, scopes: Dict[str, Optional[int]]) -> List[ragraph.node.Node]

   Get scoped nodes, being subtrees of the graph of varying depth.

   :param graph: Graph data.
   :param scopes: Node names mapped to depths of the subtree to include. A depth of
                  :obj:`None` includes the whole subtree starting at that node.

   :returns: List of nodes in all given scopes.


.. py:function:: yield_subtree(root: ragraph.node.Node, depth: Optional[int]) -> Generator[ragraph.node.Node, None, None]

   Yield nodes from a given subtree starting at Node and with given depth.

   :param root: Root node of subtree.
   :param depth: Depth of subtree. If None, defaults to full depth.

   :Yields: Nodes in the subtree.