保誠-保戶業務員媒合平台
編輯 | 究查 | 歷程 | 原始

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.

@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 родительская команда