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]

   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

   For interactive web interface, use the separate syllable_walk_web module::

       python -m build_tools.syllable_walk_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.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:: main(args = None)

   Main entry point for syllable walker CLI.

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

   :param args: Command-line arguments. If None, uses sys.argv.

   :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