Command Line Interface для OScript

Короткое название библиотеки cli

Данная библиотека для языка OScript позволяет создавать консольные приложения с разбором и проверкой аргументов.

Документация и описание публичного API

Быстрый старт

Пример простого приложения

#Использовать cli

Перем Лог;

///////////////////////////////////////////////////////////////////////////////

Процедура ВыполнитьПриложение()

    Приложение = Новый КонсольноеПриложение(ПараметрыПриложения.ИмяПриложения(), "Помощник генерации приложения на основании шаблона cli");
    Приложение.Версия("v version", ПараметрыПриложения.Версия());

    Приложение.УстановитьОсновноеДействие(ЭтотОбъект)
    Приложение.Запустить(АргументыКоманднойСтроки);

КонецПроцедуры

Процедура ВыполнитьКоманду(Знач Команда) Экспорт

    Сообщить("Полезная работа");

КонецПроцедуры

///////////////////////////////////////////////////////


Попытка

    ВыполнитьПриложение();

Исключение

    Сообщить(ОписаниеОшибки());

КонецПопытки;

Пример приложения с несколькими командами

#Использовать cli

///////////////////////////////////////////////////////////////////////////////

Процедура ВыполнитьПриложение()

    Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli", ЭтотОбъект);
    Приложение.Версия("v version","1.0.0");

    Приложение.ДобавитьКоманду("i init", "Инициализация структуры нового приложения", Новый КомандаInit);
    Приложение.ДобавитьКоманду("g generate", "Генерация элементов структуры приложения", Новый КомандаGenerate);

    Приложение.Запустить(АргументыКоманднойСтроки);

КонецПроцедуры

Процедура ВыполнитьКоманду(Знач КомандаПриложения) Экспорт
    КомандаПриложения.ВывестиСправку();
КонецПроцедуры

///////////////////////////////////////////////////////

Попытка

    ВыполнитьПриложение();

Исключение

    Сообщить(ОписаниеОшибки());

КонецПопытки;

Пример приложения с вложенными командами

#Использовать cli

///////////////////////////////////////////////////////////////////////////////

Процедура ВыполнитьПриложение()

    Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli");
    Приложение.Версия("v version","1.0.0");

    Приложение.ДобавитьКоманду("i init", "Инициализация структуры нового приложения", Новый КомандаInit);
    Приложение.ДобавитьКоманду("g generate", "Генерация элементов структуры приложения", Новый КомандаGenerate);

    Приложение.Запустить(АргументыКоманднойСтроки);

КонецПроцедуры

///////////////////////////////////////////////////////

Попытка

    ВыполнитьПриложение();

Исключение

    Сообщить(ОписаниеОшибки());

КонецПопытки;

Класс КомандаGenerate Для добавления подкоманды в любую команду используются методы ДобавитьПодкоманду или ДобавитьКоманду

Процедура ОписаниеКоманды(Команда) Экспорт

    // Метод <ДобавитьПодкоманду>
    Команда.ДобавитьПодкоманду("c command", "Генерация дополнительной вложенной команды", Новый КомандаGenerateCommand);
    
    // Метод <ДобавитьКоманду>
    Команда.ДобавитьКоманду("o option", "Генерация опции для команды", Новый КомандаGeneratOption);

Процедура ВыполнитьКоманду(Знач Команда) Экспорт

КонецПроцедуры

Мотивация

Для PR в cmdline слишком большие изменения в API, т.е. обеспечить совместимость очень трудоемко. Сравнительная таблица возможностей:

| | cli | cmdline | |-----------------------------------------------------------------------------------|------|---------| | Встроенная команда help | ✓ | ✓ | | Автоматическая генерация справки по приложению и командам | ✓ | ✓ | | Встроенная команда version | ✓ | ✓ | | Команды | ✓ | ✓ | | Подкоманды | ✓ | | | Совмещение булевых (флаговых) опций -xyz | ✓ | | | Совмещение опции и значения -fValue | ✓ | | | Взаимоисключающие опции: --start ❘ --stop | ✓ | | | Необязательные опции : [-a -b] or [-a [-b]] | ✓ | | | Проверка аргументов : FILE PATH | ✓ | | | Необязательные аргументы : SRC [DST] | ✓ | | | Повторение аргументов : SRC... DST | ✓ | | | Зависимость опций и аргументов друг от друга : SRC [-f DST] | ✓ | | | Формирование своей строки выполнения: [-d ❘ --rm] FILE [КОМАНДА [АРГУМЕНТЫ...]] | ✓ | |

