22 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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

22 KiB Raw Blame History Unescape Escape