coa 0.4.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2015-present Sergey Berezhnoy <veged@ya.ru>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # Command-Option-Argument
2
- [![build status](https://secure.travis-ci.org/veged/coa.png)](http://travis-ci.org/veged/coa)
2
+
3
+ Yet another parser for command line options.
4
+
5
+ [![NPM Status][npm-img]][npm]
6
+ [![Travis Status][test-img]][travis]
7
+ [![AppVeyor Status][appveyor-img]][appveyor]
8
+ [![Coverage Status][coverage-img]][coveralls]
9
+ [![Dependency Status][dependency-img]][david]
10
+
11
+ [npm]: https://www.npmjs.org/package/coa
12
+ [npm-img]: https://img.shields.io/npm/v/coa.svg
13
+ [travis]: https://travis-ci.org/veged/coa
14
+ [test-img]: https://img.shields.io/travis/veged/coa.svg
15
+ [appveyor]: https://ci.appveyor.com/project/zxqfox/coa
16
+ [appveyor-img]: https://ci.appveyor.com/api/projects/status/github/veged/coa?svg=true
17
+ [coveralls]: https://coveralls.io/r/veged/coa
18
+ [coverage-img]: https://img.shields.io/coveralls/veged/coa.svg
19
+ [david]: https://david-dm.org/veged/coa
20
+ [dependency-img]: http://img.shields.io/david/veged/coa.svg
3
21
 
4
22
  ## What is it?
5
23
 
@@ -9,7 +27,6 @@ Once you write definition in terms of commands, options and arguments you automa
9
27
  * Command line help text
10
28
  * Program API for use COA-based programs as modules
11
29
  * Shell completion
12
- * Subcommand extendibility by external node modules
13
30
 
14
31
  ### Other features
15
32
 
@@ -20,8 +37,6 @@ Once you write definition in terms of commands, options and arguments you automa
20
37
 
21
38
  ### TODO
22
39
 
23
- * --Subcommand extendibility--
24
- * Shell completion helpers
25
40
  * Localization
26
41
  * Shell-mode
27
42
  * Configs
@@ -47,22 +62,14 @@ require('coa').Cmd() // main (top level) command declaration
47
62
  .version;
48
63
  })
49
64
  .end() // end option chain and return to main command
50
- .cmd()
51
- .name('subcommand')
52
- .apply(require('./subcommand')) // load subcommand from module
53
- .end()
65
+ .cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
54
66
  .cmd() // inplace subcommand declaration
55
- .name('othercommand')
56
- .title('Awesome other subcommand')
57
- .helpful()
67
+ .name('othercommand').title('Awesome other subcommand').helpful()
58
68
  .opt()
59
- .name('input')
60
- .title('input file, required')
61
- .short('i')
62
- .long('input')
69
+ .name('input').title('input file, required')
70
+ .short('i').long('input')
63
71
  .val(function(v) { // validator function, also for translate simple values
64
- return require('fs').createReadStream(v);
65
- })
72
+ return require('fs').createReadStream(v) })
66
73
  .req() // make option required
67
74
  .end() // end option chain and return to command
68
75
  .end() // end subcommand chain and return to parent command
@@ -71,14 +78,12 @@ require('coa').Cmd() // main (top level) command declaration
71
78
 
72
79
  ````javascript
73
80
  // subcommand.js
74
- module.exports = function() {
81
+ exports.COA = function() {
75
82
  this
76
83
  .title('Awesome subcommand').helpful()
77
84
  .opt()
78
- .name('output')
79
- .title('output file')
80
- .short('o')
81
- .long('output')
85
+ .name('output').title('output file')
86
+ .short('o').long('output')
82
87
  .output() // use default preset for "output" option declaration
83
88
  .end()
84
89
  };
@@ -153,16 +158,6 @@ Adds shell completion to command, adds "completion" subcommand, that makes all t
153
158
  Must be called only on root command.<br>
154
159
  **@returns** *COA.Cmd* `this` instance (for chainability)
155
160
 
156
- #### Cmd.extendable
157
- Adds ability to extend command by external node modules.<br>
158
- **@param** *String* `[pattern]` Pattern of modules names to search.
159
- Should be simple string with `%s` placeholder like `coa-program-%s-subcommand`
160
- or without it — it will be treated as module name prefix then. E.g. `coa-program-`.<br>
161
- Node module should export function or `Cmd` object. Function will be passed
162
- to `Cmd.apply()` method of created subcommand object using `Cmd.cmd()` method. And
163
- `Cmd` object will be passed to `Cmd.cmd()` method.
164
- **@returns** *COA.Cmd* `this` instance (for chainability)
165
-
166
161
  #### Cmd.usage
167
162
  Build full usage text for current command instance.<br>
168
163
  **@returns** *String* `usage` text
@@ -331,7 +326,7 @@ Make argument value outputing stream.<br>
331
326
  It's add useful validation and shortcut for STDOUT.<br>
332
327
  **@returns** *COA.Arg* `this` instance (for chainability)
333
328
 
334
- #### Opt.comp
329
+ #### Arg.comp
335
330
  Set custom additional completion for current argument.<br>
336
331
  **@param** *Function* `fn` completion generation function,
337
332
  invoked in the context of command instance.
package/README.ru.md ADDED
@@ -0,0 +1,316 @@
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` родительская команда
package/index.js CHANGED
@@ -1 +1 @@
1
- module.exports = require(process.env.COVER? './lib-cov' : './lib');
1
+ module.exports = require('./lib');