.. _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"

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