build_tools.tui_common.cli_utils
================================

.. py:module:: build_tools.tui_common.cli_utils

.. autoapi-nested-parse::

   Shared CLI utilities for build tools.

   This module provides common functionality used across multiple CLI tools,
   including tab completion, file discovery, and corpus database integration.

   These utilities were extracted from the syllable extractor CLIs to eliminate
   duplication and ensure consistent behavior across tools.



Attributes
----------

.. autoapisummary::

   build_tools.tui_common.cli_utils.READLINE_AVAILABLE
   build_tools.tui_common.cli_utils.CORPUS_DB_AVAILABLE


Functions
---------

.. autoapisummary::

   build_tools.tui_common.cli_utils.record_corpus_db_safe
   build_tools.tui_common.cli_utils.path_completer
   build_tools.tui_common.cli_utils.setup_tab_completion
   build_tools.tui_common.cli_utils.input_with_completion
   build_tools.tui_common.cli_utils.discover_files


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

.. py:data:: READLINE_AVAILABLE
   :value: True


.. py:data:: CORPUS_DB_AVAILABLE
   :value: True


.. py:function:: record_corpus_db_safe(operation, func, quiet = False)

   Execute corpus_db operation with safe error handling.

   If corpus_db recording fails, logs warning to stderr but allows
   extraction to continue. Ensures corpus_db is purely observational.

   :param operation: Description of operation (e.g., "start run")
   :param func: Callable performing the corpus_db operation
   :param quiet: If True, suppress warning messages

   :returns: Result of func() if successful, None if failed


.. py:function:: path_completer(text, state)

   Tab completion function for file paths.

   This enables bash-like tab completion for navigating directories
   and selecting files.

   :param text: The current text being completed
   :param state: The completion state (0 for first call, incremented for each match)

   :returns: The next completion match, or None when no more matches


.. py:function:: setup_tab_completion()

   Configure readline for tab completion with file paths.

   This enables:
   - Tab completion for file and directory names
   - Tilde (~) expansion for home directory
   - Standard bash-like completion behavior


.. py:function:: input_with_completion(prompt)

   Get user input with tab completion enabled.

   :param prompt: The prompt to display

   :returns: User input string


.. py:function:: discover_files(source, pattern = '*.txt', recursive = False)

   Discover text files in a directory matching the specified pattern.

   This function searches for files matching a glob pattern in the specified
   directory, optionally recursing into subdirectories. Results are sorted
   alphabetically for deterministic processing order.

   :param source: Directory to search for files. Must be an existing directory.
   :param pattern: Glob pattern for file matching (default: "*.txt").
                   Examples: "*.txt", "*.md", "data_*.csv"
   :param recursive: If True, search recursively into subdirectories using rglob.
                     If False, search only the top level (default: False).

   :returns: List of Path objects for matching files, sorted alphabetically.
             Returns empty list if no files match.

   :raises ValueError: If source is not a directory or doesn't exist.

   .. admonition:: Example

      >>> # Find all .txt files in a directory
      >>> files = discover_files(Path("/data/texts"))
      >>> print(f"Found {len(files)} files")
      
      >>> # Find all .md files recursively
      >>> files = discover_files(Path("/data"), pattern="*.md", recursive=True)
      
      >>> # Find files with custom pattern
      >>> files = discover_files(Path("/data"), pattern="book_*.txt")