Установка

Для установки необходимо:

• Скачать файл cli.ospx из раздела releases
• Воспользоваться командой:

$ opm install -f <ПутьКФайлу>

Либо скачать библиотеку с помощью opm:

opm install cli

Базовые принципы

При создании приложения необходимо указать имя приложения и описание:

Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli");

Каждый возможный вариант выполнения - это "Команда". Команды могут создаваться явно, кроме того, само Приложение содержит в себе корневую (Основную) команду.

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

Процедура ВыполнитьКоманду(Знач Команда) Экспорт
КонецПроцедуры

Для установки основной функции выполнения приложения в приложении надо установить основное действие. В простейшем случае основным действием может выступать сам стартовый сценарий:

Передать данный класс через процедуру:

Приложение.УстановитьОсновноеДействие(ЭтотОбъект)

Встроенная команда "Версия"

Для добавления отображения версии через опции: -v, --version надо добавить строчку:

Приложение.Версия("v version", "1.2.3");

Это позволит запускать приложение с ключом v или --version:

my-app --version

Запуск парсера аргументов и приложения в целом

Для запуска приложения необходимо добавить строчку:

Приложение.Запустить(АргументыКоманднойСтроки);

Этот вызов является "точкой входа" в консольное приложение. В общем случае после него уже не идет никакого дополнительного кода. Парсер анализирует аргументы и запускает команды автоматически.

Параметры команд/приложения

Все параметры разделяются на два типа:

• Опция
• Аргумент

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

Опция

Опция может быть следующих простых типов:

• Булево
• Строка
• Число
• Дата

Также опция может принимать массивы данных типов, например:

• МассивЧисел
• МассивСтрок
• МассивДат
• МассивБулево
• Перечисление

Для простых типов поддерживается определение типа значения по умолчанию. Пример:

Отладка = Команда.Опция("f force", ,"Описание опция")
    .ТБулево() // тип опции Булево
    ;
// Можно заменить на вызов

Отладка = Команда.Опция("f force", Ложь ,"Описание опция");

Пример булево опции:

Отладка = Команда.Опция("v debug", ложь ,"Описание опции")
    .Флаговый() // тип опции булево
    .ВОкружении("ИМЯ_ПЕРЕМЕННОЙ")
    .ПоУмолчанию(Ложь)
    .СкрытьВСправке(); // Любой тип

ВОкружении Возможна передача нескольких переменных окружения, разделенных через пробел

Пример перечисления опции:

ЦветКонсоли = Команда.Опция("c color", "green" ,"Описание опции")
    .ТПеречисление() // тип опции перечисление
    .Перечисление("green", Новый ЗеленыйЦвет(), "Консоль будет зеленого цвета")
    .Перечисление("red", Цвета.Красный, "Консоль будет красного цвета")
    .Перечисление("Случайный", СлучайныйЦвет(), "Консоль будет случайного цвета")
    ;

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

Подробное описание возможностей параметров команд и приложения

Пример синтаксиса опций

Для типа булево:

• -f : одно тире для коротких имен
• -f=false : одно тире для коротких имен и значение булево (true/false)
• --force : двойное тире для длинных имен
• -it : группировка булевых опций, будет эквивалентно: -i -t

Для типа строка, число, дата, длительность:

• -e=value : одно тире для коротких имен, через равно значение опции
• -e value : одно тире для коротких имен, через пробел значение опции
• -Ivalue : одно тире для коротких имен, и сразу значение опции
• --extra=value : двойное тире для длинных имен, через равно значение опции
• --extra value : двойное тире для длинных и