san40_u5an40.Arguments 1.1.10

san40_u5an40.Arguments

Назначение

Библиотека для упрощения проверки аргументов командой строки.

Оглавление:

• Пример использования
• Принцип работы
  • Режимы
  • Типы обязательных аргументов
  • Работа с опциональными аргументами
  • Переопределение сообщений об ошибках
  • Работа с результатом проверки аргументов
  • Типы в Error.Type
  • Exceptions

Пример использования

var buildResult = new ArgumentsBuilder(args)
    .AddDirectory()
    .AddFile()
    .AddNumber(1, 3)
    .AddStringValue()
    .AddCustom(p => p.Contains("45"), "В выражении '{0}' отсутствует '45'")
    .Build();

if (!buildResult.IsValid)
{
    Console.WriteLine(
        $"В аргументах допущена ошибка: \"{buildResult.Error}\". " +
        "Чтобы ознакомиться со справочными сведеньями, введите \"app /s\".");
    return;
}

var arguments = buildResult.Value;
DoSomething(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);

Принцип работы

Режимы

Билдер работает в двух режимах:

• Одиночный режим для простых сценариев (был показан в примере использования).
• Режим секций/команд.

При одиночном режиме программа поддерживает только один набор аргументов: "{файл} {директория} {произвольная строка}". Возможности указывать разные команды или секции нет.

В режиме секций можно создать разные наборы параметров:

• "--rm {файл}".
• "--touch {файл}".
• "--ls".
• И т.д.

Собственно первые аргументы в этом перечне и есть так называемые секции. В качестве них можно использовать и команды, которые поддерживает ваше приложение. Наличие двух минусов не является обязательным, такой вид был взят лишь для примера.

Чтобы создать секцию, необходимо вызвать метод AddSection, указав название в параметре. Для составления же сценариев необходимо обращаться к секции по индексатору. Пример:

var argumentsBuilder = new ArgumentsBuilder(args)
    .AddSection("-sort")
    .AddSection("-stat");

argumentsBuilder["-sort"]
    .AddNumber(1, 6);

argumentsBuilder["-stat"]
    .AddCustom(p => p.Contains("556"), "Не гудный аргумент так то");

var buildResult = argumentsBuilder.Build();

if (!buildResult.IsValid)
{
    Console.WriteLine(buildResult.Error);
    return;
}

var arguments = buildResult.Value;

switch (arguments.Section)
{
    case "-sort":
        DoSomething(arguments[0]);
        break;

    case "-stat":
        DoSomething(arguments[0]);
        break;
}

Типы обязательных аргументов

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

Перечень обязательных аргументов представлен в этой таблице:

Работа с опциональными аргументами

Опциональные аргументы не обязательны для ввода пользователем, однако при неверной попытке их ввести будет всё же возвращено сообщение об ошибке.

Пример использования:

var buildResult = new ArgumentsBuilder(args)
    .AddNumber(1900, DateTime.Now.Year)        // Обязательный
    .AddOptional("/rm")                        // Опциональный, как и следующий
    .AddOptionalPair("/n", p => p.Length >= 2, "Указанное имя слишком короткое, необходимо ввести не менее двух символов") // Подойдут: {"/n": "Василий"}, {"/n", "Ян"} и т.п.
    .Build();

if (!buildResult.IsValid)
{
    Console.WriteLine(buildResult.Error);
    return;
}

var arguments = buildResult.Value;
        
DoSomething_1(arguments[0]);

if (arguments.ContainsPair("/n", out string? name))
    DoSomething_2(name!);

if (arguments.Contains("/rm"))
    DoSomething_3();

Как уже понятно, опциональные аргументы отдельно проверяются с помощью методов Contains и ContainsPair. Первый метод проверки принимает только паттерн, который был добавлен в билдер, второй помимо паттерна принимает и out-параметр, в который будет записано значение пары.

Важно! Проверка опциональных аргументов не допустима, если они не были добавлены в билдер с помощью методов AddOptional и AddOptionalPair. Также опциональные аргументы допустимо располагать только после обязательных.

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

Переопределение сообщений об ошибках

Каждый метод для добавления обязательных аргументов поддерживает переопределение сообщения об ошибке. Они принимают необязательный параметр errorMessage, кроме метода AddCustom, где указание сообщения об ошибке является обязательным.

Стандартные сообщения об ошибках в аргументах:

• StringValue и StringPattern — "Отсутствует необходимое строковое значение".
• Number — "'{0}' не является числом, либо не входит в допустимый числовой диапазон".
• Directory — "Директории '{0}' не существует".
• File — "Файла '{0}' не существует".

Как уже стало понятно, сообщения об ошибках поддерживают интернирование с помощью подстроки {0}.

Работа с результатом проверки аргументов

После вызова ArgumentsBuilder.Build() возвращается ResultArguments, который имеет следующие свойства:

• IsValid — Возвращает bool-значение, показывающее валидные ли ввёл аргументы пользователь. Важно! Если IsValid == false, то обращение к свойству Value приведёт к выбросу InvalidOperationException, как и обращение к Error при IsValid == true.
• Error — Информация об ошибках, допущенных при вводе аргументов. Представлена объектом FailureArguments:
  • Message — Сообщение об ошибке (можно не указывать явно Error.Message, т.к. FailureArguments переопределяет метод ToString, возвращающий это строковое значение).
  • Type — Тип ошибки (будут рассмотрены в следующем параграфе).
• Value — Информация об аргументах, если они пошли проверку на валидность. Представлена объектом SuccessArguments:
  • Section — Возвращает секцию в формате string, которую ввёл пользователь.
  • this[int index] — Обращение к аргументам, указанным пользователем, через индекс. Важно! Индексация начинается с 0. Секция, которая указывается 1-ым аргументом, не учитывается индексатором. Обращение к несуществующему индексу (не был добавлен обязательный аргумент) приведёт к ArgumentOutOfRangeException.
  • Contains — Проверяет наличие опционального аргумента.
  • ContainsPair — Проверяет наличие опциональной пары аргументов. Первым параметром указывается паттерн, вторым out-параметром указывается nullable-строка, хранящая результат введённого пользователем значения.

Со всеми этими свойствами вы уже знакомы из предыдущих примеров, здесь просто собран их полный перечень и изложены важные уточнения.

Типы в Error.Type

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

Exceptions

Большая часть определённых в этой библиотеке исключений проявит себя на этапе компиляции. Как правило они относятся к блокам Важно и необходимы для устранения неоднозначности в проектировании обработчика аргументов.

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

• Обращение к несуществующему индексу (см. подробнее информацию об индексаторе в соответствующем параграфе).
• Обращение к свойству Error при валидном результате (при дизайне, показанном в примерах, такого исключения не будет).
• Обращение к свойству Value при валидном (соответственно).