From 26105034da4fcce7ac883c899d781f016559310d Mon Sep 17 00:00:00 2001 From: ruki Date: Thu, 8 Nov 2018 00:38:48 +0800 Subject: switch to vuepress --- node_modules/coa/README.ru.md | 316 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 node_modules/coa/README.ru.md (limited to 'node_modules/coa/README.ru.md') diff --git a/node_modules/coa/README.ru.md b/node_modules/coa/README.ru.md new file mode 100644 index 00000000..54a8bafe --- /dev/null +++ b/node_modules/coa/README.ru.md @@ -0,0 +1,316 @@ +# Command-Option-Argument +[![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa) + +## Что это? + +COA — парсер параметров командной строки, позволяющий извлечь максимум пользы от формального API вашей программы. +Как только вы опишете определение в терминах команд, параметров и аргументов, вы автоматически получите: + +* Справку для командной строки +* API для использования программы как модуля в COA-совместимых программах +* Автодополнение для командной строки + +### Прочие возможности + +* Широкий выбор настроек для параметров и аргументов, включая множественные значения, логические значения и обязательность параметров +* Возможность асинхронного исполнения команд, используя промисы (используется библиотека [Q](https://github.com/kriskowal/q)) +* Простота использования существующих команд как подмодулей для новых команд +* Комбинированная валидация и анализ сложных значений + +## Примеры + +````javascript +require('coa').Cmd() // декларация команды верхнего уровня + .name(process.argv[1]) // имя команды верхнего уровня, берем из имени программы + .title('Жутко полезная утилита для командной строки') // название для использования в справке и сообщениях + .helpful() // добавляем поддержку справки командной строки (-h, --help) + .opt() // добавляем параметр + .name('version') // имя параметра для использования в API + .title('Version') // текст для вывода в сообщениях + .short('v') // короткое имя параметра: -v + .long('version') // длинное имя параметра: --version + .flag() // параметр не требует ввода значения + .act(function(opts) { // действия при вызове аргумента + // результатом является вывод текстового сообщения + return JSON.parse(require('fs').readFileSync(__dirname + '/package.json')) + .version; + }) + .end() // завершаем определение параметра и возвращаемся к определению верхнего уровня + .cmd().name('subcommand').apply(require('./subcommand').COA).end() // загрузка подкоманды из модуля + .cmd() // добавляем еще одну подкоманду + .name('othercommand').title('Еще одна полезная подпрограмма').helpful() + .opt() + .name('input').title('input file, required') + .short('i').long('input') + .val(function(v) { // функция-валидатор, также может использоваться для трансформации значений параметров + return require('fs').createReadStream(v) }) + .req() // параметр является обязательным + .end() // завершаем определение параметра и возвращаемся к определению команды + .end() // завершаем определение подкоманды и возвращаемся к определению команды верхнего уровня + .run(process.argv.slice(2)); // разбираем process.argv и запускаем +```` + +````javascript +// subcommand.js +exports.COA = function() { + this + .title('Полезная подпрограмма').helpful() + .opt() + .name('output').title('output file') + .short('o').long('output') + .output() // использовать стандартную настройку для параметра вывода + .end() +}; +```` + +## API + +### Cmd +Команда — сущность верхнего уровня. У команды могут быть определены параметры и аргументы. + +#### Cmd.api +Возвращает объект, который можно использовать в других программах. Подкоманды являются методами этого объекта.
+**@returns** *{Object}* + +#### Cmd.name +Определяет канонический идентификатор команды, используемый в вызовах API.
+**@param** *String* `_name` имя команды
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.title +Определяет название команды, используемый в текстовых сообщениях.
+**@param** *String* `_title` название команды
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.cmd +Создает новую подкоманду или добавляет ранее определенную подкоманду к текущей команде.
+**@param** *COA.Cmd* `[cmd]` экземпляр ранее определенной подкоманды
+**@returns** *COA.Cmd* экземпляр новой или ранее определенной подкоманды + +#### Cmd.opt +Создает параметр для текущей команды.
+**@returns** *COA.Opt* `new` экземпляр параметра + +#### Cmd.arg +Создает аргумент для текущей команды.
+**@returns** *COA.Opt* `new` экземпляр аргумента + +#### Cmd.act +Добавляет (или создает) действие для текущей команды.
+**@param** *Function* `act` функция, + выполняемая в контексте экземпляра текущей команды + и принимающая следующие параметры:
+ - *Object* `opts` параметры команды
+ - *Array* `args` аргументы команды
+ - *Object* `res` объект-аккумулятор результатов
+ Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки) + или любое другое значение, рассматриваемое как результат.
+**@param** *{Boolean}* [force=false] флаг, назначающий немедленное исполнение вместо добавления к списку существующих действий
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.apply +Исполняет функцию с переданными аргументами в контексте экземпляра текущей команды.
+**@param** *Function* `fn`
+**@param** *Array* `args`
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.comp +Назначает кастомную функцию автодополнения для текущей команды.
+**@param** *Function* `fn` функция-генератор автодополнения, + исполняемая в контексте текущей команды. + Принимает параметры:
+ - *Object* `opts` параметры
+ Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.helpful +Ставит флаг поддержки справки командной строки, т.е. вызов команды с параметрами -h --help выводит справку по работе с командой.
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.completable +Добавляет поддержку автодополнения командной строки. Добавляется подкоманда "completion", которая выполняет все необходимые действия.
+Может быть добавлен только для главной команды.
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.usage +Возвращает текст справки по использованию команды для текущего экземпляра.
+**@returns** *String* `usage` Текст справки по использованию + +#### Cmd.run +Разбирает аргументы из значения, возвращаемого NodeJS process.argv, +и запускает текущую программу, т.е. вызывает process.exit после завершения +всех действий.
+**@param** *Array* `argv`
+**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) + +#### Cmd.invoke +Исполняет переданную (или текущую) команду с указанными параметрами и аргументами.
+**@param** *String|Array* `cmds` подкоманда для исполнения (необязательно)
+**@param** *Object* `opts` параметры, передаваемые команде (необязательно)
+**@param** *Object* `args` аргументы, передаваемые команде (необязательно)
+**@returns** *Q.Promise* + +#### Cmd.reject +Проваливает промисы, возращенные в действиях.
+Используется в .act() для возврата с ошибкой.
+**@param** *Object* `reason` причина провала
+ Вы можете определить метод toString() и свойство toString() + объекта причины провала.
+**@returns** *Q.promise* проваленный промис + +#### Cmd.end +Завершает цепочку методов текущей подкоманды и возвращает экземпляр родительской команды.
+**@returns** *COA.Cmd* `parent` родительская команда + +### Opt +Параметр — именованная сущность. У параметра может быть определено короткое или длинное имя для использования из командной строки.
+**@namespace**
+**@class** Переданный параметр + +#### Opt.name +Определяет канонический идентификатор параметра, используемый в вызовах API.
+**@param** *String* `_name` имя параметра
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.title +Определяет описание для параметра, используемое в текстовых сообщениях.
+**@param** *String* `_title` название параметра
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.short +Назначает ключ для короткого имени параметра, передаваемого из командной строки с одинарным дефисом (например, `-v`).
+**@param** *String* `_short`
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.long +Назначает ключ для длинного имени параметра, передаваемого из командной строки с двойным дефисом (например, `--version`).
+**@param** *String* `_long`
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.flag +Помечает параметр как логический, т.е. параметр не имеющий значения.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.arr +Помечает параметр как принимающий множественные значения.
+Иначе будет использовано последнее переданное значение параметра.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.req +Помечает параметр как обязательный.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.only +Интерпретирует параметр как команду, +т.е. программа будет завершена сразу после выполнения параметра.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.val +Назначает функцию валидации (или трансформации значения) для значения параметра.
+Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.
+Используется для валидации и трансформации введенных данных.
+**@param** *Function* `_val` функция валидации, + исполняемая в контексте экземпляра параметра + и принимающая в качестве единственного параметра значение, полученное + из командной строки
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.def +Назначает значение параметра по умолчанию. Это значение также передается +в функцию валидации как обычное значение.
+**@param** *Object* `_def`
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.input +Помечает параметр как принимающий ввод пользователя.
+Позволяет использовать валидацию для STDIN.
+**@returns** *{COA.Opt}* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.output +Помечает параметр как вывод.
+Позволяет использовать валидацию для STDOUT.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.act +Добавляет (или создает) действие для текущего параметра команды. +Это действие будет выполнено, если текущий параметр есть +в списке полученных параметров (с любым значением).
+**@param** *Function* `act` функция, выполняемая в контексте + экземпляра текущей команды и принимающая следующие параметры:
+ - *Object* `opts` параметры команды
+ - *Array* `args` аргументы команды
+ - *Object* `res` объект-аккумулятор результатов
+ Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки) + или любое другое значение, рассматриваемое как результат.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.comp +Назначает кастомную функцию автодополнения для текущей команды.
+**@param** *Function* `fn` функция-генератор автодоплнения, исполняемая в + контексте экземпляра команды. + Принимает параметры:
+ - *Object* `opts` параметры автодополнения
+ Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.
+**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) + +#### Opt.end +Завершает цепочку методов текущего параметра и возвращает экземпляр родительской команды.
+**@returns** *COA.Cmd* `parent` родительская команда + + +### Arg +Аргумент — неименованная сущность.
+Аргументы передаются из командной строки как список неименованных значений. + +#### Arg.name +Определяет канонический идентификатор аргумента, используемый в вызовах API.
+**@param** *String* `_name` имя аргумента
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.title +Определяет описание для аргумента, используемое в текстовых сообщениях.
+**@param** *String* `_title` описание аргумента
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.arr +Помечает аргумент как принимающий множественные значения.
+Иначе будет использовано последнее переданное значение аргумента.
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.req +Помечает аргумент как обязательный.
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.val +Назначает функцию валидации (или трансформации значения) для аргумента.
+Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.
+Используется для валидации и трансформации введенных данных.
+**@param** *Function* `_val` функция валидации, + исполняемая в контексте экземпляра аргумента + и принимающая в качестве единственного параметра значение, полученное + из командной строки
+**@returns** *COA.Opt* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.def +Назначает дефолтное значение для аргумента. Дефолтное значение передается +в функцию валидации как обычное значение.
+**@param** *Object* `_def`
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.output +Помечает параметр как вывод.
+Позволяет назначить валидацию для STDOUT.
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.comp +Назначает кастомную функцию автодополнения для текущего аргумента.
+**@param** *Function* `fn` функция-генератор автодоплнения, + исполняемая в контексте текущей команды. + Принимает параметры:
+ - *Object* `opts` параметры +Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.
+**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) + +#### Arg.end +Завершает цепочку методов текущего аргумента и возвращает экземпляр родительской команды.
+**@returns** *COA.Cmd* `parent` родительская команда -- cgit v1.2.3