"""Main command interface - equivalent to C++ IMainCommand."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Protocol


class IMainCommand(ABC):
    """Abstract base class for command processors.

    This interface handles command execution routing, equivalent to
    the C++ IMainCommand interface.
    """

    @abstractmethod
    def init(self) -> None:
        """Initialize the command processor.

        Sets up command mappings and registrations.
        """

    @abstractmethod
    def execute_command(self, command_id: str, in_param: object = None, out_param: object = None) -> bool:
        """Execute a specific command.

        Args:
            command_id: Command identifier to execute
            in_param: Input parameters for the command
            out_param: Output parameters (mutable)

        Returns
        -------
            bool: True if command executed successfully
        """

    @abstractmethod
    def get_command_count(self) -> int:
        """Get the number of supported commands.

        Returns
        -------
            int: Total number of commands this processor handles
        """

    @abstractmethod
    def get_command_id(self, index: int) -> str:
        """Get command ID by index.

        Args:
            index: Command index (0-based)

        Returns
        -------
            str: Command identifier at the given index
        """


# Protocol version for type checking
class MainCommandProtocol(Protocol):
    """Protocol for command processor type checking."""

    def init(self) -> None:
        """Initialize the command processor.

        Sets up command mappings and registrations.
        """

    def execute_command(self, command_id: str, in_param: object, out_param: object) -> bool:
        """Execute a command.

        Args:
            command_id: Command identifier to execute
            in_param: Input parameters for the command
            out_param: Output parameters (mutable)

        Returns
        -------
            bool: True if command executed successfully
        """

    def get_command_count(self) -> int:
        """Get the number of supported commands.

        Returns
        -------
            int: Total number of commands this processor handles
        """

    def get_command_id(self, index: int) -> str:
        """Get command ID by index.

        Args:
            index: Command index (0-based)

        Returns
        -------
            str: Command identifier at the given index
        """
