"""
Debug output control utility.

This module provides a centralized way to control debug output across the project.
Debug output is disabled by default and can be enabled via the OMML2TEX_DEBUG
environment variable.

Usage:
    from omml2tex.utils.debug import debug_print

    debug_print("[DEBUG] Some debug info")  # Only prints if OMML2TEX_DEBUG=1

Environment Variables:
    OMML2TEX_DEBUG: Set to "1" or "true" to enable debug output (default: disabled)
"""

import os
import sys


def is_debug_enabled() -> bool:
    """
    Check if debug mode is enabled via environment variable.

    Returns:
        True if OMML2TEX_DEBUG is set to "1" or "true", False otherwise
    """
    debug_value = os.environ.get('OMML2TEX_DEBUG', '').lower()
    return debug_value in ('1', 'true', 'yes', 'on')


def debug_print(*args, **kwargs):
    """
    Print debug output only if debug mode is enabled.

    This function has the same signature as the built-in print() function,
    but only outputs to stderr when OMML2TEX_DEBUG environment variable is set.

    Args:
        *args: Arguments to print
        **kwargs: Keyword arguments for print (e.g., file, sep, end)

    Examples:
        >>> debug_print("[DEBUG] Processing equation")
        >>> debug_print("[DEBUG] Value:", value, "Result:", result)
        >>> debug_print("[DEBUG] Error", file=sys.stderr)  # file=sys.stderr is default
    """
    if is_debug_enabled():
        # Default to stderr if file not specified
        if 'file' not in kwargs:
            kwargs['file'] = sys.stderr
        print(*args, **kwargs)


__all__ = ['is_debug_enabled', 'debug_print']