1
0
mirror of https://github.com/alei1180/curlone.git synced 2025-11-23 22:45:05 +02:00
Files
curlone/lib/cli/docs/readme.md

893 lines
40 KiB
Markdown
Raw Normal View History

Описание публичного интерфейса библиотеки
========================
<!-- TOC -->
- [Класс КонсольноеПриложение:](#класс-консольноеприложение)
- [Публичные свойства](#публичные-свойства)
- [ФлагВерсия](#флагверсия)
- [ВерсияПриложения](#версияприложения)
- [Версия](#версия)
- [УстановитьСпек](#установитьспек)
- [ПолучитьКоманду](#получитькоманду)
- [Запустить](#запустить)
- [ДобавитьКоманду](#добавитькоманду)
- [УстановитьОсновноеДействие](#установитьосновноедействие)
- [УстановитьДействиеПередВыполнением](#установитьдействиепередвыполнением)
- [УстановитьДействиеПослеВыполнения](#установитьдействиепослевыполнения)
- [Опция](#опция)
- [Аргумент](#аргумент)
- [ВыполнитьКоманду](#выполнитькоманду)
- [Класс КомандаПриложения:](#класс-командаприложения)
- [Публичные свойства](#публичные-свойства-1)
- [Спек](#спек)
- [ПодробноеОписание](#подробноеописание)
- [Приложение](#приложение)
- [КомандыРодители](#командыродители)
- [ДобавитьПодкоманду](#добавитьподкоманду)
- [ПолучитьПодкоманды](#получитьподкоманды)
- [ПолучитьИмяКоманды](#получитьимякоманды)
- [ПолучитьСинонимы](#получитьсинонимы)
- [ПолучитьОписание](#получитьописание)
- [ЗначениеОпции](#значениеопции)
- [ЗначениеАргумента](#значениеаргумента)
- [ПараметрыКоманды](#параметрыкоманды)
- [ПередВыполнениемКоманды](#передвыполнениемкоманды)
- [ПослеВыполненияКоманды](#послевыполнениякоманды)
- [ВывестиСправку](#вывестисправку)
- [Запуск](#запуск)
- [НачалоЗапуска](#началозапуска)
- [ЭтоСинонимКоманды](#этосинонимкоманды)
- [Опция](#опция-1)
- [Аргумент](#аргумент-1)
- [УстановитьДействиеВыполнения](#установитьдействиевыполнения)
- [УстановитьДействиеПередВыполнением](#установитьдействиепередвыполнением-1)
- [УстановитьДействиеПослеВыполнения](#установитьдействиепослевыполнения-1)
- [Класс ПараметрКоманды:](#класс-параметркоманды)
- [Публичные свойства](#публичные-свойства-2)
- [Имя](#имя)
- [Описание](#описание)
- [ПодробноеОписание](#подробноеописание-1)
- [ПеременнаяОкружения](#переменнаяокружения)
- [Синонимы](#синонимы)
- [НаименованияПараметров](#наименованияпараметров)
- [СкрытьЗначение](#скрытьзначение)
- [УстановленаИзПеременнойОкружения](#установленаизпеременнойокружения)
- [УстановленаПользователем](#установленапользователем)
- [ТребоватьУстановкиПользователем](#требоватьустановкипользователем)
- [Значение](#значение)
- [ТипОпции](#типопции)
- [ЭтоМассив](#этомассив)
- [Очистить](#очистить)
- [ЗначениеВСтроку](#значениевстроку)
- [ПолучитьОбязательностьВвода](#получитьобязательностьввода)
- [УстановитьЗначение](#установитьзначение)
- [ИзПеременнойОкружения](#изпеременнойокружения)
- [Текучие функции](#текучие-функции)
- [ВОкружении](#вокружении)
- [СкрытьВСправке](#скрытьвсправке)
- [ПоУмолчанию](#поумолчанию)
- [Флаговый](#флаговый)
- [Флаг](#флаг)
- [ТБулево](#тбулево)
- [ТДата](#тдата)
- [ТЧисло](#тчисло)
- [ТСтрока](#тстрока)
- [ТМассивДат](#тмассивдат)
- [ТМассивЧисел](#тмассивчисел)
- [ТМассивСтрок](#тмассивстрок)
- [ТМассивБулево](#тмассивбулево)
- [ТПеречисление](#тперечисление)
- [Перечисление](#перечисление)
- [Описание](#описание-1)
- [ПодробноеОписание](#подробноеописание-2)
- [Псевдоним](#псевдоним)
- [Обязательный](#обязательный)
- [ВФайле](#вфайле)
- [ПроизвольныйТип](#произвольныйтип)
<!-- /TOC -->
### Класс КонсольноеПриложение:
> Основной класс для реализации консольного приложения
#### Публичные свойства
##### ФлагВерсия
```bsl
// Класс ПараметрКоманды, для доступа к установленному значению из вне
```
##### ВерсияПриложения
```bsl
// Строковое представление версии приложения
```
#### Версия
```bsl
// Процедура добавляет версию приложения,
// при вызове данной опции, показывается установленная версия и
// завершается выполнение с кодом (0)
//
// Параметры:
// Наименование - строка - имя опции, в строке допустимо задавать синоним через пробел, например "v version"
// СтрокаВерсии - строка - версия, приложения
```
#### УстановитьСпек
```bsl
// Процедура позволяет переопределить стандартную строку использования приложения
//
// Параметры:
// СтрокаСпек - строка - переопределенная строка использования приложения
```
#### ПолучитьКоманду
```bsl
// Возвращает основную команду приложения
//
// Возвращаемое значение:
// Команда - класс КомандаПриложения
```
#### Запустить
```bsl
// Основная процедура запуска приложения
//
// Параметры:
// АргументыКоманднойСтрокиВходящие - Массив - Элементы <Строка>, необзательный,
// Если, не передано считывает из АргументыКоманднойСтроки
```
#### ДобавитьКоманду
```bsl
// Функция добавляет команду приложение и возвращает экземпляр данной команды
//
// Параметры:
// ИмяКоманды - строка - в строке допустимо задавать синоним через пробел, например "exec e"
// ОписаниеКоманды - строка - описание команды для справки
// КлассРеализацииКоманды - объект - класс, объект реализующий функции выполнения команды.
// Так же используется, для автоматической настройки опций и параметров команды
//
// Возвращаемое значение:
// Команда - класс КомандаПриложения
```
#### УстановитьОсновноеДействие
```bsl
// Процедура устанавливает процедуру "ВыполнитьКоманду" выполнения для приложения
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ВыполнитьКоманду"
//
```
#### УстановитьДействиеПередВыполнением
```bsl
// Процедура устанавливает процедуру "ПередВыполнениемКоманды" выполнения для приложения
// запускаемую перед выполнением "ВыполнитьКоманду"
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ПередВыполнениемКоманды"
//
```
#### УстановитьДействиеПослеВыполнения
```bsl
// Процедура устанавливает процедуру "ПослеВыполненияКоманды" выполнения для приложения
// запускаемую после выполнением "ВыполнитьКоманду"
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ПослеВыполненияКоманды"
//
```
#### Опция
```bsl
// Функция добавляет опцию приложения и возвращает экземпляр данной опции
//
// Параметры:
// Имя - строка - имя опции, в строке допустимо задавать синоним через пробел, например "s some-opt"
// Значение - строка - значение опции по умолчанию
// Описание - объект - описание опции для справки.
//
// Возвращаемое значение:
// Команда - класс ПараметрКоманды
//
// Дополнительно смотри справку по классу ПараметрКоманды
```
#### Аргумент
```bsl
// Функция добавляет аргумент приложения и возвращает экземпляр данной аргумента
//
// Параметры:
// Имя - строка - имя аргумента, в строке допустимо использование только из БОЛЬШИХ латинских букв, например "ARG"
// Значение - строка - значение аргумента по умолчанию
// Описание - объект - описание аргумента для справки.
//
// Возвращаемое значение:
// Команда - класс ПараметрКоманды
//
// Дополнительно смотри справку по классу ПараметрКоманды
//
```
#### ВыполнитьКоманду
```bsl
// Предопределенная процедура выполнения приложения, если не задана процедура в классе.
// Выводит справку, по работе с приложением и завершает работу с кодом "1"
// Переопределяется, процедурой "УстановитьОсновноеДействие"
//
// Параметры:
// Команда - класс КомандаПриложения - инстанс класс, для доступа к опция и аргументам выполняемой команды
//
```
### Класс КомандаПриложения:
> Основной класс для реализации консольного приложения
#### Публичные свойства
##### Спек
```bsl
// Пользовательская строка использования текущей команды
```
##### ПодробноеОписание
```bsl
// (ЗАГОТОВКА) Содержит дополнительно подробное описания для справки по команде
```
##### Приложение
```bsl
// Содержит экземпляр класс КонсольноеПриложения, для возможности получения экспортных свойств приложения
```
##### КомандыРодители
```bsl
// Содержит входящий массив родителей текущей команды
// Устанавливается при выполнении команд родителей
```
#### ДобавитьПодкоманду
```bsl
// Функция добавляет под команду в текущую и возвращает экземпляр данной команды
//
// Параметры:
// ИмяКоманды - строка - в строке допустимо задавать синоним через пробел, например "exec e"
// ОписаниеКоманды - строка - описание команды для справки
// КлассРеализацииКоманды - объект - класс, объект реализующий функции выполнения команды.
// Так же используется, для автоматической настройки опций и параметров команды
//
// Возвращаемое значение:
// Команда - класс КомандаПриложения
```
#### ПолучитьПодкоманды
```bsl
// Функция массив вложенных команд, текущей команды
//
// Возвращаемое значение:
// массив, элементы класс КомандаПриложения
```
#### ПолучитьИмяКоманды
```bsl
// Функция возвращает текущее имя команды
//
// Возвращаемое значение:
// строка
```
#### ПолучитьСинонимы
```bsl
// Функция массив синонимов команды
//
// Возвращаемое значение:
// массив, элементы класс КомандаПриложения
```
#### ПолучитьОписание
```bsl
// Функция возвращает описание команды
//
// Возвращаемое значение:
// строка
```
#### ЗначениеОпции
```bsl
// Функция возвращает значение опции по переданному имени/синониму опции
//
// Параметры:
// ИмяОпции - строка - имя или синоним опции
//
// Возвращаемое значение:
// Произвольный - Значение - полученное значение в результате чтения строки использования или переменных окружения
```
#### ЗначениеАргумента
```bsl
// Функция возвращает значение аргумента по переданному имени аргумента
//
// Параметры:
// ИмяАргумента - строка - имя аргумента
//
// Возвращаемое значение:
// Произвольный - Значение - полученное значение в результате чтения строки использования или переменных окружения
```
#### ПараметрыКоманды
```bsl
// Функция возвращает все параметры команды, для доступа к ним по синонимам
//
// Возвращаемое значение:
// Соответствие
// Ключ - имя или синоним опции/аргумента команды
// Значение - полученное значение в результате чтения строки использования или переменных окружения
```
#### ПередВыполнениемКоманды
```bsl
// Предопределенная процедура ПередВыполнениемКоманды команды, если не задана процедура в классе.
// Содержит код определение необходимости вывода версии приложения
```
#### ПослеВыполненияКоманды
```bsl
// Предопределенная процедура ПослеВыполненияКоманды команды, если не задана процедура в классе.
```
#### ВывестиСправку
```bsl
Процедура выводит справку по команде в консоль
```
#### Запуск
```bsl
// Основная процедура запуска команды приложения
//
// Параметры:
// АргументыCLI - Массив - Элементы <Строка>
//
```
#### НачалоЗапуска
```bsl
// Процедура подготавливает команды к запуску
// Формирует строку использования и
// настраивает парсер для выполнения парсинга входящих параметров
// Обязательно вызывается пред выполнением команды
```
#### ЭтоСинонимКоманды
```bsl
// Функция проверяет строку, что она является ли синонимом текущей команды
//
// Параметры:
// СтрокаПроверки - строка - имя команды, для проверки
//
// Возвращаемое значение:
// булево - истина. если это синоним или имя текущей команды, иначе ложь
```
#### Опция
```bsl
// Функция добавляет опцию команды и возвращает экземпляр данной опции
//
// Параметры:
// Имя - строка - имя опции, в строке допустимо задавать синоним через пробел, например "s some-opt"
// Значение - строка - значение опции по умолчанию
// Описание - объект - описание опции для справки.
//
// Возвращаемое значение:
// Команда - класс ПараметрКоманды
//
// Дополнительно смотри справку по классу ПараметрКоманды
```
#### Аргумент
```bsl
// Функция добавляет аргумент команды и возвращает экземпляр данной аргумента
//
// Параметры:
// Имя - строка - имя аргумента, в строке допустимо использование только из БОЛЬШИХ латинских букв, например "ARG"
// Значение - строка - значение аргумента по умолчанию
// Описание - объект - описание аргумента для справки.
//
// Возвращаемое значение:
// Команда - класс ПараметрКоманды
//
// Дополнительно смотри справку по классу ПараметрКоманды
```
#### УстановитьДействиеВыполнения
```bsl
// Процедура устанавливает процедуру "ВыполнитьКоманду" выполнения для команды
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ВыполнитьКоманду"
//
```
#### УстановитьДействиеПередВыполнением
```bsl
// Процедура устанавливает процедуру "ПередВыполнениемКоманды" выполнения для команды
// запускаемую перед выполнением "ВыполнитьКоманду"
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ПередВыполнениемКоманды"
//
```
#### УстановитьДействиеПослеВыполнения
```bsl
// Процедура устанавливает процедуру "ПослеВыполненияКоманды" выполнения для команды
// запускаемую после выполнением "ВыполнитьКоманду"
//
// Параметры:
// КлассРеализации - объект - класс, объект реализующий процедуру выполнения команды.
// ИмяПроцедуры - строка - имя процедуры, отличное от стандартного "ПослеВыполненияКоманды"
//
```
### Класс ПараметрКоманды:
> Основной класс для реализации параметров команды опции или аргумента
#### Публичные свойства
##### Имя
```bsl
// Имя параметра команды
// первая строка из массива строк, переданных при создании
```
##### Описание
```bsl
// Описание параметра команды
// Используется при выводе справки
```
##### ПодробноеОписание
```bsl
// Подробное описание параметра команды
// Используется при выводе справки (запланировано)
```
##### ПеременнаяОкружения
```bsl
// Содержит имя переменной окружения, откуда получать значение
// допустимо использование нескольких переменных окружения через пробел
// Используется при выводе справки
```
##### Синонимы
```bsl
// Содержит синонимов параметра команды
```
##### НаименованияПараметров
```bsl
// Содержит нормализованные наименования параметров
// для опций ("f force"):
// "-f", "--force"
// для аргументов ("ARG"):
// "ARG"
```
##### СкрытьЗначение
```bsl
// Определяет необходимость показа значения по умолчанию параметра в справке.
// Значение "Истина" скрывает в справке, по умолчанию "Ложь"
```
##### УстановленаИзПеременнойОкружения
```bsl
// Содержит признак истина, если значение получено из переменной окружения
```
##### УстановленаПользователем
```bsl
// Содержит признак истина, если значение установлено пользователем в строке использования
```
##### ТребоватьУстановкиПользователем
```bsl
// Признак обязательности установки значения пользователем в строке использования
// при "истина", если значение не передано явно, будет вызывать исключение
```
##### Значение
```bsl
// Содержит значение параметра
// В том числе установленное значение по умолчанию
```
##### ТипОпции
```bsl
// Содержит тип параметра
```
#### ЭтоМассив
```bsl
// Возвращает истина, если тип параметра Массив
//
// Возвращаемое значение:
// булево
```
#### Очистить
```bsl
// Процедура очищает, Значение параметра, для типа Массив
//
```
#### ЗначениеВСтроку
```bsl
// Возвращает строковое представление значения параметра
//
// Возвращаемое значение:
// строка
```
#### ПолучитьОбязательностьВвода
```bsl
// Возвращает истина, если данный параметр обязателен для указания
//
// Возвращаемое значение:
// булево
```
#### УстановитьЗначение
```bsl
// Процедура устанавливает значение параметра из входящего значения
// приводить к необходимому типу
//
// Параметры:
// ВходящееЗначение - строка - полученная строка при парсинге строки использования
```
#### ИзПеременнойОкружения
```bsl
// Процедура устанавливает значение параметра из переменной окружения
//
```
#### Текучие функции
##### ВОкружении
```bsl
// Функция устанавливает переменную окружения для параметра команды
// возвращает текущий параметр команды
//
// Параметры:
// СтрокаПеременнаяОкружения - строка - имя переменной окружения, откуда получать значение
// допустимо использование нескольких переменных окружения через пробел
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### СкрытьВСправке
```bsl
// Функция устанавливает признак скрытости значения по умолчанию в справке
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ПоУмолчанию
```bsl
// Функция устанавливает значение по умолчанию
// возвращает текущий параметр команды
//
// Параметры:
// ВходящееЗначение - произвольный - значение параметра по умолчанию
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### Флаговый
```bsl
// Функция устанавливает тип параметра "Булево"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### Флаг
```bsl
// Функция устанавливает тип параметра "Булево"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### ТБулево
```bsl
// Функция устанавливает тип параметра "Булево"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### ТДата
```bsl
// Функция устанавливает тип параметра "Дата"
// возвращает текущий параметр команды
//
// Параметры:
// ФорматДаты - Строка - формат даты, при приведении к дате из строки параметра по умолчанию (yyyy-MM-dd_HH:mm:ss)
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### ТЧисло
```bsl
// Функция устанавливает тип параметра "Число"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### ТСтрока
```bsl
// Функция устанавливает тип параметра "Строка"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### ТМассивДат
```bsl
// Функция устанавливает тип параметра "Массив" элементы "Дата"
// возвращает текущий параметр команды
//
// Параметры:
// ФорматДаты - Строка - формат даты, при приведении к дате из строки параметра по умолчанию (yyyy-MM-dd_HH:mm:ss)
// ВходящийРазделительМассива - символ - используется для разделения параметров при парсинге строки
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ТМассивЧисел
```bsl
// Функция устанавливает тип параметра "Массив" элементы "Число"
// возвращает текущий параметр команды
//
// Параметры:
// ВходящийРазделительМассива - символ - используется для разделения параметров при парсинге строки
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ТМассивСтрок
```bsl
// Функция устанавливает тип параметра "Массив" элементы "Строки"
// возвращает текущий параметр команды
//
// Параметры:
// ВходящийРазделительМассива - символ - используется для разделения параметров при парсинге строки
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ТМассивБулево
```bsl
// Функция устанавливает тип параметра "Массив" элементы "Булево"
// возвращает текущий параметр команды
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ТПеречисление
```bsl
// Функция устанавливает тип параметра "Перечисление"
// возвращает текущий параметр команды
//
// Параметры:
// ДоступныеПеречисления - Соответсвие
// Ключ - Строка
// Значение - Структура ("Наименование, Значение, ДополнительнаяСправка")
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
// Вызов необязателен, автоматически определяется при создании параметра,
// если передано значение по умолчанию
```
##### Перечисление
```bsl
// Функция устанавливает произвольный тип параметра
// возвращает текущий параметр команды
//
// Параметры:
// НаименованиеПеречисления - строка - пользовательное значение перечисления
// ЗначениеПеречисления - произвольный - системное значение перечисления
// ДополнительнаяСправкаПеречисления - строка - дополнительная строка для справки
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
//
```
##### Описание
```bsl
// Функция устанавливает описание параметра для справки
// возвращает текущий параметр команды
//
// Параметры:
// НовыеОписание - строка - строка с новым описанием, отличным от переданного в момент создания
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ПодробноеОписание
```bsl
// Функция устанавливает подробное описание параметра для справки
// возвращает текущий параметр команды
//
// Параметры:
// ВходящееПодробноеОписание - строка - строка с новым описанием, отличным от переданного в момент создания
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
//
```
##### Псевдоним
```bsl
// Функция устанавливает дополнительный синоним/псевдоним параметра для справки
// возвращает текущий параметр команды
//
// Параметры:
// СтрокаПсевдонима - строка - строка с новым псевдонимом, отличным от переданного в момент создания
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### Обязательный
```bsl
// Функция устанавливает признак обязательности указания данного параметра
// возвращает текущий параметр команды
//
// Параметры:
// Признак - булево - признак обязательности указания данного параметра (по умолчанию Истина)
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```
##### ВФайле
```bsl
// (ЗАГОТОВКА) Функция устанавливает путь и место в файле при получении настроек
// возвращает текущий параметр команды
//
// Параметры:
// ПутьКФайлу - строка - путь к файлу для чтения
// МестоВФайле - строка - путь в файле, в формате "general.force"
//
// Возвращаемое значение:
// ЭтотОбъект - класс ПараметрКоманд
```
##### ПроизвольныйТип
```bsl
// Функция устанавливает произвольный тип параметра
// возвращает текущий параметр команды
//
// Параметры:
// ВходящийКлассЗначенияПараметра - класс - Произвольный класс, реализующий ряд обязательных функций
// ВходящийТипПараметра - тип - тип значения параметра
// ВходящийТипЭлементаПараметра - Тип - тип элементов значения параметра, если тип Массив
//
// Возвращаемое значение:
// ПараметрКоманды - значение из переменной ЭтотОбъект
```