Autumn Docs

Оформление

autumn-cli ​

Обертка над cli библиотекой, которая предоставляет возможности создания консольных приложений на фреймворке ОСень.

Подключение и пример использования ​

Точка входа в приложение

main.os

bsl
#Использовать autumn
#Использовать autumn-cli
#Использовать "Каталог/С/Классами/Команд"

Поделка = Новый Поделка();
Поделка.ЗапуститьПриложение();

Допустим, мы хотим сделать приложение, которое имеет следующие команды:

plus - Принимает один числовой аргумент и прибавляет к нему 10. Выводит результат в консоль.

hello - Имеет опцию name и выводит в консоль приветствующее сообщение.

date - Имеет две подкоманды, day выводит в консоль начало дня, и month выводит в консоль начало месяца.

Аргументы ​

Подготовим первую команду:

Каталог/С/Классами/Команд/КомандаПлюс.os

bsl
&Аргумент(Имя = "ARG", Описание = "Значение числа") // Определим аргумент и дадим ему описание
&ТЧисло // Укажем тип аргумента
Перем ПереданноеЧисло;

&КомандаПриложения(Имя = "p plus", Описание = "Прибавляет 10 к заданному числу") // Аннотация, обозначающая, что этот класс - консольная команда
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

&ВыполнениеКоманды // Метод, помеченный этой аннотацией, будет выполнен при вызове команды.
Процедура ВывестиРезультатСложения() Экспорт

	Результат = ПереданноеЧисло + 10;

	Сообщить("Результат сложения: " + Результат);
	
КонецПроцедуры

В этом примере мы определили класс как команду консольного приложения с помощью аннотации

&КомандаПриложения(Имя = "p plus", Описание = "Прибавляет 10 к заданному числу")

В которой указали имя команды и ее описание. А для определения аргумента команды была создана переменная с аннотацией

&Аргумент(Имя = "ARG", Описание = "Значение числа")

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

&ВыполнениеКоманды

Опции ​

Команда с опцией

Каталог/С/Классами/Команд/КомандаПривет.os

bsl
&Опция(Имя = "n name", Описание = "Имя пользователя")
Перем ИмяПользователя;

&КомандаПриложения(Имя = "H hello", Описание = "Поздоровается с пользователем")
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

&ВыполнениеКоманды
Процедура ПоприветствоватьПользователя() Экспорт

	ТекстСообщения = "Привет " + ИмяПользователя + "!";

	Сообщить(ТекстСообщения);
	
КонецПроцедуры

В этом примере, для определения опции команды была создана переменная с аннотацией

&Опция(Имя = "n name", Описание = "Имя пользователя")

Подкоманды ​

Теперь определим последнюю команду, которая имеет две подкоманды

Каталог/С/Классами/Команд/КомандаДата.os

bsl
&КомандаПриложения(Имя = "d date", Описание = "Выводит дату")
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

И с помощью аннотации &ПодкомандаПриложения определим эти две подкоманды, указав параметр Родитель — имя класса (или идентификатор) родительской команды

Каталог/С/Классами/Команд/ПодкомандаДень.os

bsl
&ПодкомандаПриложения(Имя = "day", Родитель = "КомандаДата", Описание = "Выводит дату - начало дня")
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

&ВыполнениеКоманды
Процедура СообщитьДень() Экспорт

	Сообщить(НачалоДня(ТекущаяДата()));

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

Каталог/С/Классами/Команд/ПодкомандаМесяц.os

bsl
&ПодкомандаПриложения(Имя = "month", Родитель = "КомандаДата", Описание = "Выводит дату - начало месяца")
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

&ВыполнениеКоманды
Процедура СообщитьМесяц() Экспорт

	Сообщить(НачалоМесяца(ТекущаяДата()));
	
КонецПроцедуры

Параметр Родитель позволяет подкоманде самой указать, к какой команде она относится. Добавление новой подкоманды — это создание одного нового файла без необходимости правки родительской команды.

