build_tools.tui_common.interactive
==================================

.. py:module:: build_tools.tui_common.interactive

.. autoapi-nested-parse::

   Shared interactive mode utilities for syllable extractors.

   This module provides common interactive mode prompts and UI helpers
   used by both pyphen and NLTK syllable extractors.

   Usage::

       from build_tools.tui_common.interactive import (
           prompt_extraction_settings,
           prompt_input_file,
           print_banner,
           print_section,
       )

       # Display tool banner
       print_banner("PYPHEN SYLLABLE EXTRACTOR", [
           "This tool extracts syllables using dictionary-based hyphenation.",
           "Output is saved to _working/output/ by default.",
       ])

       # Get extraction settings
       min_len, max_len = prompt_extraction_settings(
           default_min=2,
           default_max=8,
       )

       # Get input file
       input_path = prompt_input_file()



Functions
---------

.. autoapisummary::

   build_tools.tui_common.interactive.print_banner
   build_tools.tui_common.interactive.print_section
   build_tools.tui_common.interactive.prompt_integer
   build_tools.tui_common.interactive.prompt_extraction_settings
   build_tools.tui_common.interactive.prompt_input_file
   build_tools.tui_common.interactive.print_extraction_complete


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

.. py:function:: print_banner(title, description_lines, width = 70)

   Print a formatted banner with title and description.

   :param title: Main title text (displayed in all caps)
   :param description_lines: List of description lines to display
   :param width: Banner width in characters (default: 70)

   .. admonition:: Example

      >>> print_banner("MY TOOL", [
      ...     "This tool does something useful.",
      ...     "Output is saved to output/ by default.",
      ... ])
      ======================================================================
      MY TOOL
      ======================================================================
      
      This tool does something useful.
      Output is saved to output/ by default.
      ======================================================================


.. py:function:: print_section(title, width = 70)

   Print a section header.

   :param title: Section title text
   :param width: Section width in characters (default: 70)

   .. admonition:: Example

      >>> print_section("EXTRACTION SETTINGS")
      ----------------------------------------------------------------------
      EXTRACTION SETTINGS
      ----------------------------------------------------------------------


.. py:function:: prompt_integer(prompt_text, default, min_value = 1, max_value = None, compare_to = None, compare_label = 'minimum')

   Prompt for an integer value with validation.

   :param prompt_text: Text to display in the prompt
   :param default: Default value if user presses Enter
   :param min_value: Minimum allowed value (default: 1)
   :param max_value: Maximum allowed value (optional)
   :param compare_to: Value that this must be >= (for max > min validation)
   :param compare_label: Label for compare_to value in error message

   :returns: Validated integer value

   .. admonition:: Example

      >>> min_len = prompt_integer(
      ...     "Minimum syllable length",
      ...     default=2,
      ...     min_value=1,
      ... )
      >>> max_len = prompt_integer(
      ...     "Maximum syllable length",
      ...     default=8,
      ...     min_value=1,
      ...     compare_to=min_len,
      ...     compare_label="minimum",
      ... )


.. py:function:: prompt_extraction_settings(default_min = 2, default_max = 8, min_label = 'Minimum syllable length', max_label = 'Maximum syllable length')

   Prompt for min/max syllable length extraction settings.

   :param default_min: Default minimum syllable length
   :param default_max: Default maximum syllable length
   :param min_label: Label for minimum prompt
   :param max_label: Label for maximum prompt

   :returns: Tuple of (min_len, max_len)

   .. admonition:: Example

      >>> print_section("EXTRACTION SETTINGS")
      >>> min_len, max_len = prompt_extraction_settings()
      >>> print(f"✓ Settings: syllables between {min_len}-{max_len} characters")


.. py:function:: prompt_input_file(prompt_text = "Enter input file path (or 'quit' to exit): ")

   Prompt for an input file path with tab completion.

   Includes:
   - Tab completion hint (if readline available)
   - Home directory expansion (~)
   - File existence validation
   - 'quit' command to exit

   :param prompt_text: Text to display in the prompt

   :returns: Validated Path to the input file

   :raises SystemExit: If user types 'quit'

   .. admonition:: Example

      >>> print_section("INPUT FILE SELECTION")
      >>> input_path = prompt_input_file()


.. py:function:: print_extraction_complete(syllables_path, metadata_path, output_base_dir)

   Print extraction completion message with output paths.

   :param syllables_path: Path to saved syllables file
   :param metadata_path: Path to saved metadata file
   :param output_base_dir: Base output directory for relative path display

   .. admonition:: Example

      >>> print_extraction_complete(
      ...     syllables_path=Path("output/20260110/syllables/test.txt"),
      ...     metadata_path=Path("output/20260110/meta/test.txt"),
      ...     output_base_dir=Path("output/"),
      ... )