.. _root_api_command_index:

Command
=======

Объект ``Command`` представляет собой основную единицу функциональности в приложении ``Argenta``. Каждая команда определяет конкретное действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и образуют интерфейс взаимодействия с приложением.

``Command`` инкапсулирует всю необходимую информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов для настройки поведения и список псевдонимов для альтернативных способов вызова.

-----

Инициализация
-------------

.. code-block:: python
   :linenos:

   __init__(self, trigger: str, *,
            description: str | None = None,
            flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
            aliases: list[str] | None = None) -> None

Создает новую команду для регистрации в роутере.

* ``trigger`` : Строковый триггер команды, который пользователь должен ввести для её вызова. Это основной идентификатор команды в системе.

* ``description`` : Необязательное описание команды, объясняющее её назначение. Если не указано, используется значение по умолчанию ``"Command without description"``. Отображается в справке и списке доступных команд.

* ``flags`` : Набор флагов команды для настройки её поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``. По умолчанию команда создается без флагов.

* ``aliases`` : Список строковых синонимов для основного триггера. Позволяет вызывать команду альтернативными способами. По умолчанию список пуст.

**Атрибуты:**

.. py:attribute:: trigger

   Основной триггер команды в виде строки. Используется для идентификации команды при парсинге пользовательского ввода.

.. py:attribute:: description

   Текстовое описание команды. Если не было передано при инициализации, содержит значение ``"Command without description"``.

.. py:attribute:: registered_flags

   Объект ``Flags``, содержащий все зарегистрированные флаги команды. Автоматически конвертируется из одиночного ``Flag`` в коллекцию при инициализации.

.. py:attribute:: aliases

   Список строк с альтернативными триггерами команды. Пустой список, если псевдонимы не заданы.

**Пример использования:**

.. literalinclude:: ../../../code_snippets/command/snippet.py
   :linenos:
   
.. seealso ::
   Подробнее про флаги: :ref:`Flags <root_api_command_flags>` и :ref:`Флаги вводимых команд <root_flags>`.

-----

Регистрация команд
------------------

Команды регистрируются в роутерах с помощью декоратора ``@router.command()``. После регистрации команда становится доступной пользователям для вызова.

**Базовый пример:**

.. literalinclude:: ../../../code_snippets/command/snippet2.py
   :linenos:

**Команды с флагами:**

.. literalinclude:: ../../../code_snippets/command/snippet3.py
   :linenos:

-----

Работа с псевдонимами
---------------------

Псевдонимы позволяют вызывать один и тот же хэндлер разными триггерами, сохраняя при этом флаги команды и описание.

**Пример с псевдонимами:**

.. code-block:: python
   :linenos:

   from argenta import Router, Command

   router = Router(title="System")

   @router.command(Command(
       "shutdown",
       description="Shutdown the system",
       aliases=["poweroff", "halt", "stop"]
   ))
   def handle_shutdown(response):
       response.write("Shutting down the system...")

Теперь пользователь может вызвать команду любым из способов:

.. code-block:: bash

   shutdown
   poweroff
   halt
   stop

Все эти варианты выполнят одну и ту же функцию ``handle_shutdown``.

-----
    
.. _root_api_command_input_command:

InputCommand
------------

Класс ``InputCommand`` представляет собой распаршенную команду, введенную пользователем. Это внутренний класс, который создается автоматически при парсинге пользовательского ввода. Непосредственная работа с данным классом возможна при создании кастомного хэндлера для обработки неизвестных команд.

.. seealso ::
   Подробнее про кастомные хэндлеры обработки исключений ввода :ref:`тут <root_error_handling>`

Создает экземпляр распарсенной команды.

:param trigger: Триггер команды, извлеченный из пользовательского ввода
:param input_flags: Флаги, переданные пользователем при вызове команды

**Атрибуты:**

.. py:attribute:: trigger
   :no-index:

   Строковый триггер команды, введенный пользователем.

.. py:attribute:: input_flags

   Объект ``InputFlags``, содержащий все флаги, переданные с командой. Автоматически конвертируется из одиночного ``InputFlag`` в коллекцию.

.. toctree ::
    :hidden:
    
    flag
    possible_values
    input_flag
    validation_status
    flags 
    input_flags