Вложенные подкоманды ​

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

Каталог/С/Классами/Команд/ПодкомандаФормат.os

bsl
&ПодкомандаПриложения(Имя = "format", Родитель = "ПодкомандаДень", Описание = "Выводит дату в указанном формате")
Процедура ПриСозданииОбъекта()
		
КонецПроцедуры

&ВыполнениеКоманды
Процедура СообщитьФормат() Экспорт

	Сообщить(Формат(НачалоДня(ТекущаяДата()), "ДЛФ=Д"));

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

Наборы опций ​

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

Определим набор опций:

Каталог/С/Классами/Команд/НаборОпцийПодключения.os

bsl
&Опция(Имя = "ibconnection", Описание = "Строка подключения к базе")
&ТСтрока
&ПоУмолчанию("./build/ib")
Перем СтрокаПодключения Экспорт;

&Опция(Имя = "v8version", Описание = "Версия платформы 1С")
&ТСтрока
&ПоУмолчанию("8.3")
Перем ВерсияПлатформы Экспорт;

&НаборОпций
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Аннотация &НаборОпций на конструкторе (без параметров) регистрирует класс как набор опций. Поля набора описываются теми же аннотациями &Опция, &Аргумент, &ПоУмолчанию и т.д., что и в обычных командах.

Теперь подключим набор к команде:

Каталог/С/Классами/Команд/КомандаЗагрузки.os

bsl
&НаборОпций("НаборОпцийПодключения")
Перем ОпцииПодключения;

&Опция(Имя = "f file", Описание = "Путь до *.cf")
&ТСтрока
&ПоУмолчанию("./1cv8.cf")
Перем ПутьКФайлу;

&КомандаПриложения(Имя = "import", Описание = "Загрузка конфигурации из файла")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

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

	Сообщить("Загрузка конфигурации:");
	Сообщить("  Файл: " + ПутьКФайлу);
	Сообщить("  Подключение: " + ОпцииПодключения.СтрокаПодключения);
	Сообщить("  Версия 1С: " + ОпцииПодключения.ВерсияПлатформы);

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

Вызов: myapp date day format

Обратная совместимость ​

Старый способ регистрации подкоманд через перечисление параметра Подкоманда в родительской команде по-прежнему работает:

bsl
&КомандаПриложения(Имя = "d date", 
					Описание = "Выводит дату",
					Подкоманда = "ПодкомандаДень",
					Подкоманда = "ПодкомандаМесяц"
)

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

Аннотация &НаборОпций("НаборОпцийПодключения") на поле команды подключает набор опций по имени класса. При выполнении команды фреймворк автоматически:

  • зарегистрирует все опции и аргументы из набора в CLI
  • заполнит значения из командной строки
  • передаст готовый экземпляр набора в поле команды

Доступ к значениям — через свойства набора: ОпцииПодключения.СтрокаПодключения, ОпцииПодключения.ВерсияПлатформы.

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

Описание параметров аннотаций ​

&КомандаПриложения и &ПодкомандаПриложения имеют одинаковый набор параметров:

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

  • Имя - Имя команды, которое будет в интерфейсе cli.

  • Описание - Текстовое описание, которое будет отображено в cli

  • Подкоманда - Имя желудя подкоманды (Идентификатор или имя класса). параметр повторяемый, т.е. может быть несколько подкоманд. Устаревший способ — рекомендуется использовать параметр Родитель в подкоманде.

  • Родитель - (только для &ПодкомандаПриложения) Имя желудя родительской команды (Идентификатор или имя класса), к которой будет прикреплена подкоманда. Позволяет подкоманде самой указывать своего родителя и поддерживает вложенность любой глубины.

  • ДобавлятьАннотациюЖелудь - Управляет добавлением корневой аннотации "Желудь". По умолчанию - истина. Трогать стоит только в случае, если вы знаете, что делаете, при работе с мета-аннотациями над командами приложения.

