sfcode
An Online Competing and Development Environment
Command-Option-Argument

build status

Что это?

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
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.

Parameters
</strong>String _name имя команды
Returns
COA.Cmd this экземпляр команды (для поддержки цепочки методов)

Cmd.title

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

Parameters
</strong>String _title название команды
Returns
COA.Cmd this экземпляр команды (для поддержки цепочки методов)

Cmd.cmd

Создает новую подкоманду или добавляет ранее определенную подкоманду к текущей команде.

Parameters
</strong>COA.Cmd [cmd] экземпляр ранее определенной подкоманды
Returns
COA.Cmd экземпляр новой или ранее определенной подкоманды

Cmd.opt

Создает параметр для текущей команды.

Returns
COA.Opt new экземпляр параметра

Cmd.arg

Создает аргумент для текущей команды.

Returns
COA.Opt new экземпляр аргумента

Cmd.act

Добавляет (или создает) действие для текущей команды.

Parameters
</strong>Function act функция, выполняемая в контексте экземпляра текущей команды и принимающая следующие параметры:
  • Object opts параметры команды
  • Array args аргументы команды
  • Object res объект-аккумулятор результатов
    Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки) или любое другое значение, рассматриваемое как результат.
</strong>*{Boolean}* [force=false] флаг, назначающий немедленное исполнение вместо добавления к списку существующих действий
Returns
COA.Cmd this экземпляр команды (для поддержки цепочки методов)

Cmd.apply

Исполняет функцию с переданными аргументами в контексте экземпляра текущей команды.

Parameters
</strong>Function fn
</strong>Array args
Returns
COA.Cmd this экземпляр команды (для поддержки цепочки методов)

Cmd.comp

Назначает кастомную функцию автодополнения для текущей команды.

Parameters
</strong>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 после завершения всех действий.

Parameters
</strong>Array argv
Returns
COA.Cmd this экземпляр команды (для поддержки цепочки методов)

Cmd.invoke

Исполняет переданную (или текущую) команду с указанными параметрами и аргументами.

Parameters
</strong>String|Array cmds подкоманда для исполнения (необязательно)
</strong>Object opts параметры, передаваемые команде (необязательно)
</strong>Object args аргументы, передаваемые команде (необязательно)
Returns
Q.Promise

Cmd.reject

Проваливает промисы, возращенные в действиях.
Используется в .act() для возврата с ошибкой.

Parameters
</strong>Object reason причина провала
Вы можете определить метод toString() и свойство toString() объекта причины провала.
Returns
Q.promise проваленный промис

Cmd.end

Завершает цепочку методов текущей подкоманды и возвращает экземпляр родительской команды.

Returns
COA.Cmd parent родительская команда

Opt

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