std.getopt

Обработка параметров командной строки.

Модуль getopt реализует функцию getopt, которая соответствует синтаксису параметров командной строки POSIX. Поддерживаются расширения GNU в виде длинных параметров, вводимых с помощью двойного дефиса ("--"). Поддержка объединения параметров командной строки, как это было в случае с более традиционным подходом с однобуквенными параметрами, предоставляется, но по умолчанию не включена.

Лицензия:: Лицензия Boost 1.0.

Авторы:: Андрей Александреску

Уведомление: Этот модуль и его документация вдохновлены модулем Perl's Getopt::Long. Синтаксис D's getopt проще, чем его аналог в Perl, потому что getopt выводит ожидаемые типы параметров из статических типов переданных указателей.

Исходный код: std/getopt.d

класс GetOptException: object.Exception;

Выбрасывается при одном из следующих условий:

Передается нераспознанный аргумент командной строки, и std.getopt.config.passThrough отсутствовал.
Параметр командной строки не найден, и std.getopt.config.required был указан.

GetoptResult getopt(T...)(ref string[] args, T opts);

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

Синопсис

import std.getopt;

string data = "file.dat";
int length = 24;
bool verbose;
enum Color { no, yes };
Color color;

void main(string[] args)
{
  auto helpInformation = getopt(
    args,
    "length",  &length,    // numeric
    "file",    &data,      // string
    "verbose", &verbose,   // flag
    "color", "Information about this color", &color);    // enum
  ...

  if (helpInformation.helpWanted)
  {
    defaultGetoptPrinter("Some information about the program.",
      helpInformation.options);
  }
}

Функция getopt принимает ссылку на командную строку (полученную main) в качестве первого аргумента и неограниченное количество пар строк и указателей. Каждая строка — это параметр, предназначенный для "заполнения" значения, на которое указывает указатель справа (указатель "связи"). Строка параметра в вызове getopt не должна начинаться с дефиса. Во всех случаях параметры командной строки, которые были обработаны и использованы getopt, удаляются из args. Всё, что в аргументах не выглядело как параметр, остается в args для дальнейшей обработки программой. Значения, на которые параметры не повлияли, не трогаются, поэтому распространённым приёмом является инициализация параметров их значениями по умолчанию, а затем вызов getopt. Если аргумент командной строки распознаётся как параметр с параметром, и параметр не может быть правильно обработано (например, ожидается число, но его нет), выбрасывается исключение ConvException. Если std.getopt.config.passThrough не был передан getopt, и найден нераспознанный аргумент командной строки, выбрасывается GetOptException. В зависимости от типа связываемого указателя, getopt распознаёт следующие типы параметров:

