Определяет значение аргумента по умолчанию, либо список возможных значений.

Если default пуст, либо отсутствует, аргумент будет обязательным.

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

  a:
    default: 53

Если default - список из одного пустого значения, то аргумент будет опцией с пустым значением по умолчанию. Пример:

  a:
    default:
      -

Если default содержит список из двух элементов, то аргумент будет флагом, подставляющим первое значение когда отсутствует в команде, а второе - когда присутствует. Пример:

  a:
    default:
      - https://
      - http://

Если default содержит список из более чем трех элементов, аргумент сможет принимать только значения из списка. Если при этом первый элемент пуст, то аргумент будет обязательным, если же нет - первое значение из списка будет использоваться по умолчанию. Пример:

  arg:
    default:
      -
      - one
      - two

Содержит описание назначения аргумента, которое будет выведено при вызове помощи use <script name> -h или use <script name> --help. Пример:

  arg:
    description: очень важный аргумент

Косметический ключ, позволяющий задать свое метазначение для опций. На позиционные аргументы не влияет.

Пример:

arg:
  default: 42
  metavar: MY_METAVAR

Отображение:

usage: test [--arg MY_METAVAR] [-h]

options:
  --arg MY_METAVAR  (default: '42')
  -h, --help        show this help message and exit

Определяет, может ли аргумент принимать множественные значения, или нет. По умолчанию false. Пример:

  arg:
    multiple: true

Содержит строку, котороя будет заменятья в коде скрипта (ключ script) на значение аргумента. Не самое элегантное решение, но позволяет творить интересные трюки в комбинации с mode: format.

Реплейсеры в коде скрипта заменяются в том порядке, в каком описаны ключи в arguments. После аргументов в код подставляются значения file_[NUMBER], если они есть.

Если ключ отсутвует либо пуст, то реплейсер принимает значение #[ARGUMENT NAME]#

Пример реплейсеров и скрипта:

arguments:
  arg:
    replacer: -+PLACEHOLDER+-
script: >-
  cat -+PLACEHOLDER+- | ncat 127.0.0.1 9090

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

Пример:

arguments:
  ip:
    regex: >-
      ((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3,3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])

script: 'echo #ip# is ok'

Реакция скрипта на ввод:

$ bashmator use ip 77.88.55.60
77.88.55.60 is ok

$ bashmator use ip 77.88.55.601
ip: error: argument 'ip': invalid value '77.88.55.601'

Содержит список имен аргументов, которые будут интерпритированы как имена файлов.

Данные файлы будут читаться построчно, а считанные строки будут подставляться в скрипт на место реплейсера.

Если файла не существует, то будет подставлено входящиее значение аргумента.

Пример:

shell: bash
arguments:
  arg1:
    description: test
mode:
  readfile:
    - arg1
script: >-
  echo #arg1#

Содержимое файла some_file.txt:

one
two
three

Если запустить скрипт с аргументом ./some_file.txt, то для исполнения будет сформирован следующий код:

echo one two three

Подзволяет заменять значения аргументов. Содержит в себе имена аргументов в качестве ключей, которые в свою очередь содержат замены в виде ключ:значение.

Пример:

shell: bash
arguments:
  arg1:
    default:
      - A
      - B
      - C
mode:
  replace:
    arg1:
      A: One
      B: Two
script: >-
  echo #arg1#

В данном примере, когда на вход скрпта в аргумент --arg1 будет подаваться значение A, в скрипт будет подставлено значение One, а когда B - Two. Значение C заменено не будет и попадет в скрипт напрямую.

Если содержит имя множественного аргумента (multiply: true), то скрипт будет запускаться отдельно для каждого его значения. По умолчанию этого не происходит.

Пример:

shell: bash
arguments:
  arg1:
    multiple: true
mode:
  loop: arg1
script: >-
  echo -n #arg1#; echo ' end'

Результат выполнения скрипта c аргументами 1 2 3 4 5:

1 end
2 end
3 end
4 end
5 end

Содержит имена аргументов в качестве ключей и шаблоны python функции .format() в качестве значений. Если значение аргумента пусто, то форматирование не происходит и соответсвующий реплейсер удаляется из скрипта.

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

Обычно этот ключ применяется для правильной подстановки неоднозначных значений с использованием шаблона {0!r}, однако в комбинации с пустыми по умолчанию аргументами может позволить опционально вставлять в скрипт дополнительные куски.

Пример:

shell: bash
arguments:
  arg1:
    default:
      -
  arg2:
    multiple: true
mode:
  format:
    arg1: >-
      | tee {0!r}
    arg2: >-
      {0!r}
script: >-
  echo #arg1# #arg2#

Если запустить скрипт с аргументами a d c r t, для исполнения будет сформирован следующий код:

echo 'a' 'd' 'c' 'r' 't' 

Если с аргументами --arg1 ./file.txt a d c r t:

echo 'a' 'd' 'c' 'r' 't' | tee './test.txt'

Содержит имена множественных аргументов (multiply: true) в качестве ключей и строки-разделители для объединения в качестве значений. По умолчанию объединение значений множественных аргументов происходит через пробел.

Пример:

  join:
    arg1: ','

В этом случае значения множественного аргумента arg1 будут подставлены в скрипт в виде следующей строки:

val1,val2,val3,val4

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

⚠️ Обязательный ключ

Содержит путь до файла в библиотеке относительно директории files. Используйте / для перехода в директорию независимо от системы (windows, linux). Пример:

file_1:
  path: lorem/lorem.txt

Так же можно обращаться к файлам по полному пути и использовать возвраты в родительскую директорию, но этого делать не рекомендуется. Скорее всего я закрою эту возможность спустя какое-то время, так как это больше баг, чем фитча 🥲.

Работает аналогично ключу replacer для arguments, но не подвергается форматированию.

Содержит краткое описание файла, которое будет выведено при вызове помощи use <script name> -h или use <script name> --help.

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

Пример:

file_1:
  path: "lorem folder/lorem'.txt"
  quote:
    - "'"
    - '\'

При выполнении подставит следующую строку:

'/<library path>/lorem folder/lorem\'.txt'

Работает аналогично ключу shell в корне. Если ключ отсутствует, item будет использовать значение главного shell.

Работает аналогично ключу mode в корне. Используется для изменения главных параметров форматирования для item.

Чтобы отметить действие loop главного mode, оставьте ключ пустым. Например:

item_2:
  script: echo _A_
  mode:
    loop:

Содержит краткое описание назначения item, которое будет выведено при вызове помощи use <script name> -h или use <script name> --help.

⚠️ Обязательный ключ

Работает аналогично главному script.