Skip to content

HTTPS clone URL

Subversion checkout URL

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