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.

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

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