Булевы параметры. Одиночный аргумент устанавливает параметр в true. Дополнительно, true или false можно задать внутри параметра, разделив их знаком "=":
```
  bool verbose = false, debugging = true;
  getopt(args, "verbose", &verbose, "debug", &debugging);
```
Для установки verbose в true, вызовите программу с --verbose или --verbose=true. Для установки debugging в false, вызовите программу с --debugging=false.
Числовые параметры. Если параметр связан с числовым типом, ожидается число как следующий параметр или прямо внутри параметра, разделённое знаком "=":
```
  uint timeout;
  getopt(args, "timeout", &timeout);
```
Для установки timeout в 5, вызовите программу с --timeout=5 или --timeout 5.
Инкрементные параметры. Если имя параметра имеет суффикс "+" и связан с числовым типом, то значение параметра отслеживает количество раз, когда этот параметр встречался в командной строке:
```
  uint paranoid;
  getopt(args, "paranoid+", &paranoid);
```
Вызов программы с "--paranoid --paranoid --paranoid" установит paranoid в 3. Обратите внимание, что инкрементный параметр никогда не ожидает параметра, например, в командной строке "--paranoid 42 --paranoid" "42" не установит paranoid в 42; вместо этого paranoid устанавливается в 2, и "42" не рассматривается как часть обычных аргументов программы.
Параметры перечисления. Если параметр связан с перечислением, ожидается символ перечисления как строка как следующий параметр или прямо внутри параметра, разделённое знаком "=":
```
  enum Color { no, yes };
  Color color; // default initialized to Color.no
  getopt(args, "color", &color);
```
Для установки color в Color.yes, вызовите программу с --color=yes или --color yes.
Строковые параметры. Если параметр связан со строкой, ожидается строка как следующий параметр или прямо внутри параметра, разделённое знаком "=":
```
string outputFile;
getopt(args, "output", &outputFile);
```
Вызов программы с "--output=myfile.txt" или "--output myfile.txt" установит outputFile в "myfile.txt". Если вы хотите передать строку, содержащую пробелы, вам нужно использовать цитирование, которое подходит для вашей оболочки, например, --output='my file.txt'.
Массивные параметры. Если параметр связан с массивом, новый элемент добавляется в массив каждый раз, когда этот параметр встречается:
```
string[] outputFiles;
getopt(args, "output", &outputFiles);
```
Вызов программы с "--output=myfile.txt --output=yourfile.txt" или "--output myfile.txt --output yourfile.txt" установит outputFiles в [ "myfile.txt", "yourfile.txt" ]. В качестве альтернативы можно установить arraySep, чтобы разрешить несколько элементов в одном параметре.
```
string[] outputFiles;
arraySep = ",";  // defaults to "", meaning one element per parameter
getopt(args, "output", &outputFiles);
```
С помощью приведенного кода вы можете вызвать программу с "--output=myfile.txt,yourfile.txt" или "--output myfile.txt,yourfile.txt".
Хэшовые параметры. Если параметр связан с ассоциативным массивом, ожидается строка вида "name=value" как следующий параметр, или прямо внутри параметра, разделённое знаком "=":
```
double[string] tuningParms;
getopt(args, "tune", &tuningParms);
```
Вызов программы с e.g. "--tune=alpha=0.5 --tune beta=0.6" установит tuningParms в [ "alpha" : 0.5, "beta" : 0.6 ]. В качестве альтернативы можно установить arraySep в качестве разделителя элементов:
```
double[string] tuningParms;
arraySep = ",";  // defaults to "", meaning one element per parameter
getopt(args, "tune", &tuningParms);
```
С помощью приведенного кода вы можете вызвать программу с "--tune=alpha=0.5,beta=0.6" или "--tune alpha=0.5,beta=0.6". В общем случае ключи и значения могут быть любого парсируемого типа.
Параметры обратного вызова. Параметр может быть связан с функцией или делегатом с сигнатурой void function(), void function(string option), void function(string option, string value), или их эквивалентами делегатов.
- Если обратный вызов не принимает аргументов, обратный вызов вызывается всякий раз, когда этот параметр виден.
- Если обратный вызов принимает один строковый аргумент, строка параметра (без ведущего дефиса(ов)) передаётся обратному вызову. После этого строка параметра считается обработанной и удаляется из массива параметров.
```
void main(string[] args)
{
  uint verbosityLevel = 1;
  void myHandler(string option)
  {
    if (option == "quiet")
    {
      verbosityLevel = 0;
    }
    else
    {
      assert(option == "verbose");
      verbosityLevel = 2;
    }
  }
  getopt(args, "verbose", &myHandler, "quiet", &myHandler);
}
```
- Если обратный вызов принимает два строковых аргумента, строка параметра обрабатывается как параметр с одним аргументом и парсится соответственно. Параметр и его значение передаются обратному вызову. После этого всё, что было передано обратному вызову, считается обработанным и удаляется из списка.
```
int main(string[] args)
{
  uint verbosityLevel = 1;
  bool handlerFailed = false;
  void myHandler(string option, string value)
  {
    switch (value)
    {
      case "quiet": verbosityLevel = 0; break;
      case "verbose": verbosityLevel = 2; break;
      case "shouting": verbosityLevel = verbosityLevel.max; break;
      default :
        stderr.writeln("Unknown verbosity level ", value);
        handlerFailed = true;
        break;
    }
  }
  getopt(args, "verbosity", &myHandler);
  return handlerFailed ? 1 : 0;
}
```

