.. _root_flags:

Флаги вводимых команд
=====================

Флаги (или параметры) — это специальные аргументы, которые конечный юзер может добавлять к командам, чтобы управлять их поведением. 

-----

Синтаксис флагов
-----------------

Обобщённый синтаксис выглядит так:

.. code-block:: py

   <command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>

То есть, у флага обязательно должен быть префикс, который может быть одним, двум или трем минусам. После префикса следует имя флага, без
пробела, после, через пробел, идёт значение флага, если оно есть.

-----

Два типа флагов
---------------

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

.. note::
    Ошибки валидации значений являются пассивными, их не нужно обрабатывать явно. У каждого инстанса :ref:`InputFlag <root_api_command_input_flag>` есть поле ``status``, по которому можно определить результат валидации флага. **Конкретная реализация и описание API вы можете найти в разделе** :ref:`Flag <root_api_command_flag>`.

При регистрации флага вы можете указать допустимые для него значения, по умолчанию любое введённое значение для флага будет валидным. Допустимые значения можно указать различными способами:

-----

Ограничение по списку возможных значений
----------------------------------------

Вы можете заранее определить список допустимых значений для флага.

**Пример:**

Предположим, у вас есть флаг ``--format``, который может принимать только значения ``json`` или ``xml``.

.. code-block:: bash
   :linenos:

   # Эта команда сработает
   export --format json

   # А эта вызовет ошибку валидации, так как "csv" нет в списке разрешённых
   export --format csv
   
-----

Проверка с помощью регулярных выражений
-----------------------------------------

Для более сложных проверок вы можете использовать регулярные выражения. Это особенно полезно, когда значение должно соответствовать определённому формату, например, быть email-адресом, датой или номером телефона.

**Пример:**

Допустим, флаг ``--email`` должен принимать только корректные email-адреса.

.. code-block:: bash
   :linenos:

   # Сработает, так как значение соответствует формату email
   send --email "user@example.com"

   # Вызовет ошибку валидации, так как "user_example.com" — некорректный email
   send --email "user_example.com"

Встроенная валидация избавляет вас от необходимости писать ручные проверки и делает ваш код более декларативным.