choosy 0.1.0

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+group :development do
+  gem 'rspec', :require => "spec"
+  gem 'autotest'
+  gem 'autotest-notification'
+end

data/Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.4.2)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    autotest-notification (2.3.1)
+      autotest (~> 4.3)
+    diff-lcs (1.1.2)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  autotest
+  autotest-notification
+  rspec

data/LICENSE

@@ -0,0 +1,23 @@
+The MIT LICENSE
+
+Copyright (c) 2011 Gabe McArthur
+Copyright (c) 2010 Gabriel Horner
+
+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,
+distribute, 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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,393 @@
+# Choosy: Picking your arguments carefully
+
+This is a small DSL library for creating command line clients in Ruby. It is largely inspired by the <a href="https://github.com/defunkt/choice">choice</a>, <a href="https://github.com/visionmedia/commander">commander</a>, and <a href="http://furius.ca/optcomplete/">optcomplete.py</a> libraries, though it makes some different design decisions than they do.  It is opinionated software.
+
+This library should:
+
+  - Make creating command line clients relatively easy.
+  - Make creating supercommands like git, subversion, and gem easier.
+  - Allow you to add validation logic for your arguments within the parsing phase.
+  - Allowing for dependencies between options, so that you can more easily validate related options (i.e. if the<code>--bold</code> flag requires the <code>--font Arial</code> flag, then you should be able to ask for the <code>--font</code> option to be validated first, and then the <code>--bold</code> option.
+  - Allow you to customize its output using your own formatting system.
+  - Allow you to customize the output to your specifications.
+
+This library should never:
+
+  - Interact with your execution logic.  You can attach executors to commands for convenience, but the execution phase should be delegated to you, not the parsing library.  Separation of concerns, people.
+  - Rely on display or user interface libraries like Highline, since this is only for parsing command lines.
+  - Pollute your namespaces with my DSL function names.  (I really, really hate it when libraries do this.) 
+
+# Examples
+
+    #!/usr/bin/env ruby
+    # foo.rb
+
+    require 'rubygems'
+    require 'choosy'
+
+    FOO_VERSION = 1.0.1
+
+    class FooExecutor
+      def execute!(options, args)
+        puts "BOLDED!!" if options[:bold]
+        options[:count].times do
+          puts "#{options[:prefix]}#{options[:words].push('foo').join(',')#{options[:suffix}}"
+        end
+        puts "and #{args.join ' '}"
+      end
+    end
+
+    foo_cmd = Choosy::Command.new :foo do |foo|
+      # Add a class to do the execution when you call foo_cmd.execute!
+      # You can also use a proc that takes the options and the args, like:
+      #    foo.executor { |opts, args| puts 'Hi!' }
+      foo.executor FooExecutor.new
+
+      # You can add your custom printer by giving the
+      # full path to an ERB template file here.  
+      # The default printer is :standard, but you can 
+      # also use the builtin printer :compact.  The 
+      # output can be colored or uncolored, though the
+      # default is colored.
+      foo.printer :standard, :colored => true
+
+      foo.summary 'Prints out "foo" to the console"
+      foo.desc    <<HERE
+    This is a long description about what 'foo' is
+    and how it works.  Don't worry your pretty little head
+    about the details.
+    HERE
+
+      foo.separator 'Required Options:'
+
+      # A shorthand for a common option type.
+      # It adds the '-p/--prefix PREFIX' infomation for you.
+      foo.single :prefix, "A prefix for 'foo'" do |p|
+        p.default '<'
+        p.required
+      end
+
+      # The long way to do the same thing as above, except with
+      # explicitly named dependencies
+      foo.option :suffix => [:prefix] do |o|
+        o.short '-s'
+        o.long  '--suffix', 'SUFFIX'
+        o.desc  'A suffix for "foo"'
+        o.required
+
+        o.validate do |suffix|
+          if suffix == foo[:prefix]      
+            o.fail "You can't matching prefixes and suffixes, you heathen!"
+          end
+        end
+      end
+
+      # Just like the 'single' method above, except now it automatically
+      # requires/casts the argument to this flag into an integer.  These commands
+      # also take an optional hash as the last argument, which can be used instead
+      # of a block.
+      foo.integer :count, 'The number of times to repeat "foo"', :required => true
+
+      foo.separator 
+      foo.separator 'Options:'
+
+      foo.option :words do |o|
+        o.short '-w'
+        o.long  '--words', 'WORDS+' # By default, the '+' at the end
+                                    # means that this takes multiple
+                                    # arguments.  You put a '-' at
+                                    # the end of the argument list
+                                    # to stop parsing this option
+                                    # and allow for regular args.
+        o.desc  "Other fun words to put in quotes"
+        o.default []                # The default anyway on multple arg options
+        
+        # Sets the exact count of the number of arguments it accepts.
+        # also allowable are the single selectors :zero and :one.
+        # By default, the option 'WORDS+' sets the range to be
+        # {:at_least => 1, :at_most => 1000 }
+        o.count {:at_least => 2, :at_most => 10 }
+
+        o.validate do |words|
+          words.each do |word|
+            if word !~ /\w+/
+              o.fail "I can't print that: #{word}"
+            end
+          end
+        end
+      end
+
+      # Alternatively, we could have done the following:
+      foo.strings :words, "Other fun words to put in quotes" do |w|
+        w.count {:at_least => 2, :at_most => 10 }
+        w.validate do |words|
+          words.each do |word|
+            if word !~ /\w+/
+              w.fail "I can't print that: #{word}"
+            end
+          end
+        end
+      end
+
+      # Yet another shorthand notation for options, since they
+      # are boolean by default
+      foo.option :bold => {:long => '--bold', :default => false}
+
+      options.separator
+      # Tail options
+
+      # When any of the simpler notations are suffixed with a '_' 
+      # character, the short option is always suppressed.
+      foo.boolean_ :debug, "Prints out extra debugging output."
+
+      # The '_' characters are replaced with '-' in flags, so the 
+      # following creates a '--no-color' flag.
+      foo.boolean_ :no_color, "Turns off coloring in the output" do |o|
+        o.validate do
+          foo.printer :standard, :colored => false
+        end
+      end
+
+      # Adds the standard -h/--help option.
+      # Should skip the '-h' flag if already set.
+      foo.help  
+
+      # Adds the --version option.
+      foo.version "Foo: #{FOO_VERSION}"
+
+      # Now, add some validation for any addtional arguments
+      # that are left over after the parsing.
+      foo.arguments do |args|
+        if args.empty?
+          a.fail "You have to pass in empty arguments that do nothing!"
+        end
+        if args.count >= 3
+          a.fail "Whoa there!  You're going argument crazy!"
+        end
+      end
+    end
+
+    if __FILE__ == $0
+      # Parses and validates the options.
+      args =  ['--prefix', '{', 
+               '--suffix', '}',
+               '--words', 'high', 'there', 'you', '-', 
+               # The '-' stops parsing this option, so that:
+               'handsom', 'devil',
+               'http://not.posting.here', # will be regular arguments
+               '-c, '3', # Count
+               '--', # Stops parsing all arguments
+               '-h', '--help', '-v', '--version' # Ignored
+              ]
+      result = foo_cmd.parse!(args)
+      
+      require 'pp'
+      pp result[:prefix]        # => '{'
+      pp result[:suffix]        # => '}'
+      pp reuslt[:count]         # => 3
+      pp result[:bold]          # => false
+      pp reuslt[:words]         # => ['high', 'there', 'you']
+      pp reuslt.args            # => ['handsom', 'devil',
+                                #     'http://not.posting.here',
+                                #     '-h', '--help', '-v', '--version']
+      pp result.options         # => {:prefix => '{', :suffix => '}'
+                                #     :count => 3, :bold => false,
+                                #     :words => ['high', 'there', 'you']}
+  
+      # Now, call the command that does the actual work.
+      # This passes the foo_cmd.options and the foo_cmd.args
+      # as arguments to the executors 'execute!' method.
+      #
+      # This allows you to easily associate command classes with
+      # commands, without resorting to a hash or combining
+      # execution logic with command parsing logic.
+      foo_cmd.execute!(args)    # {high,there,you,foo}
+                                # {high,there,you,foo}
+                                # {high,there,you,foo}
+                                # and handsom devil http://not.posting.here -h --help -v --verbose
+  
+    end
+
+### Super Commands
+
+You can also combine multiple choices into an uber-choice, creating
+commands that look a lot like git or subversion.
+
+First, we create another command.
+    
+    #!/usr/bin/env ruby
+    # bar.rb
+
+    require 'rubygems'
+    require 'choosy'
+
+    class BarExecutor
+      def execute!(options, args)
+        if options[:bold]
+          puts "BOLDED BAR"
+        else
+          puts "bar"
+        end
+      end
+    end
+    
+    # Create a new command
+    bar_cmd = Choosy::Command.new :bar do |bar|
+      bar.executor BarExecutor.new
+      bar.summary "Just prints 'bar'"
+      bar.desc "A truly unremarkable command"
+
+      bar.boolean :bold, "Bolds something" 
+
+      # Because there is no bar.arguments call,
+      # it is now an error if there are extra
+      # command line arguments to this command.
+    end
+    
+We can now create our super command.
+
+    #!/usr/bin/env ruby
+    # superfoo.rb
+
+    require 'rubygems'
+    require 'choosy'
+    require 'foo.rb'
+    require 'bar.rb'
+    
+    SUPERFOO_VERSION = "1.0.1"
+    
+    superfoo = Choosy::SuperCommand.new :superfoo do |superfoo|
+      superfoo.summary "This is a superfoo command."
+      superfoo.desc "Say something, dammit!"
+
+      # You can also add commands after instantiation.
+      # Note that, when added, these commands have their
+      # -h/--help/--version flags suppressed, so you'll
+      # need to add those flags here.
+      superfoo.commands bar_cmd
+
+      # Creates a 'help' command
+      superfoo.help do |help|
+        help.summary "Prints this help message"
+      end
+
+      # Create some global options that are parsed
+      # defore subcommand options
+    
+      superfoo.option :config do |o|
+        o.long '--config', 'FILE'
+        o.desc "Configure your superfoo with a configuration file."
+    
+        o.validate do |config|
+          if !File.exist? config
+            o.fail "Unable to find configuration file!"
+          end
+        end
+      end
+    
+      # Adds a global --version flag.
+      superfoo.version do
+        puts "#{SUPERFOO_VERSION}"
+      end
+    end
+    
+    # Add a command after the fact.
+    superfoo.commands foo_cmd
+    
+    if __FILE__ == $0
+      superfoo.parse! ['-c', '5',
+                       'foo',
+                       '--config', '~/.superfoo',
+                       '--prefix', '{',
+                       '--suffix', '}',
+                       'cruft',
+                       'bar',
+                       '--bold']
+                       
+      require 'pp'
+      pp superfoo[:config]                  # => '~/.superfoo'
+      pp superfoo.subcommand.name           # => :foo
+      pp superfoo.subcommand[:prefix]       # => '{'
+      pp superfoo.subcommand[:suffix]       # => '}'
+      pp superfoo.subcommand[:count]        # => 2
+      pp superfoo.subcommand[:bold]         # => true
+      pp superfoo.subcommand.options        # => {:prefix => '{', :suffix => '}'
+                                            #     :count => 2,
+                                            #     :bold => true, 
+                                            #     :words => [],
+                                            #     :config => '~/.superfoo' }
+      pp superfoo.subcommand.args           # => ['cruft', 'bar']
+      
+      pp superfoo.options                   # => {:prefix => '{', :suffix => '}'
+                                            #     :count => 2,
+                                            #     :bold => true, 
+                                            #     :words => [],
+                                            #     :config => '~/.superfoo' }
+      pp superfoo.args                      # => ['cruft', 'bar']
+  
+      # Now, we can call the subcommand
+      superfoo.execute!                     ## Calls superfoo.subcommand.execute!
+                                            ## Prints:
+                                            # BOLDED!!
+                                            # {foo}
+                                            # {foo}
+                                            # and cruft bar
+  
+      # We got what we wanted, so reset the parser.
+      superfoo.reset!
+  
+      # Instead of parsing the 'bar' parameter as an argument to
+      # the foo command, so that when the first argument that matches
+      # another command name is encountered, it stops parsing the
+      # current command and passes the rest of the arguments to the
+      # next command.
+      #
+      # You can also set this inside a SuperChoosy.new {|s| ... } 
+      # block.
+      superfoo.parsimonious
+  
+      superfoo.parse! ['-c', '5',
+                       'foo',
+                       '--config', '~/.superfoo',
+                       '--prefix', '{',
+                       '--suffix', '}',
+                       'cruft',
+                       'bar',
+                       '--bold']
+                       
+      pp superfoo[:config]                      # => '~/.superfoo'
+      pp superfoo.subcommand.name               # => :foo
+      pp superfoo.subcommands[0].name           # => :foo
+      pp superfoo.subcommands[0][:prefix]       # => '{'
+      pp superfoo.subcommands[0][:suffix]       # => '}'
+      pp superfoo.subcommands[0][:count]        # => 2
+      pp superfoo.subcommands[0][:bold]         # => true
+      pp superfoo.subcommands[0].options        # => {:prefix => '{', :suffix => '}'
+                                                #     :count => 2,
+                                                #     :bold => false, 
+                                                #     :words => [],
+                                                #     :config => '~/.superfoo' }
+      pp superfoo.subcommands[0].args           # => ['cruft']
+  
+      pp superfoo.subcommands[1].name           # => :bar
+      pp superfoo.subcommands[1][:bold]         # => true
+      pp superfoo.subcommands[1].options        # => {:bold => true,
+                                                #     :config => '~/.superfoo'}
+      pp superfoo.subcommands[1].args           # => []
+      
+      pp superfoo.options                       # => {:config => '~/.superfoo'}
+      pp superfoo.args                          # => []
+  
+      # Now, execute the subcommands in order
+      superfoo.execute!        ## Same as:
+                               #  superfoo.subcommands.each do |subcommand|
+                               #    command.execute!
+                               #  end
+                               ## Prints:
+                               # {foo}
+                               # {foo}
+                               # and cruft
+                               # BOLDED BAR
+    end
+
+### TODO: Output Printing

data/Rakefile

@@ -0,0 +1,57 @@
+# $LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+# $LOAD_PATH.unshift File.expand_path("../spec", __FILE__)
+
+require 'rubygems'
+require 'rake'
+#require 'rake/rdoctask'
+require 'rspec/core/rake_task'
+require './lib/choosy/version'
+
+PACKAGE_NAME = "choosy"
+PACKAGE_VERSION = Choosy::Version
+
+desc "Default task"
+task :default => [ :spec ]
+
+desc "Build documentation"
+task :doc => [ :rdoc ]
+
+#task :rdoc => SOURCE_FILES
+
+desc "Run the RSpec tests"
+RSpec::Core::RakeTask.new :spec
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name           = PACKAGE_NAME
+    gem.version        = PACKAGE_VERSION
+    gem.summary        = 'Yet another option parsing library.'
+    gem.description    = 'This is a DSL for creating more complicated command line tools.'
+    gem.email          = ['madeonamac@gmail.com']
+    gem.authors        = ['Gabe McArthur']
+    gem.homepage       = 'http://github.com/gabemc/choosy'
+    gem.files          = FileList["[A-Z]*", "{bin,lib,spec}/**/*"]
+    
+    gem.add_development_dependency 'rspec', '~> 2.5'
+  end
+rescue LoadError
+  puts "Jeweler or dependencies are not available.  Install it with: gem install jeweler"
+end
+
+desc "Cleans the generated files."
+task :clean do
+  rm Dir.glob('*.gemspec')
+  rm Dir.glob('*.gem')
+  rm_rf 'pkg'
+end
+
+desc "Deploys the gem to rubygems.org"
+task :gem => :release do
+  system("gem build #{PACKAGE_NAME}.gemspec")
+  system("gem push #{PACKAGE_NAME}-#{PACKAGE_VERSION}.gem")
+end
+
+desc "Does the full release cycle."
+task :deploy => [:gem, :clean] do
+end

data/lib/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/choosy/base_command.rb

@@ -0,0 +1,59 @@
+require 'choosy/errors'
+
+module Choosy
+  class BaseCommand
+    attr_accessor :name, :summary, :description, :printer
+    attr_reader :builder, :listing, :option_builders
+    
+    def initialize(name)
+      @name = name
+      @listing = []
+      @option_builders = {}
+
+      @builder = create_builder
+      yield @builder if block_given?
+      @builder.finalize!
+    end
+
+    def alter(&block)
+      yield @builder if block_given?
+      @builder.finalize!
+    end
+
+    def options
+      @option_builders.values.map {|b| b.option}
+    end
+
+    def parse!(args, propagate=false)
+      if propagate
+        return parse(args)
+      else
+        begin
+          return parse(args)
+        rescue Choosy::ValidationError, Choosy::ConversionError, Choosy::ParseError => e
+          $stderr << "#{@name}: #{e.message}\n"
+          exit 1
+        rescue Choosy::HelpCalled => e
+          handle_help(e)
+          exit 0
+        rescue Choosy::VersionCalled => e
+          $stdout <<  "#{e.message}\n"
+          exit 0
+        end
+      end
+    end
+
+    protected
+    def create_builder
+      # Override in subclasses
+    end
+
+    def parse(args)
+      # Override in subclasses
+    end
+
+    def handle_help(hc)
+      # Override in subclasses
+    end
+  end
+end

data/lib/choosy/command.rb

@@ -0,0 +1,32 @@
+require 'choosy/errors'
+require 'choosy/base_command'
+require 'choosy/dsl/command_builder'
+require 'choosy/parser'
+require 'choosy/verifier'
+
+module Choosy
+  class Command < BaseCommand
+    attr_accessor :executor, :argument_validation
+    
+    def execute!(args)
+      raise Choosy::ConfigurationError.new("No executor given for: #{name}") unless executor
+      result = parse!(args)
+      executor.call(result.options, result.args)
+    end
+
+    protected
+    def create_builder
+      Choosy::DSL::CommandBuilder.new(self)
+    end
+
+    def handle_help(hc)
+      printer.print!(self)
+    end
+
+    def parse(args)
+      parser = Parser.new(self)
+      result = parser.parse!(args)
+      result.verify!
+    end
+  end
+end