Типы аргументов и опций ​

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

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

Дополнительные аннотации аргументов и опций ​

&ВОкружении("ИМЯ_ПЕРЕМЕННОЙ_ОКРУЖЕНИЯ") - Получать значение из переменной окружения.

&Флаговый - Определяет тип значения - булево, аналогично &ТБулево

&Флаг - Определяет тип значения - булево, аналогично &ТБулево

&СкрытьВСправке - Отключает отображение в справке.

&ПоУмолчанию("Некое_дефолтное_значение") - Значение по умолчанию, которое будет присвоено.

&Псевдоним - Дополнительное имя параметра.

&Описание - Описание параметра.

&Обязательный - Вызывает ошибку, если параметр не передан.

&ПодробноеОписание - Подробное описание.

&Перечисление - Элемент перечисления с параметрами:

  • Имя- Имя элемента
  • Значение- Значение элемента
  • Описание- Описание для справки

Настройка версии и имени приложения. ​

Настройку вывода версии и имени приложения можно осуществить двумя способами.

  1. Создать рядом с точкой входа или в каталоге проекта файл

autumn-properties.json

json
{
    "cli": {
        "ИмяПриложения": "cli_test",
        "ПолноеИмяПриложения": "cli_test v%{cli.ВерсияПриложения}",
        "ВерсияПриложения": "1.0.1"
    }
}
  1. В каталог с командами, которые будут загружены в контекст осени, добавить желудь с определенным интерфейсом

Каталог/С/Классами/Команд/ДемоОписаниеПриложения.os

bsl
&Желудь("ОписаниеКонсольногоПриложения")
&Верховный
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Функция ИмяПриложения() Экспорт
	Возврат "demo-cli";
КонецФункции

Функция ПолноеИмяПриложения() Экспорт
	Возврат "Демонстрационное консольное приложение";
КонецФункции

Функция ВерсияПриложения() Экспорт
	Возврат "1.0";
КонецФункции

Миграция с cli ​

Инфраструктурный, условный main.os от вашего приложения не нужен. он должен быть запущен при помощи ОСени. Дальше перед вами три пути:

Первый - команды модифицировать аннотациями конструктора &КомандаПриложения или &ПодкомандаПриложения, оставить методы ОписаниеКоманды и ВыполнитьКоманду, тогда фреймворк поймёт, что они уже реализованы, и не будет генерировать для них код.

Второй - команды модифицировать аннотациями конструктора &КомандаПриложения или &ПодкомандаПриложения, убрать методы ОписаниеКоманды и ВыполнитьКоманду, и создать поля класса, с необходимыми аннотациями, и метод с аннотацией &ВыполнениеКоманды. В таком случае фреймворк сгенерит все остальное за вас.

Третий - Команды оставить без изменений, но создать класс - дуб, который превратит ваши команды в желуди. Для понимания, приведу пример, как можно "ожелудить" небольшую команду:

Каталог/С/Классами/Команд/МояЛегасиКоманда.os

bsl
Перем ИмяПользователя;

Процедура ПриСозданииОбъекта()
КонецПроцедуры

Процедура ОписаниеКоманды(Знач КомандаПриложения) Экспорт
	
	КомандаПриложения.Опция("n name", "", "Имя пользователя");

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

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

	Сообщить("Привет " + ИмяПользователя);

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

Теперь создадим дуб, в котором можно ожелудить все необходимые классы:

Каталог/С/Классами/Команд/ДубЛегасиКоманды.os

bsl
&Дуб
Процедура ПриСозданииОбъекета()
КонецПроцедуры

&Завязь
&КомандаПриложения(Имя = "legacy", Описание = "Легаси команда, которая работает через дуб")
Функция МояЛегасиКоманда() Экспорт
  Возврат Новый МояЛегасиКоманда();
КонецФункции

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

Больше примеров ​

Описанные классы можно посмотреть в каталоге example и еще больше примеров команд в каталоге tests