> For the complete documentation index, see [llms.txt](https://bryan-guner.gitbook.io/my-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bryan-guner.gitbook.io/my-docs/redux/repos/examples/real-world/node_modules/coa/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 Возвращает объект, который можно использовать в других программах. Подкоманды являются методами этого объекта.\ \&#xNAN;**@returns** *{Object}* #### Cmd.name Определяет канонический идентификатор команды, используемый в вызовах API.\ \&#xNAN;**@param** *String* `_name` имя команды\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.title Определяет название команды, используемый в текстовых сообщениях.\ \&#xNAN;**@param** *String* `_title` название команды\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.cmd Создает новую подкоманду или добавляет ранее определенную подкоманду к текущей команде.\ \&#xNAN;**@param** *COA.Cmd* `[cmd]` экземпляр ранее определенной подкоманды\ \&#xNAN;**@returns** *COA.Cmd* экземпляр новой или ранее определенной подкоманды #### Cmd.opt Создает параметр для текущей команды.\ \&#xNAN;**@returns** *COA.Opt* `new` экземпляр параметра #### Cmd.arg Создает аргумент для текущей команды.\ \&#xNAN;**@returns** *COA.Opt* `new` экземпляр аргумента #### Cmd.act Добавляет (или создает) действие для текущей команды.\ \&#xNAN;**@param** *Function* `act` функция, выполняемая в контексте экземпляра текущей команды и принимающая следующие параметры:\ \- *Object* `opts` параметры команды\ \- *Array* `args` аргументы команды\ \- *Object* `res` объект-аккумулятор результатов\ Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки) или любое другое значение, рассматриваемое как результат.\ \&#xNAN;**@param** *{Boolean}* \[force=false] флаг, назначающий немедленное исполнение вместо добавления к списку существующих действий\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.apply Исполняет функцию с переданными аргументами в контексте экземпляра текущей команды.\ \&#xNAN;**@param** *Function* `fn`\ \&#xNAN;**@param** *Array* `args`\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.comp Назначает кастомную функцию автодополнения для текущей команды.\ \&#xNAN;**@param** *Function* `fn` функция-генератор автодополнения, исполняемая в контексте текущей команды. Принимает параметры:\ \- *Object* `opts` параметры\ Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.helpful Ставит флаг поддержки справки командной строки, т.е. вызов команды с параметрами -h --help выводит справку по работе с командой.\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.completable Добавляет поддержку автодополнения командной строки. Добавляется подкоманда "completion", которая выполняет все необходимые действия.\ Может быть добавлен только для главной команды.\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.usage Возвращает текст справки по использованию команды для текущего экземпляра.\ \&#xNAN;**@returns** *String* `usage` Текст справки по использованию #### Cmd.run Разбирает аргументы из значения, возвращаемого NodeJS process.argv, и запускает текущую программу, т.е. вызывает process.exit после завершения всех действий.\ \&#xNAN;**@param** *Array* `argv`\ \&#xNAN;**@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов) #### Cmd.invoke Исполняет переданную (или текущую) команду с указанными параметрами и аргументами.\ \&#xNAN;**@param** *String|Array* `cmds` подкоманда для исполнения (необязательно)\ \&#xNAN;**@param** *Object* `opts` параметры, передаваемые команде (необязательно)\ \&#xNAN;**@param** *Object* `args` аргументы, передаваемые команде (необязательно)\ \&#xNAN;**@returns** *Q.Promise* #### Cmd.reject Проваливает промисы, возращенные в действиях.\ Используется в .act() для возврата с ошибкой.\ \&#xNAN;**@param** *Object* `reason` причина провала\ Вы можете определить метод toString() и свойство toString() объекта причины провала.\ \&#xNAN;**@returns** *Q.promise* проваленный промис #### Cmd.end Завершает цепочку методов текущей подкоманды и возвращает экземпляр родительской команды.\ \&#xNAN;**@returns** *COA.Cmd* `parent` родительская команда ### Opt Параметр — именованная сущность. У параметра может быть определено короткое или длинное имя для использования из командной строки.\ \&#xNAN;**@namespace**\ \&#xNAN;**@class** Переданный параметр #### Opt.name Определяет канонический идентификатор параметра, используемый в вызовах API.\ \&#xNAN;**@param** *String* `_name` имя параметра\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.title Определяет описание для параметра, используемое в текстовых сообщениях.\ \&#xNAN;**@param** *String* `_title` название параметра\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.short Назначает ключ для короткого имени параметра, передаваемого из командной строки с одинарным дефисом (например, `-v`).\ \&#xNAN;**@param** *String* `_short`\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.long Назначает ключ для длинного имени параметра, передаваемого из командной строки с двойным дефисом (например, `--version`).\ \&#xNAN;**@param** *String* `_long`\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.flag Помечает параметр как логический, т.е. параметр не имеющий значения.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.arr Помечает параметр как принимающий множественные значения.\ Иначе будет использовано последнее переданное значение параметра.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.req Помечает параметр как обязательный.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.only Интерпретирует параметр как команду, т.е. программа будет завершена сразу после выполнения параметра.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.val Назначает функцию валидации (или трансформации значения) для значения параметра.\ Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.\ Используется для валидации и трансформации введенных данных.\ \&#xNAN;**@param** *Function* `_val` функция валидации, исполняемая в контексте экземпляра параметра и принимающая в качестве единственного параметра значение, полученное из командной строки\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.def Назначает значение параметра по умолчанию. Это значение также передается в функцию валидации как обычное значение.\ \&#xNAN;**@param** *Object* `_def`\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.input Помечает параметр как принимающий ввод пользователя.\ Позволяет использовать валидацию для STDIN.\ \&#xNAN;**@returns** *{COA.Opt}* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.output Помечает параметр как вывод.\ Позволяет использовать валидацию для STDOUT.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.act Добавляет (или создает) действие для текущего параметра команды. Это действие будет выполнено, если текущий параметр есть в списке полученных параметров (с любым значением).\ \&#xNAN;**@param** *Function* `act` функция, выполняемая в контексте экземпляра текущей команды и принимающая следующие параметры:\ \- *Object* `opts` параметры команды\ \- *Array* `args` аргументы команды\ \- *Object* `res` объект-аккумулятор результатов\ Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки) или любое другое значение, рассматриваемое как результат.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.comp Назначает кастомную функцию автодополнения для текущей команды.\ \&#xNAN;**@param** *Function* `fn` функция-генератор автодоплнения, исполняемая в контексте экземпляра команды. Принимает параметры:\ \- *Object* `opts` параметры автодополнения\ Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов) #### Opt.end Завершает цепочку методов текущего параметра и возвращает экземпляр родительской команды.\ \&#xNAN;**@returns** *COA.Cmd* `parent` родительская команда ### Arg Аргумент — неименованная сущность.\ Аргументы передаются из командной строки как список неименованных значений. #### Arg.name Определяет канонический идентификатор аргумента, используемый в вызовах API.\ \&#xNAN;**@param** *String* `_name` имя аргумента\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.title Определяет описание для аргумента, используемое в текстовых сообщениях.\ \&#xNAN;**@param** *String* `_title` описание аргумента\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.arr Помечает аргумент как принимающий множественные значения.\ Иначе будет использовано последнее переданное значение аргумента.\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.req Помечает аргумент как обязательный.\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.val Назначает функцию валидации (или трансформации значения) для аргумента.\ Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.\ Используется для валидации и трансформации введенных данных.\ \&#xNAN;**@param** *Function* `_val` функция валидации, исполняемая в контексте экземпляра аргумента и принимающая в качестве единственного параметра значение, полученное из командной строки\ \&#xNAN;**@returns** *COA.Opt* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.def Назначает дефолтное значение для аргумента. Дефолтное значение передается в функцию валидации как обычное значение.\ \&#xNAN;**@param** *Object* `_def`\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.output Помечает параметр как вывод.\ Позволяет назначить валидацию для STDOUT.\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.comp Назначает кастомную функцию автодополнения для текущего аргумента.\ \&#xNAN;**@param** *Function* `fn` функция-генератор автодоплнения, исполняемая в контексте текущей команды. Принимает параметры:\ \- *Object* `opts` параметры Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.\ \&#xNAN;**@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов) #### Arg.end Завершает цепочку методов текущего аргумента и возвращает экземпляр родительской команды.\ \&#xNAN;**@returns** *COA.Cmd* `parent` родительская команда --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bryan-guner.gitbook.io/my-docs/redux/repos/examples/real-world/node_modules/coa/readme.ru.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.