optix 1.2.0 → 1.2.1

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.
data/README.md CHANGED
@@ -1,4 +1,4 @@
1
- [![Build Status](https://travis-ci.org/busyloop/optix.png?branch=master)](https://travis-ci.org/busyloop/optix)
1
+ [![Build Status](https://travis-ci.org/busyloop/optix.png?branch=master)](https://travis-ci.org/busyloop/optix) [![Dependency Status](https://gemnasium.com/busyloop/optix.png)](https://gemnasium.com/busyloop/optix)
2
2
 
3
3
  # Optix
4
4
 
@@ -35,9 +35,9 @@ It is intended to be a lighter weight alternative to [Thor](https://github.com/w
35
35
  require 'optix'
36
36
 
37
37
  module Example
38
- class Printer < Optix::CLI
38
+ class Printer < Optix::Cli
39
39
 
40
- # Declare global cli-options
40
+ # Declare global Cli-options
41
41
  cli_root do
42
42
  # A label to be printed on the root help-screen
43
43
  text "I am printer. I print strings to the screen."
@@ -94,20 +94,27 @@ See the `examples/`-folder for more elaborate examples.
94
94
 
95
95
  ## Documentation
96
96
 
97
- A cli is composed by sub-classing `Optix::CLI` and using the DSL
98
- to describe the desired commands, labels and options.
97
+ A Cli is built using the declarative Optix DSL inside the body
98
+ of at least one sub-class of `Optix::Cli`.
99
99
 
100
- At runtime you call `Optix.invoke!(ARGV)` to invoke the parser. It will parse
101
- and validate the input (in this case: ARGV), create an instance of the class
102
- containing the requested method (if any) and call the latter.
100
+ After the declarations have been loaded you invoke the parser
101
+ with a call to `Optix.invoke!(ARGV)`. It will parse and validate
102
+ the input (in this case: ARGV), create an instance of the class
103
+ that contains the requested command-method, and call said method
104
+ with the user-supplied opts and arguments.
103
105
 
104
106
  In case of a validation error Optix displays an adequate
105
107
  error-message and auto-generated help-screen.
106
108
 
107
- If your program contains multiple classes inheriting from `Optix::CLI`
108
- then the resulting cli will be the sum of their parts. You don't have
109
- to pay attention to load-order, an Optix CLI assembles correctly in
110
- any order.
109
+ If your program loads multiple sub-classes of `Optix::Cli`
110
+ then the resulting Cli will be the sum of all declarations in
111
+ any of them.
112
+
113
+ Optix is agnostic towards the order of declarations; a sub-command
114
+ declaration is allowed to appear before its parent. This feature allows
115
+ for very dynamic user interfaces to be generated at runtime, e.g.
116
+ via conditionals or dynamic class-loading.
117
+
111
118
 
112
119
  ### Commands and Sub-Commands
113
120
 
@@ -122,7 +129,7 @@ would look like this:
122
129
  require 'optix'
123
130
 
124
131
  module Example
125
- class HelloWorld < Optix::CLI
132
+ class HelloWorld < Optix::Cli
126
133
 
127
134
  # Declare a command called "world" as child of "hello"
128
135
  parent 'hello'
@@ -159,7 +166,7 @@ Example:
159
166
 
160
167
  ```ruby
161
168
  module Example
162
- class HelperExample < Optix::CLI
169
+ class HelperExample < Optix::Cli
163
170
 
164
171
  # This method becomes a command because it is
165
172
  # preceded by an optix-directive ('parent')
@@ -187,7 +194,7 @@ Short description, displayed in the subcommand-list on the help-screen of the *p
187
194
 
188
195
  ```ruby
189
196
  module Example
190
- class Frobnitz < Optix::CLI
197
+ class Frobnitz < Optix::Cli
191
198
 
192
199
  desc 'Frobnicate a gizmo'
193
200
  def frob(cmd, opts, argv)
@@ -203,7 +210,7 @@ Long description, displayed on the help-screen for this command.
203
210
 
204
211
  ```ruby
205
212
  module Example
206
- class Frobnitz < Optix::CLI
213
+ class Frobnitz < Optix::Cli
207
214
 
208
215
  text "Frobnicate the gizmo by subtle twiddling."
209
216
  text "Please only apply this to 2-state devices or you might bork it."
@@ -222,7 +229,7 @@ Specifies the parent for this command.
222
229
 
223
230
  ```ruby
224
231
  module Example
225
- class Frobnitz < Optix::CLI
232
+ class Frobnitz < Optix::Cli
226
233
 
227
234
  parent 'foo bar', ['desc for foo', 'desc for bar']
228
235
  def batz(cmd, opts, argv)
@@ -245,11 +252,11 @@ end
245
252
 
246
253
  ### cli_root
247
254
 
248
- Takes a block to specify the root-command.
255
+ Takes a block (DSL-enabled) to declare the root-command.
249
256
 
250
- This is a useful shorthand in programs that have
251
- (sub-)commands where it hence doesn't make sense to use
252
- the `parent :none`-syntax.
257
+ You normally use this to specify the help-text that is to be displayed
258
+ on the root-screen (`foo.rb --help`), default opts that should be inherited
259
+ by all commands, and any top-level filters and triggers.
253
260
 
254
261
  ```ruby
255
262
  #!/usr/bin/env ruby
@@ -257,9 +264,9 @@ the `parent :none`-syntax.
257
264
  require 'optix'
258
265
 
259
266
  module Example
260
- class Frobnitz < Optix::CLI
267
+ class Frobnitz < Optix::Cli
261
268
 
262
- # Declare global cli-options (aka "the root-command")
269
+ # Declare the root-command
263
270
  cli_root do
264
271
  # A label to be printed on the root help-screen
265
272
  text "I am printer. I print strings to the screen."
@@ -267,6 +274,12 @@ module Example
267
274
 
268
275
  # An option that is inherited by all commands
269
276
  opt :debug, "Enable debugging", :default => false
277
+
278
+ # Support '--version' and '-v'
279
+ opt :version, "Print version and exit"
280
+ trigger :version do
281
+ puts "Version 1.0"
282
+ end
270
283
  end
271
284
 
272
285
  # Declare a command called "print"
@@ -292,9 +305,11 @@ if __FILE__ == $0
292
305
  end
293
306
  ```
294
307
 
295
- * All sub-commands inherit the `opt`s from their parents.
296
- A `text` declared inside `cli_root` will display on the root help-screen.
297
-
308
+ * If you're composing your Cli from multiple Optix::Cli-subclasses
309
+ then the `cli_root`-block probably feels a bit awkward because
310
+ you're not sure in which class to put it. In that case please take
311
+ a look at `examples/thor_style/kitchen_sink.rb` for the alternative
312
+ singleton-style syntax that is usually a better fit in these scenarios.
298
313
 
299
314
  ### opt
300
315
 
@@ -302,7 +317,7 @@ Declares an option.
302
317
 
303
318
  ```ruby
304
319
  module Example
305
- class Frobnitz < Optix::CLI
320
+ class Frobnitz < Optix::Cli
306
321
 
307
322
  opt :some_name, "some description", :default => 'some_default'
308
323
  def frob(cmd, opts, argv)
@@ -328,8 +343,8 @@ Takes the following optional arguments:
328
343
  **:floats**, **:ios** or **:dates**. If unset, the default argument type is **:flag**, meaning that the argument
329
344
  does not take a parameter. The specification of `:type` is not necessary if a `:default` is given.
330
345
 
331
- * `:default` Set the default value for an argument. Without a default value, the opts-hash passed to `exec{}`
332
- and `filter{}` will have a *nil* value for this key unless the argument is given on the commandline.
346
+ * `:default` Set the default value for an argument. Without a default value, the opts-hash passed to `trigger{}`,
347
+ `filter{}` and your command-method will have a *nil* value for this key unless the argument is given on the commandline.
333
348
  The argument type is derived automatically from the class of the default value given, so specifying a `:type`
334
349
  is not necessary if a `:default` is given. (But see below for an important caveat when `:multi` is specified too.)
335
350
  If the argument is a flag, and the default is set to **true**, then if it is specified on the the commandline
@@ -372,7 +387,7 @@ Describes positional parameters that this command accepts.
372
387
 
373
388
  ```ruby
374
389
  module Example
375
- class Frobnitz < Optix::CLI
390
+ class Frobnitz < Optix::Cli
376
391
  params "<foo> [bar]"
377
392
  def frob(cmd, opts, argv)
378
393
  ...
@@ -381,8 +396,8 @@ module Example
381
396
  end
382
397
  ```
383
398
 
384
- * Note: Optix does **not** validate or inspect positional parameters. This is up to you inside your method.
385
- The value of this command is only used by Optix to display a proper synopsis in the help-screen.
399
+ * Note: Optix does **not** validate or inspect positional parameters.
400
+ Optix only uses the `params`-String to display a proper synopsis in the help-screen.
386
401
 
387
402
  ### depends
388
403
 
@@ -391,7 +406,7 @@ undirected (i.e., mutual) dependencies.
391
406
 
392
407
  ```ruby
393
408
  module Example
394
- class Frobnitz < Optix::CLI
409
+ class Frobnitz < Optix::Cli
395
410
 
396
411
  opt :we, ""
397
412
  opt :are, ""
@@ -410,11 +425,11 @@ Marks two (or more!) options as conflicting.
410
425
 
411
426
  ```ruby
412
427
  module Example
413
- class Frobnitz < Optix::CLI
428
+ class Frobnitz < Optix::Cli
414
429
 
415
430
  opt :force, "Force this operation"
416
431
  opt :no_op, "Dry run, don't actually do anything"
417
- conflict :force, :no_op
432
+ conflicts :force, :no_op
418
433
  def frob(cmd, opts, argv)
419
434
  ...
420
435
  end
@@ -429,7 +444,7 @@ Triggers short-circuit argument parsing for "action-options"
429
444
 
430
445
  ```ruby
431
446
  module Example
432
- class Frobnitz < Optix::CLI
447
+ class Frobnitz < Optix::Cli
433
448
 
434
449
  opt :version, "Print version and exit"
435
450
  trigger :version do
@@ -463,7 +478,7 @@ Filters group functionality that is common to a branch of sub-commands.
463
478
 
464
479
  ```ruby
465
480
  module Example
466
- class Frobnitz < Optix::CLI
481
+ class Frobnitz < Optix::Cli
467
482
 
468
483
  opt :debug, "Enable debugging"
469
484
  filter do |cmd, opts, argv|
@@ -491,11 +506,11 @@ end
491
506
  parsing and display the help-screen.
492
507
 
493
508
 
494
- ### Method signature
509
+ ### Command-Method signature
495
510
 
496
511
  ```ruby
497
512
  module Example
498
- class Frobnitz < Optix::CLI
513
+ class Frobnitz < Optix::Cli
499
514
 
500
515
  def frob(cmd, opts, argv)
501
516
  ...
@@ -509,8 +524,7 @@ end
509
524
  * `opts` (Hash) The options-hash, e.g.: { :debug => true }
510
525
  * `argv` (Array) Positional parameters that your command may have received, e.g.: ['a','b','c']
511
526
 
512
- * You may raise `Optix::HelpNeeded` to abort parsing and display the help-screen.
513
-
527
+ * You may raise `Optix::HelpNeeded` to display the help-screen and exit.
514
528
 
515
529
  ## Chain of execution
516
530
 
@@ -523,14 +537,17 @@ This is the chain of execution when you pass ['foo', 'bar', 'batz'] to `Optix.in
523
537
  1. Filters for `foo` (if any)
524
538
  1. Filters for `bar` (if any)
525
539
  1. Filters for `batz` (if any)
526
- 1. Exec{}-block for `batz`
540
+ 1. Your Command-method for `batz`
527
541
 
528
542
  ## Advanced usage
529
543
 
530
- Optix is very flexible and can be easily shaped into many forms.
544
+ Optix can be shaped into many forms, this document
545
+ only describes the most common usage pattern.
531
546
 
532
547
  Please see the specs, source-code and the examples in `examples/singleton_style`
533
- for advanced usage patterns (no sub-classing, lower level access).
548
+ for advanced usage examples (e.g. integrating Optix w/o sub-classing,
549
+ lower level API, scoping, etc.).
550
+
534
551
 
535
552
  ## Contributing
536
553
 
@@ -3,7 +3,7 @@
3
3
  require 'optix'
4
4
 
5
5
  module Example
6
- class Bare < Optix::CLI
6
+ class Bare < Optix::Cli
7
7
 
8
8
  # Normally Optix would create a sub-command
9
9
  # called "main" for the method below.
@@ -9,7 +9,7 @@
9
9
  require 'optix'
10
10
 
11
11
  module Example
12
- class HelloWorld < Optix::CLI
12
+ class HelloWorld < Optix::Cli
13
13
 
14
14
  # Declare a command called "world" as child of "hello"
15
15
  parent 'hello', "Try me!"
@@ -7,7 +7,7 @@ require 'optix'
7
7
  module KitchenSink
8
8
  # We declare the root-command ("global options") right here
9
9
  # NOTE: This is an alternative (equivalent) syntax to using 'cli_root'
10
- # inside a sub-class of Optix::CLI
10
+ # inside a sub-class of Optix::Cli
11
11
  Optix::command do
12
12
  # Help-screen text
13
13
  text "Kitchen-sink-multi-tool. I can print text, calculate, sing and dance!"
@@ -27,7 +27,7 @@ module KitchenSink
27
27
 
28
28
  # This is our Printer again.
29
29
  # You probably remember him from the first example. ;)
30
- class Printer < Optix::CLI
30
+ class Printer < Optix::Cli
31
31
  desc "Print a string"
32
32
  text "Print a string to the screen"
33
33
  params "<string>"
@@ -44,7 +44,7 @@ module KitchenSink
44
44
  end
45
45
 
46
46
  # A simple Calculator
47
- class Calculator < Optix::CLI
47
+ class Calculator < Optix::Cli
48
48
  # We want all commands in here to be subcommands of
49
49
  # 'calc'. Since 'calc' itself is not declared anywhere
50
50
  # it is implicitly created, and we also pass a description.
@@ -3,7 +3,7 @@
3
3
  require 'optix'
4
4
 
5
5
  module Example
6
- class Frobnitz < Optix::CLI
6
+ class Frobnitz < Optix::Cli
7
7
 
8
8
  parent 'foo bar', ['desc for foo', 'desc for bar']
9
9
 
@@ -3,7 +3,7 @@
3
3
  require 'optix'
4
4
 
5
5
  module Example
6
- class Printer < Optix::CLI
6
+ class Printer < Optix::Cli
7
7
 
8
8
  # Declare global options; the text-label that is printed
9
9
  # for the root-command and one option that is inherited by
@@ -20,7 +20,7 @@ module Example
20
20
  text "Print a string to the screen"
21
21
  opt :count, "Print how many times?", :default => 1
22
22
  params "<string>"
23
- # Your CLI-methods always
23
+ # Your Cli-methods always
24
24
  def print(cmd, opts, argv)
25
25
  if argv.length < 1
26
26
  raise Optix::HelpNeeded
data/lib/optix/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  class Optix
2
- VERSION = "1.2.0"
2
+ VERSION = "1.2.1"
3
3
  end
data/lib/optix.rb CHANGED
@@ -272,7 +272,7 @@ class Optix
272
272
  end
273
273
 
274
274
  class Optix
275
- class CLI
275
+ class Cli
276
276
  class << self
277
277
  def add_context(key, value, &block)
278
278
  @optix_context ||= []
@@ -337,5 +337,13 @@ class Optix
337
337
  end
338
338
  end
339
339
  end
340
+
341
+ # For backwards compatibility
342
+ class CLI < Cli
343
+ def self.inherited(klass)
344
+ warn "[DEPRECATION WARNING] Optix::CLI is deprecated. Please use Optix::Cli instead."
345
+ super
346
+ end
347
+ end
340
348
  end
341
349
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: optix
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.0
4
+ version: 1.2.1
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,11 +9,11 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2012-12-18 00:00:00.000000000 Z
12
+ date: 2012-12-20 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: chronic
16
- requirement: &7466120 !ruby/object:Gem::Requirement
16
+ requirement: &6024860 !ruby/object:Gem::Requirement
17
17
  none: false
18
18
  requirements:
19
19
  - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
21
21
  version: '0'
22
22
  type: :runtime
23
23
  prerelease: false
24
- version_requirements: *7466120
24
+ version_requirements: *6024860
25
25
  - !ruby/object:Gem::Dependency
26
26
  name: rake
27
- requirement: &7465200 !ruby/object:Gem::Requirement
27
+ requirement: &6023760 !ruby/object:Gem::Requirement
28
28
  none: false
29
29
  requirements:
30
30
  - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
32
32
  version: '0'
33
33
  type: :development
34
34
  prerelease: false
35
- version_requirements: *7465200
35
+ version_requirements: *6023760
36
36
  - !ruby/object:Gem::Dependency
37
37
  name: rspec
38
- requirement: &7464000 !ruby/object:Gem::Requirement
38
+ requirement: &6022680 !ruby/object:Gem::Requirement
39
39
  none: false
40
40
  requirements:
41
41
  - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
43
43
  version: '0'
44
44
  type: :development
45
45
  prerelease: false
46
- version_requirements: *7464000
46
+ version_requirements: *6022680
47
47
  - !ruby/object:Gem::Dependency
48
48
  name: simplecov
49
- requirement: &7463020 !ruby/object:Gem::Requirement
49
+ requirement: &6021600 !ruby/object:Gem::Requirement
50
50
  none: false
51
51
  requirements:
52
52
  - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
54
54
  version: '0'
55
55
  type: :development
56
56
  prerelease: false
57
- version_requirements: *7463020
57
+ version_requirements: *6021600
58
58
  description: Optix is an unobtrusive, composable command line parser.
59
59
  email:
60
60
  - moe@busyloop.net
@@ -95,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
95
95
  version: '0'
96
96
  segments:
97
97
  - 0
98
- hash: 540681097072146683
98
+ hash: 4140506293072795034
99
99
  required_rubygems_version: !ruby/object:Gem::Requirement
100
100
  none: false
101
101
  requirements:
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
104
104
  version: '0'
105
105
  segments:
106
106
  - 0
107
- hash: 540681097072146683
107
+ hash: 4140506293072795034
108
108
  requirements: []
109
109
  rubyforge_project:
110
110
  rubygems_version: 1.8.10