mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 18:15:28 +03:00
75 lines
4.0 KiB
ReStructuredText
75 lines
4.0 KiB
ReStructuredText
.. _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"
|
|
|
|
Встроенная валидация избавляет вас от необходимости писать ручные проверки и делает ваш код более декларативным.
|