Параметры с несколькими именами: Иногда желательны синонимы параметров, например, "--verbose", "--loquacious" и "--garrulous" должны иметь одинаковый эффект. Такие альтернативные имена параметров можно включить в спецификацию параметра, используя "|" в качестве разделителя:

bool verbose;
getopt(args, "verbose|loquacious|garrulous", &verbose);

Регистр: По умолчанию регистр параметров не учитывается. Вы можете изменить это поведение, передав getopt директиву caseSensitive следующим образом:

bool foo, bar;
getopt(args,
    std.getopt.config.caseSensitive,
    "foo", &foo,
    "bar", &bar);

В приведенном примере "--foo" и "--bar" распознаются, но "--Foo", "--Bar", "--FOo", "--bAr" и т. д. отклоняются. Директива активна до конца getopt, или пока не встретится обратная директива caseInsensitive:

bool foo, bar;
getopt(args,
    std.getopt.config.caseSensitive,
    "foo", &foo,
    std.getopt.config.caseInsensitive,
    "bar", &bar);

Параметр "--Foo" отклоняется из-за std.getopt.config.caseSensitive, но не "--Bar", "--bAr" и т. д., потому что директива std.getopt.config.caseInsensitive отключила учёт регистра до обработки параметра "bar".

Короткие против длинных параметров: Традиционно программы принимали параметры с одной буквой, предваряемые одним дефисом (например, -t). getopt беспрепятственно принимает такие параметры. Когда используется двойной дефис (например, --t), однобуквенный параметр ведет себя так же, как параметр с несколькими буквами. При использовании одного дефиса однобуквенный параметр принимается.

Для установки timeout в 5, используйте любой из следующих вариантов: --timeout=5, --timeout 5, --t=5, --t 5, -t5, или -t 5. Форматы, такие как -timeout=5 не будут приняты. Более подробную информацию о коротких параметрах см. также в следующем разделе.

Объединение: Однобуквенные параметры могут быть объединены, т. е. "-abc" эквивалентно "-a -b -c". По умолчанию этот параметр выключен. Вы можете включить его с помощью директивы std.getopt.config.bundling:

bool foo, bar;
getopt(args,
    std.getopt.config.bundling,
    "foo|f", &foo,
    "bar|b", &bar);

В случае если вы хотите включить объединение только для некоторых параметров, объединение может быть выключено с помощью std.getopt.config.noBundling.

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

bool foo, bar;
getopt(args,
    std.getopt.config.required,
    "foo|f", &foo,
    "bar|b", &bar);

Требуется только параметр, непосредственно следующий за std.getopt.config.required.

Передача нераспознанных параметров: Если приложение должно выполнить свою обработку аргументов, которые getopt не поняла, оно может передать директиву std.getopt.config.passThrough функции getopt:

bool foo, bar;
getopt(args,
    std.getopt.config.passThrough,
    "foo", &foo,
    "bar", &bar);

Нераспознанный параметр, такой как "--baz", будет найден нетронутым в args после возвращения getopt.

Генерация информации о помощи: Если строка параметра следует за другой строкой, эта строка служит описанием для этого параметра. Функция getopt возвращает структуру типа GetoptResult. Это возвращаемое значение содержит информацию обо всех переданных параметрах, а также флаг bool GetoptResult.helpWanted, указывающий, запрашивалась ли информация об этих параметрах. Функция getopt всегда добавляет параметр для --help|-h для установки флага, если параметр виден в командной строке.

Терминатор параметров: Одиночный двойной дефис завершает сбор getopt. Он используется для разделения параметров программы от других параметров (например, параметров, передаваемых другой программе). Вызов приведенного выше примера с "--foo -- --bar" обрабатывает foo, но оставляет "--bar" в args. Сам двойной дефис удаляется из массива аргументов, за исключением случая, когда указана директива std.getopt.config.keepEndOfOptions.

