markitect-main/tools/emoji_utils.py

"""
Shared utilities for emoji/ASCII output mode handling - Issue #37

This module provides common functionality for handling emoji vs ASCII output
preferences across different MarkiTect tools. It implements the standardized
approach for emoji preference handling with proper priority management.

Priority Order:
1. CLI flags (--ascii or --emoji) - highest priority
2. MARKITECT_EMOJI environment variable - medium priority
3. Default to emoji output - fallback behavior

Environment Variable Support:
- MARKITECT_EMOJI=true/false (case-insensitive)
- Valid false values: 'false', 'f', '0'
- Invalid values default to emoji output (true)

Usage:
    from emoji_utils import determine_output_mode, add_emoji_arguments

    parser = argparse.ArgumentParser(description='My tool')
    add_emoji_arguments(parser)
    args = parser.parse_args()
    use_ascii = determine_output_mode(args)
"""

import os


def determine_output_mode(args):
    """
    Determine whether to use ASCII or emoji output based on CLI args and env.

    This function implements the standardized priority logic for emoji/ASCII
    mode selection across MarkiTect tools. It respects user preferences set
    via CLI flags or environment variables, with appropriate fallback behavior.

    Priority order (highest to lowest):
    1. CLI flags (--ascii or --emoji) - explicit user choice
    2. MARKITECT_EMOJI environment variable - persistent user preference
    3. Default to emoji output - engaging default behavior

    Environment Variable Handling:
    - MARKITECT_EMOJI is processed case-insensitively
    - Valid false values: 'false', 'f', '0'
    - All other values (including invalid ones) default to emoji mode
    - This provides robust fallback behavior for configuration errors

    Args:
        args (argparse.Namespace): Parsed command line arguments containing
            'ascii' and 'emoji' boolean attributes from add_emoji_arguments()

    Returns:
        bool: True if ASCII mode should be used, False for emoji mode

    Example:
        >>> args = parser.parse_args(['--ascii'])
        >>> determine_output_mode(args)
        True

        >>> # With MARKITECT_EMOJI=false environment variable set
        >>> args = parser.parse_args([])
        >>> determine_output_mode(args)
        True
    """
    # CLI flags take precedence
    if args.ascii:
        return True
    if args.emoji:
        return False

    # No explicit flag, check environment variable
    emoji_env = os.getenv('MARKITECT_EMOJI', 'true').lower()
    return emoji_env in ['false', 'f', '0']


def add_emoji_arguments(parser):
    """
    Add standardized emoji/ASCII output format arguments to an ArgumentParser.

    This function adds the standard --ascii and --emoji flags to any
    command-line tool, ensuring consistent behavior across MarkiTect. The flags
    are configured as mutually exclusive to prevent conflicting output modes.

    The added arguments integrate seamlessly with determine_output_mode() to
    provide complete emoji preference handling.

    Arguments Added:
    - --ascii: Use ASCII characters only (no emojis)
    - --emoji: Use emoji output (default behavior)

    Args:
        parser (argparse.ArgumentParser): The ArgumentParser instance to modify

    Returns:
        argparse._MutuallyExclusiveGroup: The mutually exclusive group
            containing the emoji-related arguments for further customization

    Example:
        >>> import argparse
        >>> parser = argparse.ArgumentParser(description='My tool')
        >>> parser.add_argument('input_file', help='Input file path')
        >>> emoji_group = add_emoji_arguments(parser)
        >>> args = parser.parse_args(['file.txt', '--ascii'])
        >>> print(f"Use ASCII: {determine_output_mode(args)}")
        Use ASCII: True

    Note:
        This function must be called before parser.parse_args() to ensure
        the arguments are available for parsing.
    """
    format_group = parser.add_mutually_exclusive_group()
    format_group.add_argument(
        '--ascii', action='store_true',
        help='Use ASCII characters only (no emojis)')
    format_group.add_argument(
        '--emoji', action='store_true',
        help='Use emoji output (default)')
    return format_group