Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 251 lines (205 sloc) 8.477 kb
5ab6944 @veged Init
authored
1 # Command-Option-Argument
2
3 COA is a yet another parser for command line options.
4 You can choose one of the [existing modules](https://github.com/joyent/node/wiki/modules#parsers-commandline),
5 or write your own like me.
6
7 ## Examples
8
9 ````javascript
10 require('coa').Cmd() // main command declaration
11 .name(process.argv[1])
12 .title('My awesome command line util')
13 .helpful()
14 .opt()
15 .name('version').short('v').long('version')
16 .title('Version')
17 .type(Boolean)
e64e1fc @veged * Rewrite in CoffeeScript
authored
18 .act(function(opts) {
19 opts.version &&
20 this.exit(
21 JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
22 .version);
23 })
5ab6944 @veged Init
authored
24 .end()
85118a6 @veged Edited README.md via GitHub
authored
25 .cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
5ab6944 @veged Init
authored
26 .cmd() // inplace subcommand declaration
27 .name('othercommand')
28 .title('Awesome other subcommand').helpful()
29 .opt()
30 .name('input').short('i').long('input')
31 .title('input file, required')
32 .validate(function(f) { return require('fs').createReadStream(f) })
33 .required()
34 .end()
35 .end()
36 .parse(process.argv.slice(2));
37 ````
38
39 ````javascript
40 // subcommand.js
41 exports.COA = function() {
42 this
43 .title('Awesome subcommand').helpful()
44 .opt()
45 .name('output').short('o').long('output')
46 .title('output file')
47 .output() // use default preset for "output" option declaration
48 .end()
49 };
50 ````
1dc5a3d @veged Add TODO
authored
51
e64e1fc @veged * Rewrite in CoffeeScript
authored
52 ## API
53
54 ### Cmd
55 Command is a top level entity. Commands may have options and arguments.<br>
56
57 #### Cmd.name
58 Set a canonical command identifier to be used anywhere in the API.<br>
59 **@param** *String* `_name` command name<br>
60 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
61
62 #### Cmd.title
63 Set a long description for command to be used anywhere in text messages.<br>
64 **@param** *String* `_title` command title<br>
65 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
66
67 #### Cmd.cmd
68 Create new subcommand for current command.<br>
69 **@returns** *COA.Cmd* `new` subcommand instance<br>
70
71 #### Cmd.opt
72 Create option for current command.<br>
73 **@returns** *COA.Opt* `new` option instance<br>
74
75 #### Cmd.arg
76 Create argument for current command.<br>
77 **@returns** *COA.Opt* `new` argument instance<br>
78
79 #### Cmd.act
80 Add (or set) action for current command.<br>
81 **@param** *Function* `act` action function,<br>
82 invoked in the context of command instance<br>
83 and has the parameters:<br>
84 - *Object* `opts` parsed options<br>
85 - *Array* `args` parsed arguments<br>
86 **@param** *{Boolean}* [force=false] flag for set action instead add to existings<br>
87 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
88
89 #### Cmd.apply
90 Apply function with arguments in context of command instance.<br>
91 **@param** *Function* `fn`<br>
92 **@param** *Array* `args`<br>
93 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
94
95 #### Cmd.helpful
96 Make command "helpful", i.e. add -h --help flags for print usage.<br>
97 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
98
99 #### Cmd.errorExit
100 Terminate program with error code 1.<br>
101 **@param** *String* `msg` message for print to STDERR<br>
102 **@param** *{Object}* [o] optional object for print with message<br>
103
104 #### Cmd.exit
105 Terminate program with error code 0.<br>
106 **@param** *String* `msg` message for print to STDERR<br>
107
108 #### Cmd.usage
109 Build full usage text for current command instance.<br>
110 **@returns** *String* `usage` text<br>
111
112 #### Cmd.parse
113 Parse arguments from simple format like NodeJS process.argv.<br>
114 **@param** *Array* `argv`<br>
115 **@returns** *COA.Cmd* `this` instance (for chainability)<br>
116
117 #### Cmd.end
118 Finish chain for current subcommand and return parent command instance.<br>
119 **@returns** *COA.Cmd* `parent` command<br>
120
121 ### Opt
122 Option is a named entity. Options may have short and long keys for use from command line.<br>
123 **@namespace**<br>
124 **@class** Presents option<br>
125
126 #### Opt.name
127 Set a canonical option identifier to be used anywhere in the API.<br>
128 **@param** *String* `_name` option name<br>
129 **@returns** *COA.Opt* `this` instance (for chainability)<br>
130
131 #### Opt.title
132 Set a long description for option to be used anywhere in text messages.<br>
133 **@param** *String* `_title` option title<br>
134 **@returns** *COA.Opt* `this` instance (for chainability)<br>
135
136
137 #### Opt.short
138 Set a short key for option to be used with one hyphen from command line.<br>
139 **@param** *String* `_short`<br>
140 **@returns** *COA.Opt* `this` instance (for chainability)<br>
141
142 #### Opt.long
143 Set a short key for option to be used with double hyphens from command line.<br>
144 **@param** *String* `_long`<br>
145 **@returns** *COA.Opt* `this` instance (for chainability)<br>
146
147 #### Opt.type
148 Set a type of option. Mainly using with Boolean for options without value.<br>
149 **@param** *Object* `_type`<br>
150 **@returns** *COA.Opt* `this` instance (for chainability)<br>
151
152 #### Opt.push
153 Makes an option accepts multiple values.<br>
154 Otherwise, the value will be used by the latter passed.<br>
155 **@returns** *COA.Opt* `this` instance (for chainability)<br>
156
157 #### Opt.required
158 Makes an option required.<br>
159 **@returns** *COA.Opt* `this` instance (for chainability)<br>
160
161 #### Opt.validate
162 Set a validation function for option.<br>
163 Value from command line passes through before becoming available from API.<br>
164 **@param** *Function* `_validate` validating function,<br>
165 invoked in the context of option instance<br>
166 and has one parameter with value from command line<br>
167 **@returns** *COA.Opt* `this` instance (for chainability)<br>
168
169 #### Opt.def
170 Set a default value for option.<br>
171 Default value passed through validation function as ordinary value.<br>
172 **@param** *Object* `_def`<br>
173 **@returns** *COA.Opt* `this` instance (for chainability)<br>
174
175 #### Opt.output
176 Make option value outputing stream.<br>
177 It's add useful validation and shortcut for STDOUT.<br>
178 **@returns** *COA.Opt* `this` instance (for chainability)<br>
179
180 #### Opt.act
181 Add action for current option command.<br>
182 This action is performed if the current option<br>
183 is present in parsed options (with any value).<br>
184 **@param** *Function* `act` action function,<br>
185 invoked in the context of command instance<br>
186 and has the parameters:<br>
187 - *Object* `opts` parsed options<br>
188 - *Array* `args` parsed arguments<br>
189 **@returns** *COA.Opt* `this` instance (for chainability)<br>
190
191 #### Opt.end
192 Finish chain for current option and return parent command instance.<br>
193 **@returns** *COA.Cmd* `parent` command<br>
194
195
196 ### Arg
197 Argument is a unnamed entity.<br>
198 From command line arguments passed as list of unnamed values.<br>
199
200 #### Arg.name
201 Set a canonical argument identifier to be used anywhere in text messages.<br>
202 **@param** *String* `_name` argument name<br>
203 **@returns** *COA.Arg* `this` instance (for chainability)<br>
204
205 #### Arg.title
206 Set a long description for argument to be used anywhere in text messages.<br>
207 **@param** *String* `_title` argument title<br>
208 **@returns** *COA.Arg* `this` instance (for chainability)<br>
209
210 #### Arg.push
211 Makes an argument accepts multiple values.<br>
212 Otherwise, the value will be used by the latter passed.<br>
213 **@returns** *COA.Arg* `this` instance (for chainability)<br>
214
215 #### Arg.required
216 Makes an argument required.<br>
217 **@returns** *COA.Arg* `this` instance (for chainability)<br>
218
219 #### Arg.validate
220 Set a validation function for argument.<br>
221 Value from command line passes through before becoming available from API.<br>
222 **@param** *Function* `_validate` validating function,<br>
223 invoked in the context of argument instance<br>
224 and has one parameter with value from command line<br>
225 **@returns** *COA.Arg* `this` instance (for chainability)<br>
226
227 #### Arg.def
228 Set a default value for argument.<br>
229 Default value passed through validation function as ordinary value.<br>
230 **@param** *Object* `_def`<br>
231 **@returns** *COA.Arg* `this` instance (for chainability)<br>
232
233 #### Arg.output
234 Make argument value outputing stream.<br>
235 It's add useful validation and shortcut for STDOUT.<br>
236 **@returns** *COA.Arg* `this` instance (for chainability)<br>
237
238 #### Arg.end
239 Finish chain for current option and return parent command instance.<br>
240 **@returns** *COA.Cmd* `parent` command<br>
241
242
1dc5a3d @veged Add TODO
authored
243 ## TODO
244 * Program API for use COA-covered programs as modules
6f183d2 @veged Edited README.md via GitHub
authored
245 * Shell completion
e64e1fc @veged * Rewrite in CoffeeScript
authored
246 * Localization
f07cc57 @veged Edited README.md via GitHub
authored
247 * Shell-mode
6b32888 @veged Edited README.md via GitHub
authored
248 * Configs
9dfe97b @veged Edited README.md via GitHub
authored
249 * Aliases
e64e1fc @veged * Rewrite in CoffeeScript
authored
250 * Defaults
Something went wrong with that request. Please try again.