Примеры:

auto args = ["prog", "--foo", "-b"];

bool foo;
bool bar;
auto rslt = getopt(args, "foo|f", "Some information about foo.", &foo, "bar|b",
    "Some help message about bar.", &bar);

if (rslt.helpWanted)
{
    defaultGetoptPrinter("Some information about the program.",
        rslt.options);
}

перечисление config: int;

Параметры конфигурации для getopt.

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

caseSensitive: Включить регистрозависимость
caseInsensitive: Выключить регистрозависимость (по умолчанию)
bundling: Включить объединение
noBundling: Выключить объединение (по умолчанию)
passThrough: Передать нераспознанные аргументы
noPassThrough: Обработать нераспознанные аргументы как ошибки (по умолчанию)
stopOnFirstNonOption: Остановить обработку по первому аргументу, который не похож на параметр
keepEndOfOptions: Не удалять разделитель endOfOptions из args
required: Сделать следующий параметр обязательным

struct GetoptResult;

Результат функции getopt.

helpWanted устанавливается, если параметр --help или -h был передан в парсер параметров.

bool helpWanted;: Флаг, указывающий, был ли запрошен вывод справки
Option[] options;: Все возможные параметры

struct Option;

Информация о параметре.

string optShort;: Короткое обозначение параметра
string optLong;: Полное обозначение параметра
string help;: Описание параметра
bool required;: Если параметр обязателен, то его отсутствие приведёт к ошибке

dchar optionChar;

Символ параметра (по умолчанию '-').

По умолчанию '-' но может быть задан до вызова getopt.

string endOfOptions;

Строка, которая традиционно обозначает конец всех параметров (по умолчанию '--').

По умолчанию "--" но может быть задана до вызова getopt. Присвоение пустой строки к endOfOptions фактически отключает её.

dchar assignChar;

Символ присваивания, используемый в параметрах с параметрами (по умолчанию '=').

По умолчанию '=' но может быть задан до вызова getopt.

string arraySep;

Когда установлено в "", параметры для массивов и ассоциативных массивов обрабатываются как отдельные аргументы. То есть, только один аргумент добавляется или вставляется при каждом появлении переключателя параметра. Если arraySep установлено на что-то другое, то каждый параметр сначала разделяется разделителем, и отдельные части обрабатываются как аргументы для того же переключателя параметра.

По умолчанию "" но может быть задано до вызова getopt.

void defaultGetoptPrinter(string text, Option[] opt);

Эта функция выводит переданные Option и текст выровненным способом в stdout.

Сначала выводится переданный текст, за ним идёт перевод строки, затем выводится короткое и полное обозначение каждого параметра. Короткое и полное обозначение выравниваются по самому длинному обозначению каждого Option переданного. Если параметр обязателен, то после полного обозначения параметра выводится "Обязательно:". Если есть сообщение справки, оно выводится далее. Формат показан в этом коде:

foreach (it; opt)
{
    writefln("%*s %*s%s%s", lengthOfLongestShortOption, it.optShort,
        lengthOfLongestLongOption, it.optLong,
        it.required ? " Required: " : " ", it.help);
}

Параметры:

string `text`	Текст, выводимый в начале вывода справки.
Option[] `opt`	Полученные `Option` из параметра `getopt`

void defaultGetoptFormatter(Output)(Output output, string text, Option[] opt, string style = "%*s %*s%*s%s\x0a");

Эта функция записывает переданный текст и Option в диапазон вывода описанным способом в документации функции defaultGetoptPrinter, если не используется опция стиля.

Параметры:

Output `output`	Диапазон вывода, используемый для записи информации о справке.
string `text`	Текст, выводимый в начале вывода справки.
Option[] `opt`	Полученные `Option` из параметра `getopt`
string `style`	Способ отображения вывода каждого `Option.`