✏️ Editing: README.ru.md

# Command-Option-Argument
[![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)

## Что это?

COA — парсер параметров командной строки, позволяющий извлечь максимум пользы от формального API вашей программы.
Как только вы опишете определение в терминах команд, параметров и аргументов, вы автоматически получите:

* Справку для командной строки
* API для использования программы как модуля в COA-совместимых программах
* Автодополнение для командной строки

### Прочие возможности

* Широкий выбор настроек для параметров и аргументов, включая множественные значения, логические значения и обязательность параметров
* Возможность асинхронного исполнения команд, используя промисы (используется библиотека [Q](https://github.com/kriskowal/q))
* Простота использования существующих команд как подмодулей для новых команд
* Комбинированная валидация и анализ сложных значений

## Примеры

````javascript
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 и запускаем
````

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

Ubuntu

Sid Gifari From Gifari Industries - BD Cyber Security Team



Ubuntu

Sid Gifari From Gifari Industries - BD Cyber Security Team