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 +61 -44
- data/examples/thor_style/bare.rb +1 -1
- data/examples/thor_style/hello_world.rb +1 -1
- data/examples/thor_style/kitchen_sink.rb +3 -3
- data/examples/thor_style/nested.rb +1 -1
- data/examples/thor_style/printer.rb +2 -2
- data/lib/optix/version.rb +1 -1
- data/lib/optix.rb +9 -1
- metadata +12 -12
data/README.md
CHANGED
@@ -1,4 +1,4 @@
|
|
1
|
-
[](https://travis-ci.org/busyloop/optix)
|
1
|
+
[](https://travis-ci.org/busyloop/optix) [](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::
|
38
|
+
class Printer < Optix::Cli
|
39
39
|
|
40
|
-
# Declare global
|
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
|
98
|
-
|
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
|
-
|
101
|
-
|
102
|
-
|
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
|
108
|
-
then the resulting
|
109
|
-
|
110
|
-
|
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::
|
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::
|
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::
|
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::
|
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::
|
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
|
255
|
+
Takes a block (DSL-enabled) to declare the root-command.
|
249
256
|
|
250
|
-
|
251
|
-
|
252
|
-
|
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::
|
267
|
+
class Frobnitz < Optix::Cli
|
261
268
|
|
262
|
-
# Declare
|
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
|
-
*
|
296
|
-
|
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::
|
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 `
|
332
|
-
|
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::
|
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.
|
385
|
-
|
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::
|
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::
|
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
|
-
|
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::
|
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::
|
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::
|
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
|
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.
|
540
|
+
1. Your Command-method for `batz`
|
527
541
|
|
528
542
|
## Advanced usage
|
529
543
|
|
530
|
-
Optix
|
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
|
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
|
|
data/examples/thor_style/bare.rb
CHANGED
@@ -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::
|
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::
|
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::
|
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 Printer < Optix::
|
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
|
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
data/lib/optix.rb
CHANGED
@@ -272,7 +272,7 @@ class Optix
|
|
272
272
|
end
|
273
273
|
|
274
274
|
class Optix
|
275
|
-
class
|
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.
|
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-
|
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: &
|
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: *
|
24
|
+
version_requirements: *6024860
|
25
25
|
- !ruby/object:Gem::Dependency
|
26
26
|
name: rake
|
27
|
-
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: *
|
35
|
+
version_requirements: *6023760
|
36
36
|
- !ruby/object:Gem::Dependency
|
37
37
|
name: rspec
|
38
|
-
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: *
|
46
|
+
version_requirements: *6022680
|
47
47
|
- !ruby/object:Gem::Dependency
|
48
48
|
name: simplecov
|
49
|
-
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: *
|
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:
|
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:
|
107
|
+
hash: 4140506293072795034
|
108
108
|
requirements: []
|
109
109
|
rubyforge_project:
|
110
110
|
rubygems_version: 1.8.10
|