1 | # Command-Option-Argument
|
2 | [![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)
|
3 |
|
4 | ## Что это?
|
5 |
|
6 | COA — парсер параметров командной строки, позволяющий извлечь максимум пользы от формального API вашей программы.
|
7 | Как только вы опишете определение в терминах команд, параметров и аргументов, вы автоматически получите:
|
8 |
|
9 | * Справку для командной строки
|
10 | * API для использования программы как модуля в COA-совместимых программах
|
11 | * Автодополнение для командной строки
|
12 |
|
13 | ### Прочие возможности
|
14 |
|
15 | * Широкий выбор настроек для параметров и аргументов, включая множественные значения, логические значения и обязательность параметров
|
16 | * Возможность асинхронного исполнения команд, используя промисы (используется библиотека [Q](https://github.com/kriskowal/q))
|
17 | * Простота использования существующих команд как подмодулей для новых команд
|
18 | * Комбинированная валидация и анализ сложных значений
|
19 |
|
20 | ## Примеры
|
21 |
|
22 | ````javascript
|
23 | require('coa').Cmd() // декларация команды верхнего уровня
|
24 | .name(process.argv[1]) // имя команды верхнего уровня, берем из имени программы
|
25 | .title('Жутко полезная утилита для командной строки') // название для использования в справке и сообщениях
|
26 | .helpful() // добавляем поддержку справки командной строки (-h, --help)
|
27 | .opt() // добавляем параметр
|
28 | .name('version') // имя параметра для использования в API
|
29 | .title('Version') // текст для вывода в сообщениях
|
30 | .short('v') // короткое имя параметра: -v
|
31 | .long('version') // длинное имя параметра: --version
|
32 | .flag() // параметр не требует ввода значения
|
33 | .act(function(opts) { // действия при вызове аргумента
|
34 | // результатом является вывод текстового сообщения
|
35 | return JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
|
36 | .version;
|
37 | })
|
38 | .end() // завершаем определение параметра и возвращаемся к определению верхнего уровня
|
39 | .cmd().name('subcommand').apply(require('./subcommand').COA).end() // загрузка подкоманды из модуля
|
40 | .cmd() // добавляем еще одну подкоманду
|
41 | .name('othercommand').title('Еще одна полезная подпрограмма').helpful()
|
42 | .opt()
|
43 | .name('input').title('input file, required')
|
44 | .short('i').long('input')
|
45 | .val(function(v) { // функция-валидатор, также может использоваться для трансформации значений параметров
|
46 | return require('fs').createReadStream(v) })
|
47 | .req() // параметр является обязательным
|
48 | .end() // завершаем определение параметра и возвращаемся к определению команды
|
49 | .end() // завершаем определение подкоманды и возвращаемся к определению команды верхнего уровня
|
50 | .run(process.argv.slice(2)); // разбираем process.argv и запускаем
|
51 | ````
|
52 |
|
53 | ````javascript
|
54 | // subcommand.js
|
55 | exports.COA = function() {
|
56 | this
|
57 | .title('Полезная подпрограмма').helpful()
|
58 | .opt()
|
59 | .name('output').title('output file')
|
60 | .short('o').long('output')
|
61 | .output() // использовать стандартную настройку для параметра вывода
|
62 | .end()
|
63 | };
|
64 | ````
|
65 |
|
66 | ## API
|
67 |
|
68 | ### Cmd
|
69 | Команда — сущность верхнего уровня. У команды могут быть определены параметры и аргументы.
|
70 |
|
71 | #### Cmd.api
|
72 | Возвращает объект, который можно использовать в других программах. Подкоманды являются методами этого объекта.<br>
|
73 | **@returns** *{Object}*
|
74 |
|
75 | #### Cmd.name
|
76 | Определяет канонический идентификатор команды, используемый в вызовах API.<br>
|
77 | **@param** *String* `_name` имя команды<br>
|
78 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
79 |
|
80 | #### Cmd.title
|
81 | Определяет название команды, используемый в текстовых сообщениях.<br>
|
82 | **@param** *String* `_title` название команды<br>
|
83 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
84 |
|
85 | #### Cmd.cmd
|
86 | Создает новую подкоманду или добавляет ранее определенную подкоманду к текущей команде.<br>
|
87 | **@param** *COA.Cmd* `[cmd]` экземпляр ранее определенной подкоманды<br>
|
88 | **@returns** *COA.Cmd* экземпляр новой или ранее определенной подкоманды
|
89 |
|
90 | #### Cmd.opt
|
91 | Создает параметр для текущей команды.<br>
|
92 | **@returns** *COA.Opt* `new` экземпляр параметра
|
93 |
|
94 | #### Cmd.arg
|
95 | Создает аргумент для текущей команды.<br>
|
96 | **@returns** *COA.Opt* `new` экземпляр аргумента
|
97 |
|
98 | #### Cmd.act
|
99 | Добавляет (или создает) действие для текущей команды.<br>
|
100 | **@param** *Function* `act` функция,
|
101 | выполняемая в контексте экземпляра текущей команды
|
102 | и принимающая следующие параметры:<br>
|
103 | - *Object* `opts` параметры команды<br>
|
104 | - *Array* `args` аргументы команды<br>
|
105 | - *Object* `res` объект-аккумулятор результатов<br>
|
106 | Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки)
|
107 | или любое другое значение, рассматриваемое как результат.<br>
|
108 | **@param** *{Boolean}* [force=false] флаг, назначающий немедленное исполнение вместо добавления к списку существующих действий<br>
|
109 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
110 |
|
111 | #### Cmd.apply
|
112 | Исполняет функцию с переданными аргументами в контексте экземпляра текущей команды.<br>
|
113 | **@param** *Function* `fn`<br>
|
114 | **@param** *Array* `args`<br>
|
115 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
116 |
|
117 | #### Cmd.comp
|
118 | Назначает кастомную функцию автодополнения для текущей команды.<br>
|
119 | **@param** *Function* `fn` функция-генератор автодополнения,
|
120 | исполняемая в контексте текущей команды.
|
121 | Принимает параметры:<br>
|
122 | - *Object* `opts` параметры<br>
|
123 | Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
|
124 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
125 |
|
126 | #### Cmd.helpful
|
127 | Ставит флаг поддержки справки командной строки, т.е. вызов команды с параметрами -h --help выводит справку по работе с командой.<br>
|
128 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
129 |
|
130 | #### Cmd.completable
|
131 | Добавляет поддержку автодополнения командной строки. Добавляется подкоманда "completion", которая выполняет все необходимые действия.<br>
|
132 | Может быть добавлен только для главной команды.<br>
|
133 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
134 |
|
135 | #### Cmd.usage
|
136 | Возвращает текст справки по использованию команды для текущего экземпляра.<br>
|
137 | **@returns** *String* `usage` Текст справки по использованию
|
138 |
|
139 | #### Cmd.run
|
140 | Разбирает аргументы из значения, возвращаемого NodeJS process.argv,
|
141 | и запускает текущую программу, т.е. вызывает process.exit после завершения
|
142 | всех действий.<br>
|
143 | **@param** *Array* `argv`<br>
|
144 | **@returns** *COA.Cmd* `this` экземпляр команды (для поддержки цепочки методов)
|
145 |
|
146 | #### Cmd.invoke
|
147 | Исполняет переданную (или текущую) команду с указанными параметрами и аргументами.<br>
|
148 | **@param** *String|Array* `cmds` подкоманда для исполнения (необязательно)<br>
|
149 | **@param** *Object* `opts` параметры, передаваемые команде (необязательно)<br>
|
150 | **@param** *Object* `args` аргументы, передаваемые команде (необязательно)<br>
|
151 | **@returns** *Q.Promise*
|
152 |
|
153 | #### Cmd.reject
|
154 | Проваливает промисы, возращенные в действиях.<br>
|
155 | Используется в .act() для возврата с ошибкой.<br>
|
156 | **@param** *Object* `reason` причина провала<br>
|
157 | Вы можете определить метод toString() и свойство toString()
|
158 | объекта причины провала.<br>
|
159 | **@returns** *Q.promise* проваленный промис
|
160 |
|
161 | #### Cmd.end
|
162 | Завершает цепочку методов текущей подкоманды и возвращает экземпляр родительской команды.<br>
|
163 | **@returns** *COA.Cmd* `parent` родительская команда
|
164 |
|
165 | ### Opt
|
166 | Параметр — именованная сущность. У параметра может быть определено короткое или длинное имя для использования из командной строки.<br>
|
167 | **@namespace**<br>
|
168 | **@class** Переданный параметр
|
169 |
|
170 | #### Opt.name
|
171 | Определяет канонический идентификатор параметра, используемый в вызовах API.<br>
|
172 | **@param** *String* `_name` имя параметра<br>
|
173 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
174 |
|
175 | #### Opt.title
|
176 | Определяет описание для параметра, используемое в текстовых сообщениях.<br>
|
177 | **@param** *String* `_title` название параметра<br>
|
178 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
179 |
|
180 | #### Opt.short
|
181 | Назначает ключ для короткого имени параметра, передаваемого из командной строки с одинарным дефисом (например, `-v`).<br>
|
182 | **@param** *String* `_short`<br>
|
183 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
184 |
|
185 | #### Opt.long
|
186 | Назначает ключ для длинного имени параметра, передаваемого из командной строки с двойным дефисом (например, `--version`).<br>
|
187 | **@param** *String* `_long`<br>
|
188 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
189 |
|
190 | #### Opt.flag
|
191 | Помечает параметр как логический, т.е. параметр не имеющий значения.<br>
|
192 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
193 |
|
194 | #### Opt.arr
|
195 | Помечает параметр как принимающий множественные значения.<br>
|
196 | Иначе будет использовано последнее переданное значение параметра.<br>
|
197 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
198 |
|
199 | #### Opt.req
|
200 | Помечает параметр как обязательный.<br>
|
201 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
202 |
|
203 | #### Opt.only
|
204 | Интерпретирует параметр как команду,
|
205 | т.е. программа будет завершена сразу после выполнения параметра.<br>
|
206 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
207 |
|
208 | #### Opt.val
|
209 | Назначает функцию валидации (или трансформации значения) для значения параметра.<br>
|
210 | Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.<br>
|
211 | Используется для валидации и трансформации введенных данных.<br>
|
212 | **@param** *Function* `_val` функция валидации,
|
213 | исполняемая в контексте экземпляра параметра
|
214 | и принимающая в качестве единственного параметра значение, полученное
|
215 | из командной строки<br>
|
216 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
217 |
|
218 | #### Opt.def
|
219 | Назначает значение параметра по умолчанию. Это значение также передается
|
220 | в функцию валидации как обычное значение.<br>
|
221 | **@param** *Object* `_def`<br>
|
222 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
223 |
|
224 | #### Opt.input
|
225 | Помечает параметр как принимающий ввод пользователя. <br>
|
226 | Позволяет использовать валидацию для STDIN.<br>
|
227 | **@returns** *{COA.Opt}* `this` экземпляр параметра (для поддержки цепочки методов)
|
228 |
|
229 | #### Opt.output
|
230 | Помечает параметр как вывод.<br>
|
231 | Позволяет использовать валидацию для STDOUT.<br>
|
232 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
233 |
|
234 | #### Opt.act
|
235 | Добавляет (или создает) действие для текущего параметра команды.
|
236 | Это действие будет выполнено, если текущий параметр есть
|
237 | в списке полученных параметров (с любым значением).<br>
|
238 | **@param** *Function* `act` функция, выполняемая в контексте
|
239 | экземпляра текущей команды и принимающая следующие параметры:<br>
|
240 | - *Object* `opts` параметры команды<br>
|
241 | - *Array* `args` аргументы команды<br>
|
242 | - *Object* `res` объект-аккумулятор результатов<br>
|
243 | Функция может вернуть проваленный промис из Cmd.reject (в случае ошибки)
|
244 | или любое другое значение, рассматриваемое как результат.<br>
|
245 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
246 |
|
247 | #### Opt.comp
|
248 | Назначает кастомную функцию автодополнения для текущей команды.<br>
|
249 | **@param** *Function* `fn` функция-генератор автодоплнения, исполняемая в
|
250 | контексте экземпляра команды.
|
251 | Принимает параметры:<br>
|
252 | - *Object* `opts` параметры автодополнения<br>
|
253 | Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
|
254 | **@returns** *COA.Opt* `this` экземпляр параметра (для поддержки цепочки методов)
|
255 |
|
256 | #### Opt.end
|
257 | Завершает цепочку методов текущего параметра и возвращает экземпляр родительской команды.<br>
|
258 | **@returns** *COA.Cmd* `parent` родительская команда
|
259 |
|
260 |
|
261 | ### Arg
|
262 | Аргумент — неименованная сущность.<br>
|
263 | Аргументы передаются из командной строки как список неименованных значений.
|
264 |
|
265 | #### Arg.name
|
266 | Определяет канонический идентификатор аргумента, используемый в вызовах API.<br>
|
267 | **@param** *String* `_name` имя аргумента<br>
|
268 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
269 |
|
270 | #### Arg.title
|
271 | Определяет описание для аргумента, используемое в текстовых сообщениях.<br>
|
272 | **@param** *String* `_title` описание аргумента<br>
|
273 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
274 |
|
275 | #### Arg.arr
|
276 | Помечает аргумент как принимающий множественные значения.<br>
|
277 | Иначе будет использовано последнее переданное значение аргумента.<br>
|
278 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
279 |
|
280 | #### Arg.req
|
281 | Помечает аргумент как обязательный.<br>
|
282 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
283 |
|
284 | #### Arg.val
|
285 | Назначает функцию валидации (или трансформации значения) для аргумента.<br>
|
286 | Значение, полученное из командной строки, передается в функцию-валидатор прежде чем оно станет доступно из API.<br>
|
287 | Используется для валидации и трансформации введенных данных.<br>
|
288 | **@param** *Function* `_val` функция валидации,
|
289 | исполняемая в контексте экземпляра аргумента
|
290 | и принимающая в качестве единственного параметра значение, полученное
|
291 | из командной строки<br>
|
292 | **@returns** *COA.Opt* `this` экземпляр аргумента (для поддержки цепочки методов)
|
293 |
|
294 | #### Arg.def
|
295 | Назначает дефолтное значение для аргумента. Дефолтное значение передается
|
296 | в функцию валидации как обычное значение.<br>
|
297 | **@param** *Object* `_def`<br>
|
298 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
299 |
|
300 | #### Arg.output
|
301 | Помечает параметр как вывод.<br>
|
302 | Позволяет назначить валидацию для STDOUT.<br>
|
303 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
304 |
|
305 | #### Arg.comp
|
306 | Назначает кастомную функцию автодополнения для текущего аргумента.<br>
|
307 | **@param** *Function* `fn` функция-генератор автодоплнения,
|
308 | исполняемая в контексте текущей команды.
|
309 | Принимает параметры:<br>
|
310 | - *Object* `opts` параметры
|
311 | Может возвращать промис или любое другое значение, рассматриваемое как результат исполнения команды.<br>
|
312 | **@returns** *COA.Arg* `this` экземпляр аргумента (для поддержки цепочки методов)
|
313 |
|
314 | #### Arg.end
|
315 | Завершает цепочку методов текущего аргумента и возвращает экземпляр родительской команды.<br>
|
316 | **@returns** *COA.Cmd* `parent` родительская команда
|
317 |
|
\ | No newline at end of file |