murano-cli-commander 4.4.10

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.
Files changed (48) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +7 -0
  3. data/.rspec +2 -0
  4. data/.rubocop.yml +44 -0
  5. data/.rubocop_todo.yml +77 -0
  6. data/.travis.yml +14 -0
  7. data/DEVELOPMENT +15 -0
  8. data/Gemfile +3 -0
  9. data/History.rdoc +446 -0
  10. data/LICENSE +22 -0
  11. data/Manifest +38 -0
  12. data/README.md +475 -0
  13. data/Rakefile +13 -0
  14. data/bin/murano-cli-commander +104 -0
  15. data/lib/murano-cli-commander.rb +35 -0
  16. data/lib/murano-cli-commander/blank.rb +7 -0
  17. data/lib/murano-cli-commander/command.rb +214 -0
  18. data/lib/murano-cli-commander/configure.rb +14 -0
  19. data/lib/murano-cli-commander/core_ext.rb +2 -0
  20. data/lib/murano-cli-commander/core_ext/array.rb +24 -0
  21. data/lib/murano-cli-commander/core_ext/object.rb +8 -0
  22. data/lib/murano-cli-commander/delegates.rb +25 -0
  23. data/lib/murano-cli-commander/help_formatters.rb +49 -0
  24. data/lib/murano-cli-commander/help_formatters/base.rb +24 -0
  25. data/lib/murano-cli-commander/help_formatters/terminal.rb +19 -0
  26. data/lib/murano-cli-commander/help_formatters/terminal/command_help.erb +35 -0
  27. data/lib/murano-cli-commander/help_formatters/terminal/help.erb +36 -0
  28. data/lib/murano-cli-commander/help_formatters/terminal_compact.rb +11 -0
  29. data/lib/murano-cli-commander/help_formatters/terminal_compact/command_help.erb +27 -0
  30. data/lib/murano-cli-commander/help_formatters/terminal_compact/help.erb +29 -0
  31. data/lib/murano-cli-commander/import.rb +5 -0
  32. data/lib/murano-cli-commander/methods.rb +11 -0
  33. data/lib/murano-cli-commander/platform.rb +7 -0
  34. data/lib/murano-cli-commander/runner.rb +455 -0
  35. data/lib/murano-cli-commander/user_interaction.rb +551 -0
  36. data/lib/murano-cli-commander/version.rb +3 -0
  37. data/murano-cli-commander.gemspec +36 -0
  38. data/spec/command_spec.rb +169 -0
  39. data/spec/configure_spec.rb +37 -0
  40. data/spec/core_ext/array_spec.rb +18 -0
  41. data/spec/core_ext/object_spec.rb +19 -0
  42. data/spec/help_formatters/terminal_compact_spec.rb +69 -0
  43. data/spec/help_formatters/terminal_spec.rb +67 -0
  44. data/spec/methods_spec.rb +61 -0
  45. data/spec/runner_spec.rb +646 -0
  46. data/spec/spec_helper.rb +78 -0
  47. data/spec/ui_spec.rb +30 -0
  48. metadata +163 -0
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2008-2013 TJ Holowaychuk <tj@vision-media.ca>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included
14
+ in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/Manifest ADDED
@@ -0,0 +1,38 @@
1
+ DEVELOPMENT
2
+ History.rdoc
3
+ Manifest
4
+ README.rdoc
5
+ Rakefile
6
+ bin/murano-cli-commander
7
+ murano-cli-commander.gemspec
8
+ lib/murano-cli-commander.rb
9
+ lib/murano-cli-commander/blank.rb
10
+ lib/murano-cli-commander/command.rb
11
+ lib/murano-cli-commander/core_ext.rb
12
+ lib/murano-cli-commander/core_ext/array.rb
13
+ lib/murano-cli-commander/core_ext/object.rb
14
+ lib/murano-cli-commander/delegates.rb
15
+ lib/murano-cli-commander/help_formatters.rb
16
+ lib/murano-cli-commander/help_formatters/base.rb
17
+ lib/murano-cli-commander/help_formatters/terminal.rb
18
+ lib/murano-cli-commander/help_formatters/terminal/command_help.erb
19
+ lib/murano-cli-commander/help_formatters/terminal/help.erb
20
+ lib/murano-cli-commander/help_formatters/terminal_compact.rb
21
+ lib/murano-cli-commander/help_formatters/terminal_compact/command_help.erb
22
+ lib/murano-cli-commander/help_formatters/terminal_compact/help.erb
23
+ lib/murano-cli-commander/import.rb
24
+ lib/murano-cli-commander/platform.rb
25
+ lib/murano-cli-commander/runner.rb
26
+ lib/murano-cli-commander/user_interaction.rb
27
+ lib/murano-cli-commander/version.rb
28
+ spec/command_spec.rb
29
+ spec/core_ext/array_spec.rb
30
+ spec/core_ext/object_spec.rb
31
+ spec/help_formatters/terminal_spec.rb
32
+ spec/runner_spec.rb
33
+ spec/spec.opts
34
+ spec/spec_helper.rb
35
+ spec/ui_spec.rb
36
+ tasks/dev_setup.rake
37
+ tasks/docs.rake
38
+ tasks/gemspec.rake
data/README.md ADDED
@@ -0,0 +1,475 @@
1
+ [<img src="https://api.travis-ci.org/commander-rb/commander.svg" alt="Build Status" />](http://travis-ci.org/commander-rb/commander)
2
+ [![Inline docs](http://inch-ci.org/github/commander-rb/commander.svg)](http://inch-ci.org/github/commander-rb/commander)
3
+
4
+ # Commander
5
+
6
+ The complete solution for Ruby command-line executables.
7
+ Commander bridges the gap between other terminal related libraries
8
+ you know and love (OptionParser, HighLine), while providing many new
9
+ features, and an elegant API.
10
+
11
+ ## Features
12
+
13
+ * Easier than baking cookies
14
+ * Parses options using OptionParser
15
+ * Auto-populates struct with options ( no more `{ |v| options[:recursive] = v }` )
16
+ * Auto-generates help documentation via pluggable help formatters
17
+ * Optional default command when none is present
18
+ * Global / Command level options
19
+ * Packaged with two help formatters (Terminal, TerminalCompact)
20
+ * Imports the highline gem for interacting with the terminal
21
+ * Adds additional user interaction functionality
22
+ * Highly customizable progress bar with intuitive, simple usage
23
+ * Multi-word command name support such as `drupal module install MOD`, rather than `drupal module_install MOD`
24
+ * Sexy paging for long bodies of text
25
+ * Support for MacOS text-to-speech
26
+ * Command aliasing (very powerful, as both switches and arguments can be used)
27
+ * Growl notification support for MacOS
28
+ * Use the `commander` executable to initialize a commander driven program
29
+
30
+ ## Installation
31
+
32
+ $ gem install commander
33
+
34
+ ## Quick Start
35
+
36
+ To generate a quick template for a commander app, run:
37
+
38
+ $ commander init yourfile.rb
39
+
40
+ To generate a quick modular style template for a commander app, run:
41
+
42
+ $ commander init --modular yourfile.rb
43
+
44
+ ## Example
45
+
46
+ For more option examples view the `Commander::Command#option` method. Also
47
+ an important feature to note is that action may be a class to instantiate,
48
+ as well as an object, specifying a method to call, so view the RDoc for more information.
49
+
50
+ ### Classic style
51
+
52
+ ```ruby
53
+ require 'rubygems'
54
+ require 'commander/import'
55
+
56
+ # :name is optional, otherwise uses the basename of this executable
57
+ program :name, 'Foo Bar'
58
+ program :version, '1.0.0'
59
+ program :description, 'Stupid command that prints foo or bar.'
60
+
61
+ command :foo do |c|
62
+ c.syntax = 'foobar foo'
63
+ c.description = 'Displays foo'
64
+ c.action do |args, options|
65
+ say 'foo'
66
+ end
67
+ end
68
+
69
+ command :bar do |c|
70
+ c.syntax = 'foobar bar [options]'
71
+ c.description = 'Display bar with optional prefix and suffix'
72
+ c.option '--prefix STRING', String, 'Adds a prefix to bar'
73
+ c.option '--suffix STRING', String, 'Adds a suffix to bar'
74
+ c.action do |args, options|
75
+ options.default :prefix => '(', :suffix => ')'
76
+ say "#{options.prefix}bar#{options.suffix}"
77
+ end
78
+ end
79
+ ```
80
+
81
+ Example output:
82
+
83
+ ```
84
+ $ foobar bar
85
+ # => (bar)
86
+
87
+ $ foobar bar --suffix '}' --prefix '{'
88
+ # => {bar}
89
+ ```
90
+
91
+ ### Modular style
92
+
93
+ **NOTE:** Make sure to use `require 'commander'` rather than `require 'commander/import'`, otherwise Commander methods will still be imported into the global namespace.
94
+
95
+ ```ruby
96
+ require 'rubygems'
97
+ require 'commander'
98
+
99
+ class MyApplication
100
+ include Commander::Methods
101
+
102
+ def run
103
+ program :name, 'Foo Bar'
104
+ program :version, '1.0.0'
105
+ program :description, 'Stupid command that prints foo or bar.'
106
+
107
+ command :foo do |c|
108
+ c.syntax = 'foobar foo'
109
+ c.description = 'Displays foo'
110
+ c.action do |args, options|
111
+ say 'foo'
112
+ end
113
+ end
114
+
115
+ run!
116
+ end
117
+ end
118
+
119
+ MyApplication.new.run if $0 == __FILE__
120
+ ```
121
+
122
+ ### Block style
123
+
124
+ ```ruby
125
+ require 'rubygems'
126
+ require 'commander'
127
+
128
+ Commander.configure do
129
+ program :name, 'Foo Bar'
130
+ program :version, '1.0.0'
131
+ program :description, 'Stupid command that prints foo or bar.'
132
+
133
+ # see classic style example for options
134
+ end
135
+ ```
136
+
137
+ ## HighLine
138
+
139
+ As mentioned above, the highline gem is imported into the global scope. Here
140
+ are some quick examples for how to utilize highline in your commands:
141
+
142
+ ```ruby
143
+ # Ask for password masked with '*' character
144
+ ask("Password: ") { |q| q.echo = "*" }
145
+
146
+ # Ask for password
147
+ ask("Password: ") { |q| q.echo = false }
148
+
149
+ # Ask if the user agrees (yes or no)
150
+ agree("Do something?")
151
+
152
+ # Asks on a single line (note the space after ':')
153
+ ask("Name: ")
154
+
155
+ # Asks with new line after "Description:"
156
+ ask("Description:")
157
+
158
+ # Calls Date#parse to parse the date string passed
159
+ ask("Birthday? ", Date)
160
+
161
+ # Ensures Integer is within the range specified
162
+ ask("Age? ", Integer) { |q| q.in = 0..105 }
163
+
164
+ # Asks for a list of strings, converts to array
165
+ ask("Fav colors?", Array)
166
+ ```
167
+
168
+ ## HighLine & Interaction Additions
169
+
170
+ In addition to highline's fantastic choice of methods, commander adds the
171
+ following methods to simplify common tasks:
172
+
173
+ ```ruby
174
+ # Ask for password
175
+ password
176
+
177
+ # Ask for password with specific message and mask character
178
+ password "Enter your password please:", '-'
179
+
180
+ # Ask for CLASS, which may be any valid class responding to #parse. Date, Time, Array, etc
181
+ names = ask_for_array 'Names: '
182
+ bday = ask_for_date 'Birthday?: '
183
+
184
+ # Simple progress bar (Commander::UI::ProgressBar)
185
+ uris = %w[
186
+ http://vision-media.ca
187
+ http://google.com
188
+ http://yahoo.com
189
+ ]
190
+ progress uris do |uri|
191
+ res = open uri
192
+ # Do something with response
193
+ end
194
+
195
+ # 'Log' action to stdout
196
+ log "create", "path/to/file.rb"
197
+
198
+ # Enable paging of output after this point
199
+ enable_paging
200
+
201
+ # Ask editor for input (EDITOR environment variable or whichever is available: TextMate, vim, vi, emacs, nano, pico)
202
+ ask_editor
203
+
204
+ # Ask editor, supplying initial text
205
+ ask_editor 'previous data to update'
206
+
207
+ # Ask editor, preferring a specific editor
208
+ ask_editor 'previous data', 'vim'
209
+
210
+ # Choose from an array of elements
211
+ choice = choose("Favorite language?", :ruby, :perl, :js)
212
+
213
+ # Alter IO for the duration of the block
214
+ io new_input, new_output do
215
+ new_input_contents = $stdin.read
216
+ puts new_input_contents # outputs to new_output stream
217
+ end
218
+ # $stdin / $stdout reset back to original streams
219
+
220
+ # Speech synthesis
221
+ speak 'What is your favorite food? '
222
+ food = ask 'favorite food?: '
223
+ speak "Wow, I like #{food} too. We have so much in common."
224
+ speak "I like #{food} as well!", "Victoria", 190
225
+
226
+ # Execute arbitrary applescript
227
+ applescript 'foo'
228
+
229
+ # Converse with speech recognition server
230
+ case converse 'What is the best food?', :cookies => 'Cookies', :unknown => 'Nothing'
231
+ when :cookies
232
+ speak 'o.m.g. you are awesome!'
233
+ else
234
+ case converse 'That is lame, shall I convince you cookies are the best?', :yes => 'Ok', :no => 'No', :maybe => 'Maybe another time'
235
+ when :yes
236
+ speak 'Well you see, cookies are just fantastic, they melt in your mouth.'
237
+ else
238
+ speak 'Ok then, bye.'
239
+ end
240
+ end
241
+ ```
242
+
243
+ ## Growl Notifications
244
+
245
+ Commander provides methods for displaying Growl notifications. To use these
246
+ methods you need to install http://github.com/tj/growl which utilizes
247
+ the [growlnotify](http://growl.info/extras.php#growlnotify) executable. Note that
248
+ growl is auto-imported by Commander when available, no need to require.
249
+
250
+ ```ruby
251
+ # Display a generic Growl notification
252
+ notify 'Something happened'
253
+
254
+ # Display an 'info' status notification
255
+ notify_info 'You have #{emails.length} new email(s)'
256
+
257
+ # Display an 'ok' status notification
258
+ notify_ok 'Gems updated'
259
+
260
+ # Display a 'warning' status notification
261
+ notify_warning '1 gem failed installation'
262
+
263
+ # Display an 'error' status notification
264
+ notify_error "Gem #{name} failed"
265
+ ```
266
+
267
+ ## Commander Goodies
268
+
269
+ ### Option Defaults
270
+
271
+ The options struct passed to `#action` provides a `#default` method, allowing you
272
+ to set defaults in a clean manner for options which have not been set.
273
+
274
+ ```ruby
275
+ command :foo do |c|
276
+ c.option '--interval SECONDS', Integer, 'Interval in seconds'
277
+ c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
278
+ c.action do |args, options|
279
+ options.default \
280
+ :interval => 2,
281
+ :timeout => 60
282
+ end
283
+ end
284
+ ```
285
+
286
+ ### Command Aliasing
287
+
288
+ Aliases can be created using the `#alias_command` method like below:
289
+
290
+ ```ruby
291
+ command :'install gem' do |c|
292
+ c.action { puts 'foo' }
293
+ end
294
+ alias_command :'gem install', :'install gem'
295
+ ```
296
+
297
+ Or more complicated aliases can be made, passing any arguments
298
+ as if it was invoked via the command line:
299
+
300
+ ```ruby
301
+ command :'install gem' do |c|
302
+ c.syntax = 'install gem <name> [options]'
303
+ c.option '--dest DIR', String, 'Destination directory'
304
+ c.action { |args, options| puts "installing #{args.first} to #{options.dest}" }
305
+ end
306
+ alias_command :update, :'install gem', 'rubygems', '--dest', 'some_path'
307
+ ```
308
+
309
+ ```
310
+ $ foo update
311
+ # => installing rubygems to some_path
312
+ ```
313
+
314
+ ### Command Defaults
315
+
316
+ Although working with a command executable framework provides many
317
+ benefits over a single command implementation, sometimes you still
318
+ want the ability to create a terse syntax for your command. With that
319
+ in mind we may use `#default_command` to help with this. Considering
320
+ our previous `:'install gem'` example:
321
+
322
+ ```ruby
323
+ default_command :update
324
+ ```
325
+
326
+ ```
327
+ $ foo
328
+ # => installing rubygems to some_path
329
+ ```
330
+
331
+ Keeping in mind that commander searches for the longest possible match
332
+ when considering a command, so if you were to pass arguments to foo
333
+ like below, expecting them to be passed to `:update`, this would be incorrect,
334
+ and would end up calling `:'install gem'`, so be careful that the users do
335
+ not need to use command names within the arguments.
336
+
337
+ ```
338
+ $ foo install gem
339
+ # => installing to
340
+ ```
341
+
342
+ ### Long descriptions
343
+
344
+ If you need to have a long command description, keep your short description under `summary`, and consider multi-line strings for `description`:
345
+
346
+ ```ruby
347
+ program :summary, 'Stupid command that prints foo or bar.'
348
+ program :description, %q(
349
+ #{c.summary}
350
+
351
+ More information about that stupid command that prints foo or bar.
352
+
353
+ And more
354
+ )
355
+ ```
356
+
357
+ ### Additional Global Help
358
+
359
+ Arbitrary help can be added using the following `#program` symbol:
360
+
361
+ ```ruby
362
+ program :help, 'Author', 'TJ Holowaychuk <tj@vision-media.ca>'
363
+ ```
364
+
365
+ Which will output the rest of the help doc, along with:
366
+
367
+ AUTHOR:
368
+
369
+ TJ Holowaychuk <tj@vision-media.ca>
370
+
371
+ ### Global Options
372
+
373
+ Although most switches will be at the command level, several are available by
374
+ default at the global level, such as `--version`, and `--help`. Using
375
+ `#global_option` you can add additional global options:
376
+
377
+ ```ruby
378
+ global_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }
379
+ ```
380
+
381
+ This method accepts the same syntax as `Commander::Command#option` so check it out for documentation.
382
+
383
+ All global options regardless of providing a block are accessable at the command level. This
384
+ means that instead of the following:
385
+
386
+ ```ruby
387
+ global_option('--verbose') { $verbose = true }
388
+ ...
389
+ c.action do |args, options|
390
+ say 'foo' if $verbose
391
+ ...
392
+ ```
393
+
394
+ You may:
395
+
396
+ ```ruby
397
+ global_option '--verbose'
398
+ ...
399
+ c.action do |args, options|
400
+ say 'foo' if options.verbose
401
+ ...
402
+ ```
403
+
404
+ ### Formatters
405
+
406
+ Two core formatters are currently available, the default `Terminal` formatter
407
+ as well as `TerminalCompact`. To utilize a different formatter simply use
408
+ `:help_formatter` like below:
409
+
410
+ ```ruby
411
+ program :help_formatter, Commander::HelpFormatter::TerminalCompact
412
+ ```
413
+
414
+ Or utilize the help formatter aliases:
415
+
416
+ ```ruby
417
+ program :help_formatter, :compact
418
+ ```
419
+
420
+ This abstraction could be utilized to generate HTML documentation for your executable.
421
+
422
+ ### Tracing
423
+
424
+ By default the `-t` and `--trace` global options are provided to allow users to get a backtrace to aid debugging.
425
+
426
+ You can disable these options:
427
+
428
+ ```ruby
429
+ never_trace!
430
+ ```
431
+
432
+ Or make it always on:
433
+
434
+ ```ruby
435
+ always_trace!
436
+ ```
437
+
438
+ ## Tips
439
+
440
+ When adding a global or command option, OptionParser implicitly adds a small
441
+ switch even when not explicitly created, for example `-c` will be the same as
442
+ `--config` in both examples, however `-c` will only appear in the documentation
443
+ when explicitly assigning it.
444
+
445
+ ```ruby
446
+ global_option '-c', '--config FILE'
447
+ global_option '--config FILE'
448
+ ```
449
+
450
+ ## ASCII Tables
451
+
452
+ For feature rich ASCII tables for your terminal app check out the terminal-table gem at http://github.com/tj/terminal-table
453
+
454
+ +----------+-------+----+--------+-----------------------+
455
+ | Terminal | Table | Is | Wicked | Awesome |
456
+ +----------+-------+----+--------+-----------------------+
457
+ | | | | | get it while its hot! |
458
+ +----------+-------+----+--------+-----------------------+
459
+
460
+ ## Running Specifications
461
+
462
+ $ rake spec
463
+
464
+ OR
465
+
466
+ $ spec --color spec
467
+
468
+ ## Contrib
469
+
470
+ Feel free to fork and request a pull, or submit a ticket
471
+ http://github.com/commander-rb/commander/issues
472
+
473
+ ## License
474
+
475
+ This project is available under the MIT license. See LICENSE for details.