optix 1.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in optix.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (C) 2012, moe@busyloop.net
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, pulverize, distribute,
+synergize, compost, defenestrate, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+If the Author of the Software (the "Author") needs a place to crash and
+you have a sofa available, you should maybe give the Author a break and
+let him sleep on your couch.
+
+If you are caught in a dire situation wherein you only have enough time
+to save one person out of a group, and the Author is a member of that
+group, you must save the Author.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO BLAH BLAH BLAH ISN'T IT FUNNY
+HOW UPPER-CASE MAKES IT SOUND LIKE THE LICENSE IS ANGRY AND SHOUTING AT YOU.
+

data/README.md

@@ -0,0 +1,431 @@
+# Optix
+
+Optix is an unobtrusive, composable command line parser based on Trollop.
+
+
+## Features
+
+* Lightweight, unobtrusive syntax.
+  No subclassing or introduction of dependencies.
+
+* Supports subcommands such as `git remote show origin` with arbitrary nesting.
+
+* Subcommands inherit from their parent. Common options (such as '--debug' or '--loglevel')
+  need to be declared only once to make them available to an entire branch.
+
+* Stands on the shoulders of [Trollop](http://trollop.rubyforge.org) (by William Morgan), one of the most complete and robust
+  option-parser implementations ever created.
+
+* Automatic validation and help-screens.
+
+* Strong test-suite.
+
+## Installation
+
+    $ gem install optix
+
+## Example
+
+```ruby
+#!/usr/bin/env ruby
+require 'optix'
+
+module Example
+  module Printer
+    # Declare the "root"-command 
+    Optix::command do
+      text "I am printer. I print strings to the screen."
+      text "Please invoke one of my not so many sub-commands."
+  
+      # Declare a global option (all subcommands inherit this)
+      opt :debug, "Enable debugging", :default => false
+    end
+  
+    # Declare sub-command 
+    Optix::command 'print' do
+      desc "Print a string"
+      text "Print a string to the screen"
+      params "<string>"
+  
+      opt :count, "Print how many times?", :default => 1
+  
+      # This block is invoked when validations pass.
+      exec do |cmd, opts, argv|
+        if argv.length < 1
+          raise Optix::HelpNeeded
+        end
+
+        puts "DEBUGGING IS ENABLED!" if opts[:debug]
+        (1..opts[:count]).each do
+          puts argv.join(' ') 
+        end
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  # Perform the actual parsing and execution.
+  Optix.invoke!(ARGV)
+end
+```
+
+The above code in action:
+
+```
+$ ./printer.rb --help
+
+Usage: ./printer.rb <subcommand>
+ 
+I am printer. I print strings to the screen.
+Please invoke one of my not so many sub-commands.
+ 
+Options:
+  --debug, -d:   Enable debugging
+   --help, -h:   Show this message
+
+Commands:
+   print   Print a string
+ 
+```
+
+See the `examples/`-folder for more elaborate examples.
+
+## Documentation
+
+### Commands and Sub-Commands
+
+Commands may be declared anywhere, at any time, in any order.
+Declaring the "root"-command looks like this:
+
+```ruby
+require 'optix'
+
+Optix::command do
+  # opts, triggers, etc
+end
+```
+
+Now, let's add a sub-command:
+
+```ruby
+Optix::command 'sub' do
+  # opts, triggers, etc
+end
+```
+
+And finally, a sub-sub command:
+
+```ruby
+Optix::command 'sub sub' do
+  # opts, triggers, etc
+end
+```
+
+Remember: Optix doesn't care about the order of declarations.
+The `sub sub` command may be declared prior to the `sub` command.
+ 
+A common pattern is to insert your `Optix::command` blocks directly
+at the module level so they get invoked during class-loading.
+This way your CLI assembles itself automatically and the
+command-hierarchy mirrors the modules/classes that
+are actually loaded.
+
+
+### Optix::command DSL
+
+Within `Optix::command` the following directives are available:
+
+### desc
+
+Short description, displayed in the subcommand-list on the help-screen of the *parent* command.
+
+```ruby
+Optix::command "frobnitz" do
+  desc "Frobnicates the gizmo"
+end
+```
+
+### text
+
+Long description, displayed on the help-screen for this command.
+
+```ruby
+Optix::command "frobnitz" do
+  text "Frobnicate the gizmo by subtle twiddling."
+  text "Please only apply this to 2-state devices or you might bork it."
+end
+```
+
+* May be called multiple times for a multi-line description.
+
+
+### opt
+
+Declares an option.
+
+```ruby
+Optix::command do
+  opt :some_name, "some description", :default => 'some_default'
+end
+```
+
+Takes the following optional arguments:
+
+  * `:long` Specify the long form of the argument, i.e. the form with two dashes. 
+    If unspecified, will be automatically derived based on the argument name by turning the name
+    option into a string, and replacing any _'s by -'s.
+
+  * `:short` Specify the short form of the argument, i.e. the form with one dash.
+    If unspecified, will be automatically derived from argument name.
+
+  * `:type` Require that the argument take a parameter or parameters of a given type. For a *single parameter*,
+    the value can be one of **:int**, **:integer**, **:string**, **:double**, **:float**, **:io**, **:date**,
+    or a corresponding Ruby class (e.g. **Integer** for **:int**).
+    For *multiple-argument parameters*, the value can be one of **:ints**, **:integers**, **:strings**, **:doubles**,
+    **: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.
+    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
+    the value will be **false**.
+
+  * `:required` If set to **true**, the argument must be provided on the commandline.
+
+  * `:multi` If set to **true**, allows multiple occurrences of the option on the commandline. 
+    Otherwise, only a single instance of the option is allowed.
+
+    Note that there are two types of argument multiplicity: an argument
+    can take multiple values, e.g. "--arg 1 2 3". An argument can also
+    be allowed to occur multiple times, e.g. "--arg 1 --arg 2".
+    
+    Arguments that take multiple values should have a `:type` parameter
+    or a `:default` value of an array of the correct type (e.g. [String]).
+    
+    The value of this argument will be an array of the parameters on the
+    commandline.
+    
+    Arguments that can occur multiple times should be marked with
+    `:multi => true`. The value of this argument will also be an array.
+    In contrast with regular non-multi options, if not specified on
+    the commandline, the default value will be [], not nil.
+    
+    These two attributes can be combined (e.g. **:type => :strings**,
+    **:multi => true**), in which case the value of the argument will be
+    an array of arrays.
+    
+    There's one ambiguous case to be aware of: when `:multi` is **true** and a
+    `:default` is set to an array (of something), it's ambiguous whether this
+    is a multi-value argument as well as a multi-occurrence argument.
+    In thise case, we assume that it's not a multi-value argument.
+    If you want a multi-value, multi-occurrence argument with a default
+    value, you must specify `:type` as well.
+
+### params
+
+Describes positional parameters that this command accepts.
+
+```ruby
+Optix::command do
+  params "<foo> [bar]"
+end
+```
+
+* Note: Optix does **not** validate or inspect positional parameters at all (this is your job, inside exec{}).
+  The value of this command is only used to display a proper synopsis in the help-screen.
+
+### depends
+
+Marks two (or more!) options as requiring each other. Only handles
+undirected (i.e., mutual) dependencies.
+
+```ruby
+Optix::command do
+  opt :we,     ""
+  opt :are,    ""
+  opt :family, ""
+  depends :we, :are, :family
+end
+```
+
+### conflicts
+
+Marks two (or more!) options as conflicting.
+
+```ruby
+Optix::command do
+  opt :force, "Force this operation"
+  opt :no_op, "Dry run, don't actually do anything"
+  conflict :force, :no_op
+end
+```
+
+### trigger
+
+Triggers allow to short-circuit argument parsing for "action-options"
+(options that directly trigger an action) such as `--version`.
+
+```ruby
+Optix::command do
+  opt :version, "Print version and exit"
+  trigger :version do
+    puts "Version 1.0"
+  end
+end
+```
+
+* Triggers fire *before* validation.
+
+* Parsing stops after a trigger has fired.
+
+* A trigger can only be bound to an existing `opt`. I.e. you must first
+  declare `opt :version` before you can bind a trigger with `trigger
+  :version`.
+
+* A trigger may be bound to multiple options like so: `trigger [:version,
+  :other, :etc] do ...`
+
+* You may raise `Optix::HelpNeeded` inside your trigger to abort
+  parsing and display the help-screen.
+
+
+### filter
+
+Filters allow to group functionality that is common to a branch of subcommands.
+
+```ruby
+Optix::command do
+  opt :debug, "Enable debugging"
+  filter do |cmd, opts, argv|
+    if opts[:debug]
+      # .. enable debugging ..
+    end
+  end
+end
+```
+
+* Filters fire *after* validation, for each command in the chain.
+
+* Parsing continues normally after a filter has fired.
+
+* Your block receives three arguments:
+    * `cmd` (Array) The full command that was executed, e.g.: ['foo', 'bar', 'baz']
+    * `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` inside your filter to abort
+  parsing and display the help-screen.
+
+
+### exec
+
+The exec-block is called when your command is invoked, after validation
+passed. It should contain (or invoke) your actual business logic.
+
+```ruby
+Optix::command do
+  exec do |cmd, opts, argv|
+    if opts[:debug]
+      # .. enable debugging ..
+    end
+  end
+end
+```
+
+* Your block receives three arguments:
+    * `cmd` (Array) The full command that was executed, e.g.: ['foo', 'bar', 'baz']
+    * `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` inside your exec-block to abort
+  parsing and display the help-screen.
+
+
+## Chain of execution
+
+This is the chain of execution when you pass ['foo', 'bar', 'batz'] to `Optix.invoke!`:
+
+  1. Triggers for `foo` (if any, execution stops if a trigger fires)
+  1. Triggers for `bar` (if any, execution stops if a trigger fires)
+  1. Triggers for `batz` (if any, execution stops if a trigger fires)
+  1. Validation
+  1. Filters for `foo` (if any)
+  1. Filters for `bar` (if any)
+  1. Filters for `batz` (if any)
+  1. Exec{}-block for `batz`
+
+
+
+## Scopes
+
+In rare cases you may want to have multiple independent Optix command-trees in a single app.
+This can be achieved by passing a scope-name to your command-declarations, like so:
+
+```ruby
+# Declare root-command in the :default scope
+Optix::command '', :default do
+  # opts, triggers, etc
+end
+
+# Declare root-command in another, independent scope
+Optix::command '', :other_scope do
+end
+
+# Declare a sub-command in the other scope
+Optix::command 'sub', :other_scope do
+end
+
+# Then either invoke the :default scope
+Optix.invoke!(ARGV)
+# ...or...
+Optix.invoke!(ARGV, :other_scope)
+```
+
+## Re-initialization
+
+In even rarer cases you may need to reset Optix at runtime.
+To make Optix forget all scopes, configuration and commands, invoke:
+
+`Optix.reset!`
+
+
+## Contributing
+
+Patches are welcome, especially bugfixes.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Copyright (C) 2012, moe@busyloop.net
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, pulverize, distribute,
+synergize, compost, defenestrate, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+If the Author of the Software (the "Author") needs a place to crash and
+you have a sofa available, you should maybe give the Author a break and
+let him sleep on your couch.
+
+If you are caught in a dire situation wherein you only have enough time
+to save one person out of a group, and the Author is a member of that
+group, you must save the Author.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO BLAH BLAH BLAH ISN'T IT FUNNY HOW UPPER-CASE MAKES IT
+SOUND LIKE THE LICENSE IS ANGRY AND SHOUTING AT YOU.
+

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+task :default => :test
+
+RSpec::Core::RakeTask.new("test:spec") do |t|
+    t.pattern = 'spec/*_spec.rb'
+    t.rcov = false
+    #t.rspec_opts = '-b -c -f progress --tag ~benchmark'
+    t.rspec_opts = '-b -c -f documentation --tag ~benchmark'
+end
+
+RSpec::Core::RakeTask.new("test:benchmark") do |t|
+    t.pattern = 'spec/*.rb'
+    t.rcov = false
+    t.rspec_opts = '-b -c -f documentation --tag benchmark'
+end
+
+
+namespace :test do
+  task :coverage do
+    #require 'cover_me'
+    #CoverMe.complete!
+  end
+end
+
+desc 'Run full test suite'
+task :test => [ 'test:spec', 'test:coverage' ]

data/examples/filetool.rb

@@ -0,0 +1,188 @@
+require 'optix'
+
+#
+# Example application to demonstrate Optix.
+#
+# The easiest way to get started is to download this file
+# and actually run it. Play around, try invoking '--help',
+# '-v', '--version' and the subcommands. 
+#
+# Then come back here to learn how it's done. :)
+#
+module Example
+  class FileTool
+    # Declare the "root" command
+    # Also declaring the first-level sub-commands right here.
+    # Just like the root-command these commands can not be invoked
+    # directly (because they have sub-commands). Their declaration
+    # is not mandatory, but by declaring them explicitly we can add
+    # some useful help-texts to aid the user.
+    Optix::command do
+      # Let's have a nice description
+      text "This is FileTool, a little example application to demonstrate Optix."
+      text "It's safe to play around with. All operations are no-ops."
+      text "Your filesystem is never actually modified!"
+      text ""
+      text "Invoke me with one of the sub-commands to perform a dummy-operation."
+
+      # Note: Options are recursively inherited by sub-commands.
+      # Thus, any option we declare here will also be available
+      # in all sub-commands.
+      opt :debug, "Enable debugging", :default => false
+      opt :version, "Print version and exit"
+
+      # Triggers fire immediately, before validation.
+      #
+      # This one short-circuits the '--version' and '-v' opts.
+      # We want to print/exit immediately when we encounter
+      # them, regardless of other opts or subcommands.
+      #
+      # NOTE: Triggers can only bind to existing opts.
+      #       Make sure to always declare the 'opt' before
+      #       creating a 'trigger' (just like in this example).
+      trigger [:version] do
+        puts "Version 1.0"
+        # parsing stops after a trigger has fired.
+      end
+
+      # Filters are "pass-through", they fire for
+      # every intermediate sub-command. We use it here
+      # to set up a common debug-mechanism before the
+      # subcommand is invoked.
+      filter do |cmd, opts, argv|
+        if opts[:debug]
+          FileTool.enable_debug!
+        end
+      end
+
+      # Note this command has no exec{}-block.
+      # It would never fire because this command has sub-commands. 
+      # When a command has sub-commands then it can no longer be
+      # invoked directly (that would only lead to confusion and
+      # bad accidents).
+    end
+
+    Optix::command 'file' do
+      desc "Operations on files"
+      text "Please invoke one of the sub-commands to perform a file-operation."
+    end
+
+    Optix::command 'dir' do
+      desc "Operations on directories"
+      text "Please invoke one of the sub-commands to perform a directory-operation."
+    end
+
+    def self.enable_debug!
+      # enable debugging...
+    end
+  end
+end
+
+module Example
+  class FileTool
+    class Move
+      # Here we declare the subcommand 'file move'
+      Optix::command 'file move' do
+        # Short one-liner for the sub-command list in parent help-screen
+        desc "Move a file"
+
+        # Verbose description for the help-screen
+        text "Move a file from <source> to <dest>"
+        text "The destination will not be overwritten unless --force is applied."
+
+        opt :force, "Force overwrite", :default => false
+
+        # This text is only used in the help-screen. Positional arguments are
+        # *not* checked by Optix, you have to do that yourself in the exec{}-block.
+        params "<source> <dest>"
+
+        exec do |cmd, opts, argv|
+          # bail if we didn't receive enough parameters
+          if argv.length < 2
+            puts "Error: #{cmd.join(' ')} must be invoked with 2 parameters."
+            exit 1
+          end
+          
+          puts "#{cmd.join(' ')} called with #{opts}, #{argv}"
+        end
+      end
+
+      # Here we declare the subcommand 'dir move'
+      Optix::command 'dir move' do
+        desc "Move directory from A to B"
+
+        text "Move a directory from <source> to <dest>"
+        text "The destination will not be overwritten unless --force is applied."
+        opt :force, "Force overwrite", :default => false
+        params "<source> <dest>"
+
+        exec do |cmd, opts, argv|
+          if argv.length < 2
+            puts "Error: #{cmd.join(' ')} must be invoked with 2 parameters."
+            exit 1
+          end
+          puts "#{cmd.join(' ')} called with #{opts}, #{argv}"
+        end
+      end
+    end
+
+    class Copy
+      # Here we declare the subcommand 'file copy'
+      Optix::command 'file copy' do
+        # Short one-liner for the sub-command list in parent help-screen
+        desc "Copy a file"
+
+        # Verbose description for the help-screen
+        text "Copy a file from <source> to <dest>"
+        text "The destination will not be overwritten unless --force is applied."
+
+        opt :force, "Force overwrite", :default => false
+
+        # This text is only used in the help-screen. Positional arguments are
+        # *not* checked by Optix, you have to do that yourself in the exec{}-block.
+        params "<source> <dest>"
+
+        exec do |cmd, opts, argv|
+          # bail if we didn't receive enough parameters
+          if argv.length < 2
+            puts "Error: #{cmd.join(' ')} must be invoked with 2 parameters."
+            exit 1
+          end
+          
+          puts "#{cmd.join(' ')} called with #{opts}, #{argv}"
+        end
+      end
+
+      # Here we declare the subcommand 'dir copy'
+      Optix::command 'dir copy' do
+        desc "Copy directory from A to B"
+
+        text "Copy a directory from <source> to <dest>"
+        text "The destination will not be overwritten unless --force is applied."
+        opt :force, "Force overwrite", :default => false
+        params "<source> <dest>"
+
+        exec do |cmd, opts, argv|
+          if argv.length < 2
+            puts "Error: #{cmd.join(' ')} must be invoked with 2 parameters."
+            exit 1
+          end
+          puts "#{cmd.join(' ')} called with #{opts}, #{argv}"
+        end 
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  # Perform some configuration (optional!)
+  Optix.configure do
+    # override a help-text template
+    # see the source-code for full list of available config keys
+    text_header_usage 'Syntax: %0 %command %params'
+  end
+
+  # Perform the actual parsing and execution.
+  Optix.invoke!(ARGV)
+end
+