22 KiB
Command-Option-Argument
Что это?
COA — парсер параметров командной строки, позволяющий извлечь максимум пользы от формального API вашей программы. Как только вы опишете определение в терминах команд, параметров и аргументов, вы автоматически получите:
- Справку для командной строки
- API для использования программы как модуля в COA-совместимых программах
- Автодополнение для командной строки
Прочие возможности
- Широкий выбор настроек для параметров и аргументов, включая множественные значения, логические значения и обязательность параметров
- Возможность асинхронного исполнения команд, используя промисы (используется библиотека Q)
- Простота использования существующих команд как подмодулей для новых команд
- Комбинированная валидация и анализ сложных значений
Примеры
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 и запускаем
// subcommand.js
.COA = function() {
exportsthis
.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
родительская команда