optix 1.2.0 → 1.2.1

data/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/busyloop/optix.png?branch=master)](https://travis-ci.org/busyloop/optix)
+[![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)
 
 # Optix
 
@@ -35,9 +35,9 @@ It is intended to be a lighter weight alternative to [Thor](https://github.com/w
 require 'optix'
 
 module Example
-  class Printer < Optix::CLI
+  class Printer < Optix::Cli
 
-    # Declare global cli-options
+    # Declare global Cli-options
     cli_root do
       # A label to be printed on the root help-screen
       text "I am printer. I print strings to the screen."
@@ -94,20 +94,27 @@ See the `examples/`-folder for more elaborate examples.
 
 ## Documentation
 
-A cli is composed by sub-classing `Optix::CLI` and using the DSL
-to describe the desired commands, labels and options.
+A Cli is built using the declarative Optix DSL inside the body
+of at least one sub-class of `Optix::Cli`.
 
-At runtime you call `Optix.invoke!(ARGV)` to invoke the parser. It will parse
-and validate the input (in this case: ARGV), create an instance of the class
-containing the requested method (if any) and call the latter.
+After the declarations have been loaded you invoke the parser
+with a call to `Optix.invoke!(ARGV)`. It will parse and validate
+the input (in this case: ARGV), create an instance of the class
+that contains the requested command-method, and call said method
+with the user-supplied opts and arguments.
 
 In case of a validation error Optix displays an adequate
 error-message and auto-generated help-screen.
 
-If your program contains multiple classes inheriting from `Optix::CLI`
-then the resulting cli will be the sum of their parts. You don't have
-to pay attention to load-order, an Optix CLI assembles correctly in 
-any order.
+If your program loads multiple sub-classes of `Optix::Cli`
+then the resulting Cli will be the sum of all declarations in
+any of them.
+
+Optix is agnostic towards the order of declarations; a sub-command
+declaration is allowed to appear before its parent. This feature allows
+for very dynamic user interfaces to be generated at runtime, e.g.
+via conditionals or dynamic class-loading.
+
 
 ### Commands and Sub-Commands
 
@@ -122,7 +129,7 @@ would look like this:
 require 'optix'
 
 module Example
-  class HelloWorld < Optix::CLI
+  class HelloWorld < Optix::Cli
 
     # Declare a command called "world" as child of "hello"
     parent 'hello'
@@ -159,7 +166,7 @@ Example:
 
 ```ruby
 module Example
-  class HelperExample < Optix::CLI
+  class HelperExample < Optix::Cli
 
     # This method becomes a command because it is
     # preceded by an optix-directive ('parent')
@@ -187,7 +194,7 @@ Short description, displayed in the subcommand-list on the help-screen of the *p
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     desc 'Frobnicate a gizmo'
     def frob(cmd, opts, argv)
@@ -203,7 +210,7 @@ Long description, displayed on the help-screen for this command.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     text "Frobnicate the gizmo by subtle twiddling."
     text "Please only apply this to 2-state devices or you might bork it."
@@ -222,7 +229,7 @@ Specifies the parent for this command.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     parent 'foo bar', ['desc for foo', 'desc for bar']
     def batz(cmd, opts, argv)
@@ -245,11 +252,11 @@ end
 
 ### cli_root
 
-Takes a block to specify the root-command.
+Takes a block (DSL-enabled) to declare the root-command.
 
-This is a useful shorthand in programs that have
-(sub-)commands where it hence doesn't make sense to use
-the `parent :none`-syntax.
+You normally use this to specify the help-text that is to be displayed
+on the root-screen (`foo.rb --help`), default opts that should be inherited
+by all commands, and any top-level filters and triggers.
 
 ```ruby
 #!/usr/bin/env ruby
@@ -257,9 +264,9 @@ the `parent :none`-syntax.
 require 'optix'
 
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
-    # Declare global cli-options (aka "the root-command")
+    # Declare the root-command
     cli_root do
       # A label to be printed on the root help-screen
       text "I am printer. I print strings to the screen."
@@ -267,6 +274,12 @@ module Example
       
       # An option that is inherited by all commands
       opt :debug, "Enable debugging", :default => false
+
+      # Support '--version' and '-v'
+      opt :version, "Print version and exit"
+      trigger :version do
+        puts "Version 1.0"
+      end
     end
     
     # Declare a command called "print"
@@ -292,9 +305,11 @@ if __FILE__ == $0
 end
 ```
 
-* All sub-commands inherit the `opt`s from their parents.
-  A `text` declared inside `cli_root` will display on the root help-screen.
-
+* If you're composing your Cli from multiple Optix::Cli-subclasses
+  then the `cli_root`-block probably feels a bit awkward because
+  you're not sure in which class to put it. In that case please take
+  a look at `examples/thor_style/kitchen_sink.rb` for the alternative
+  singleton-style syntax that is usually a better fit in these scenarios.
 
 ### opt
 
@@ -302,7 +317,7 @@ Declares an option.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     opt :some_name, "some description", :default => 'some_default'
     def frob(cmd, opts, argv)
@@ -328,8 +343,8 @@ Takes the following optional arguments:
     **:floats**, **:ios** or **:dates**. If unset, the default argument type is **:flag**, meaning that the argument
     does not take a parameter. The specification of `:type` is not necessary if a `:default` is given.
 
-  * `:default` Set the default value for an argument. Without a default value, the opts-hash passed to `exec{}`
-    and `filter{}` will have a *nil* value for this key unless the argument is given on the commandline.
+  * `:default` Set the default value for an argument. Without a default value, the opts-hash passed to `trigger{}`,
+    `filter{}` and your command-method will have a *nil* value for this key unless the argument is given on the commandline.
     The argument type is derived automatically from the class of the default value given, so specifying a `:type`
     is not necessary if a `:default` is given. (But see below for an important caveat when `:multi` is specified too.)
     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.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
     params "<foo> [bar]"
     def frob(cmd, opts, argv)
       ...
@@ -381,8 +396,8 @@ module Example
 end
 ```
 
-* Note: Optix does **not** validate or inspect positional parameters. This is up to you inside your method.
-  The value of this command is only used by Optix to display a proper synopsis in the help-screen.
+* Note: Optix does **not** validate or inspect positional parameters.
+  Optix only uses the `params`-String to display a proper synopsis in the help-screen.
 
 ### depends
 
@@ -391,7 +406,7 @@ undirected (i.e., mutual) dependencies.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     opt :we,     ""
     opt :are,    ""
@@ -410,11 +425,11 @@ Marks two (or more!) options as conflicting.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     opt :force, "Force this operation"
     opt :no_op, "Dry run, don't actually do anything"
-    conflict :force, :no_op
+    conflicts :force, :no_op
     def frob(cmd, opts, argv)
       ...
     end
@@ -429,7 +444,7 @@ Triggers short-circuit argument parsing for "action-options"
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     opt :version, "Print version and exit"
     trigger :version do
@@ -463,7 +478,7 @@ Filters group functionality that is common to a branch of sub-commands.
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     opt :debug, "Enable debugging"
     filter do |cmd, opts, argv|
@@ -491,11 +506,11 @@ end
   parsing and display the help-screen.
 
 
-### Method signature
+### Command-Method signature
 
 ```ruby
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     def frob(cmd, opts, argv)
       ...
@@ -509,8 +524,7 @@ end
     * `opts` (Hash) The options-hash, e.g.: { :debug => true }
     * `argv` (Array) Positional parameters that your command may have received, e.g.: ['a','b','c']
 
-* You may raise `Optix::HelpNeeded` to abort parsing and display the help-screen.
-
+* You may raise `Optix::HelpNeeded` to display the help-screen and exit.
 
 ## Chain of execution
 
@@ -523,14 +537,17 @@ This is the chain of execution when you pass ['foo', 'bar', 'batz'] to `Optix.in
   1. Filters for `foo` (if any)
   1. Filters for `bar` (if any)
   1. Filters for `batz` (if any)
-  1. Exec{}-block for `batz`
+  1. Your Command-method for `batz`
 
 ## Advanced usage
 
-Optix is very flexible and can be easily shaped into many forms.
+Optix can be shaped into many forms, this document
+only describes the most common usage pattern.
 
 Please see the specs, source-code and the examples in `examples/singleton_style`
-for advanced usage patterns (no sub-classing, lower level access).
+for advanced usage examples (e.g. integrating Optix w/o sub-classing,
+lower level API, scoping, etc.).
+
 
 ## Contributing
 

data/examples/thor_style/bare.rb

@@ -3,7 +3,7 @@
 require 'optix'
 
 module Example
-  class Bare < Optix::CLI
+  class Bare < Optix::Cli
 
     # Normally Optix would create a sub-command
     # called "main" for the method below. 

data/examples/thor_style/hello_world.rb

@@ -9,7 +9,7 @@
 require 'optix'
 
 module Example
-  class HelloWorld < Optix::CLI
+  class HelloWorld < Optix::Cli
 
     # Declare a command called "world" as child of "hello"
     parent 'hello', "Try me!"

data/examples/thor_style/kitchen_sink.rb

@@ -7,7 +7,7 @@ require 'optix'
 module KitchenSink
   # We declare the root-command ("global options") right here
   # NOTE: This is an alternative (equivalent) syntax to using 'cli_root'
-  #       inside a sub-class of Optix::CLI
+  #       inside a sub-class of Optix::Cli
   Optix::command do
     # Help-screen text
     text "Kitchen-sink-multi-tool. I can print text, calculate, sing and dance!"
@@ -27,7 +27,7 @@ module KitchenSink
 
   # This is our Printer again.
   # You probably remember him from the first example. ;)
-  class Printer < Optix::CLI
+  class Printer < Optix::Cli
     desc "Print a string"
     text "Print a string to the screen"
     params "<string>"
@@ -44,7 +44,7 @@ module KitchenSink
   end
 
   # A simple Calculator
-  class Calculator < Optix::CLI
+  class Calculator < Optix::Cli
     # We want all commands in here to be subcommands of
     # 'calc'. Since 'calc' itself is not declared anywhere
     # it is implicitly created, and we also pass a description.

data/examples/thor_style/nested.rb

@@ -3,7 +3,7 @@
 require 'optix'
 
 module Example
-  class Frobnitz < Optix::CLI
+  class Frobnitz < Optix::Cli
 
     parent 'foo bar', ['desc for foo', 'desc for bar']
 

data/examples/thor_style/printer.rb

@@ -3,7 +3,7 @@
 require 'optix'
 
 module Example
-  class Printer < Optix::CLI
+  class Printer < Optix::Cli
 
     # Declare global options; the text-label that is printed
     # for the root-command and one option that is inherited by
@@ -20,7 +20,7 @@ module Example
     text "Print a string to the screen"
     opt :count, "Print how many times?", :default => 1
     params "<string>"
-    # Your CLI-methods always 
+    # Your Cli-methods always 
     def print(cmd, opts, argv)
       if argv.length < 1
         raise Optix::HelpNeeded

data/lib/optix/version.rb

@@ -1,3 +1,3 @@
 class Optix
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

data/lib/optix.rb

@@ -272,7 +272,7 @@ class Optix
 end
 
 class Optix
-  class CLI
+  class Cli
     class << self
       def add_context(key, value, &block)
         @optix_context ||= []
@@ -337,5 +337,13 @@ class Optix
       end
     end
   end
+
+  # For backwards compatibility
+  class CLI < Cli
+    def self.inherited(klass)
+      warn "[DEPRECATION WARNING] Optix::CLI is deprecated. Please use Optix::Cli instead."
+      super
+    end
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: optix
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-18 00:00:00.000000000 Z
+date: 2012-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chronic
-  requirement: &7466120 !ruby/object:Gem::Requirement
+  requirement: &6024860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *7466120
+  version_requirements: *6024860
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &7465200 !ruby/object:Gem::Requirement
+  requirement: &6023760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *7465200
+  version_requirements: *6023760
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &7464000 !ruby/object:Gem::Requirement
+  requirement: &6022680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *7464000
+  version_requirements: *6022680
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &7463020 !ruby/object:Gem::Requirement
+  requirement: &6021600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *7463020
+  version_requirements: *6021600
 description: Optix is an unobtrusive, composable command line parser.
 email:
 - moe@busyloop.net
@@ -95,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 540681097072146683
+      hash: 4140506293072795034
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 540681097072146683
+      hash: 4140506293072795034
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10