build_tools.syllable_walk.cli
=============================

.. py:module:: build_tools.syllable_walk.cli

.. autoapi-nested-parse::

   Command-line interface for syllable walker.

   This module provides both interactive and batch processing functionality
   for exploring syllable feature space through random walks.

   Usage:
       python -m build_tools.syllable_walk [options]

   .. admonition:: Examples

      # Generate a single walk
      python -m build_tools.syllable_walk data.json --start ka --profile dialect
      
      # Compare all profiles
      python -m build_tools.syllable_walk data.json --start bak --compare-profiles
      
      # Generate batch of walks
      python -m build_tools.syllable_walk data.json --batch 50 --output walks.json
      
      # Start interactive web interface
      python -m build_tools.syllable_walk data.json --web



Functions
---------

.. autoapisummary::

   build_tools.syllable_walk.cli.create_argument_parser
   build_tools.syllable_walk.cli.parse_arguments
   build_tools.syllable_walk.cli.single_walk_mode
   build_tools.syllable_walk.cli.compare_profiles_mode
   build_tools.syllable_walk.cli.batch_mode
   build_tools.syllable_walk.cli.search_mode
   build_tools.syllable_walk.cli.web_mode
   build_tools.syllable_walk.cli.main


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

.. py:function:: create_argument_parser()

   Create and return the argument parser for syllable walker.

   This function creates the ArgumentParser with all CLI options but does not
   parse arguments. This separation allows Sphinx documentation tools to
   introspect the parser and auto-generate CLI documentation.

   :returns: Configured ArgumentParser ready to parse command-line arguments

   .. admonition:: Examples

      Create parser and inspect options::
      
          >>> parser = create_argument_parser()
          >>> parser.prog
          'cli.py'
      
      Use parser to parse arguments::
      
          >>> parser = create_argument_parser()
          >>> args = parser.parse_args(["data.json", "--start", "ka"])
          >>> args.start
          'ka'

   .. admonition:: Notes

      - This function is used by both the CLI and documentation generation
      - For normal CLI usage, use main() which calls this internally
      - Sphinx-argparse can introspect this function to generate docs


.. py:function:: parse_arguments(args = None)

   Parse command-line arguments.

   :param args: List of argument strings to parse. If None, uses sys.argv[1:].
                This parameter is useful for testing.

   :returns: Parsed arguments as argparse.Namespace object

   .. admonition:: Example

      >>> args = parse_arguments(["data.json", "--start", "ka"])
      >>> args.start
      'ka'


.. py:function:: single_walk_mode(walker, args)

   Handle single walk generation mode.

   :param walker: Initialized SyllableWalker instance
   :param args: Parsed command-line arguments

   :returns: Exit code (0 = success, 1 = error)


.. py:function:: compare_profiles_mode(walker, args)

   Handle profile comparison mode.

   :param walker: Initialized SyllableWalker instance
   :param args: Parsed command-line arguments

   :returns: Exit code (0 = success, 1 = error)


.. py:function:: batch_mode(walker, args)

   Handle batch walk generation mode.

   :param walker: Initialized SyllableWalker instance
   :param args: Parsed command-line arguments

   :returns: Exit code (0 = success, 1 = error)


.. py:function:: search_mode(walker, args)

   Handle syllable search mode.

   :param walker: Initialized SyllableWalker instance
   :param args: Parsed command-line arguments

   :returns: Exit code (0 = success)


.. py:function:: web_mode(args)

   Handle web server mode.

   Starts the interactive web interface for syllable walking. The server runs
   until interrupted with Ctrl+C. Walker initialization happens inside run_server().

   :param args: Parsed command-line arguments

   :returns: Exit code (0 = success, 1 = error)

   .. admonition:: Notes

      - This function calls run_server() which initializes the walker
      - The server runs until stopped with Ctrl+C
      - Any errors during initialization or server startup are caught


.. py:function:: main()

   Main entry point for syllable walker CLI.

   Parses arguments, validates inputs, initializes walker, and executes
   requested operation mode.

   :returns:

             - 0: Success
             - 1: Error (file not found, invalid arguments, etc.)
             - 2: Validation error (incompatible arguments)
             - 130: Keyboard interrupt (Ctrl+C)
   :rtype: Exit code

   .. admonition:: Notes

      - Errors are printed to stderr
      - Normal output goes to stdout
      - Keyboard interrupt (Ctrl+C) exits cleanly with code 130