commander 3.3.0

data/Rakefile

@@ -0,0 +1,16 @@
+
+$:.unshift 'lib'
+require 'commander'
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new "commander", Commander::VERSION do |p|
+  p.author = "TJ Holowaychuk"
+  p.email = "tj@vision-media.ca"
+  p.summary = "The complete solution for Ruby command-line executables"
+  p.url = "http://visionmedia.github.com/commander"
+  p.runtime_dependencies << "highline >=1.5.0"
+end
+
+Dir['tasks/**/*.rake'].sort.each { |lib| load lib }

data/bin/commander

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'commander/import'
+
+program :name, 'commander'
+program :version, Commander::VERSION
+program :description, 'Commander utility program.'
+
+command :init do |c|
+	c.syntax = 'commander init <file>'
+	c.summary = 'Initialize a commander template'
+	c.description = 'Initialize an empty <file> with a commander template, 
+    allowing very quick creation of commander executables.'
+	c.example 'Create a new file with a commander template.', 'commander init bin/my_executable'
+	c.when_called do |args, options|
+	  file = args.shift || abort('file argument required.')
+		name = ask 'Machine name of program: '
+		description = ask 'Describe your program: '
+		commands = ask_for_array 'List the commands you wish to create: '
+		begin
+      File.open(file, 'w') do |f|
+        f.write <<-"...".gsub!(/^ {10}/, '')
+          #!/usr/bin/env ruby
+          
+          require 'rubygems'
+          require 'commander'
+          require '#{name}'
+          
+          program :version, #{name.capitalize}::VERSION
+          program :description, '#{description}'
+           
+        ...
+        commands.each do |command|
+          f.write <<-"...".gsub!(/^ {12}/, '')
+            command :#{command} do |c|
+              c.syntax = '#{name} #{command} [options]'
+              c.summary = ''
+              c.description = ''
+              c.example 'description', 'command example'
+              c.option '--some-switch', 'Some switch that does something'
+              c.when_called do |args, options|
+                # Do something or c.when_called #{name.capitalize}::Commands::#{command.capitalize}
+              end
+            end
+
+          ...
+        end
+       end
+       say "Initialized template in #{file}"
+		 rescue Exception => e
+       abort e
+		 end
+	end
+end

data/commander.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{commander}
+  s.version = "3.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["TJ Holowaychuk"]
+  s.date = %q{2009-10-08}
+  s.default_executable = %q{commander}
+  s.description = %q{The complete solution for Ruby command-line executables}
+  s.email = %q{tj@vision-media.ca}
+  s.executables = ["commander"]
+  s.extra_rdoc_files = ["README.rdoc", "bin/commander", "lib/commander.rb", "lib/commander/blank.rb", "lib/commander/command.rb", "lib/commander/core_ext.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/object.rb", "lib/commander/delegates.rb", "lib/commander/help_formatters.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal_compact.rb", "lib/commander/help_formatters/terminal_compact/command_help.erb", "lib/commander/help_formatters/terminal_compact/help.erb", "lib/commander/import.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake"]
+  s.files = ["History.rdoc", "Manifest", "README.rdoc", "Rakefile", "bin/commander", "commander.gemspec", "lib/commander.rb", "lib/commander/blank.rb", "lib/commander/command.rb", "lib/commander/core_ext.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/object.rb", "lib/commander/delegates.rb", "lib/commander/help_formatters.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal_compact.rb", "lib/commander/help_formatters/terminal_compact/command_help.erb", "lib/commander/help_formatters/terminal_compact/help.erb", "lib/commander/import.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "spec/command_spec.rb", "spec/core_ext/array_spec.rb", "spec/core_ext/object_spec.rb", "spec/help_formatters/base_spec.rb", "spec/help_formatters/terminal_spec.rb", "spec/runner_spec.rb", "spec/spec_helper.rb", "spec/ui_spec.rb", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake"]
+  s.homepage = %q{http://visionmedia.github.com/commander}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Commander", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{commander}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{The complete solution for Ruby command-line executables}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<highline>, [">= 1.5.0"])
+    else
+      s.add_dependency(%q<highline>, [">= 1.5.0"])
+    end
+  else
+    s.add_dependency(%q<highline>, [">= 1.5.0"])
+  end
+end

data/lib/commander.rb

@@ -0,0 +1,31 @@
+#--
+# Copyright (c) 2008-2009 TJ Holowaychuk <tj@vision-media.ca>
+#
+# 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.
+#++
+
+require 'highline/import'
+require 'commander/version'
+require 'commander/blank'
+require 'commander/user_interaction'
+require 'commander/core_ext'
+require 'commander/runner'
+require 'commander/command'
+require 'commander/help_formatters'

data/lib/commander/blank.rb

@@ -0,0 +1,8 @@
+
+module Blank
+  def self.included base
+    base.class_eval do
+      instance_methods.each { |m| undef_method m unless m =~ /^__|object_id/ }
+    end
+  end
+end

data/lib/commander/command.rb

@@ -0,0 +1,210 @@
+
+require 'optparse'
+
+module Commander
+  class Command
+    
+    attr_accessor :name, :examples, :syntax, :description
+    attr_accessor :summary, :proxy_options, :options
+    
+    ##
+    # Options struct.
+
+    class Options
+      include Blank
+      
+      def initialize
+        @table = {}
+      end
+      
+      def __hash__
+        @table
+      end
+      
+      def method_missing meth, *args, &block
+        meth.to_s =~ /=$/ ? @table[meth.to_s.chop.to_sym] = args.first : @table[meth]
+      end
+      
+      def default defaults = {}
+        @table = defaults.merge! @table
+      end
+      
+      def inspect
+        "<Commander::Command::Options #{ __hash__.map { |k,v| "#{k}=#{v.inspect}" }.join(', ') }>"
+      end
+    end
+        
+    ##
+    # Initialize new command with specified _name_.
+    
+    def initialize name
+      @name, @examples, @when_called = name.to_s, [], []
+      @options, @proxy_options = [], []
+    end
+    
+    ##
+    # Add a usage example for this command.
+    #
+    # Usage examples are later displayed in help documentation
+    # created by the help formatters.
+    #
+    # === Examples
+    #    
+    #   command :something do |c|
+    #     c.example "Should do something", "my_command something"
+    #   end
+    #
+    
+    def example description, command 
+      @examples << [description, command]
+    end
+    
+    ##
+    # Add an option.
+    #
+    # Options are parsed via OptionParser so view it
+    # for additional usage documentation. A block may optionally be
+    # passed to handle the option, otherwise the _options_ struct seen below 
+    # contains the results of this option. This handles common formats such as:
+    #
+    #   -h, --help          options.help           # => bool
+    #   --[no-]feature      options.feature        # => bool
+    #   --large-switch      options.large_switch   # => bool
+    #   --file FILE         options.file           # => file passed
+    #   --list WORDS        options.list           # => array
+    #   --date [DATE]       options.date           # => date or nil when optional argument not set
+    #
+    # === Examples
+    #    
+    #   command :something do |c|
+    #     c.option '--recursive', 'Do something recursively'
+    #     c.option '--file FILE', 'Specify a file'
+    #     c.option('--info', 'Display info') { puts "handle with block" }
+    #     c.option '--[no-]feature', 'With or without feature'
+    #     c.option '--list FILES', Array, 'List the files specified'
+    #   
+    #     c.when_called do |args, options|
+    #       do_something_recursively if options.recursive
+    #       do_something_with_file options.file if options.file
+    #     end 
+    #   end
+    #
+    # === Help Formatters
+    #
+    # This method also parses the arguments passed in order to determine
+    # which were switches, and which were descriptions for the
+    # option which can later be used within help formatters
+    # using option[:switches] and option[:description].
+    #
+    # === Input Parsing
+    #
+    # Since Commander utilizes OptionParser you can pre-parse and evaluate
+    # option arguments. Simply require 'optparse/time', or 'optparse/date', as these
+    # objects must respond to #parse.
+    #
+    #   c.option '--time TIME', Time
+    #   c.option '--date [DATE]', Date
+    #
+    
+    def option *args, &block
+      switches, description = Runner.separate_switches_from_description *args
+      proc = block || option_proc(switches)
+      @options << {
+        :args => args,
+        :proc => proc,
+        :switches => switches,
+        :description => description,
+      }
+    end
+    
+    ##
+    # Handle execution of command. The handler may be a class, 
+    # object, or block (see examples below).
+    #
+    # === Examples
+    #    
+    #   # Simple block handling
+    #   c.when_called do |args, options|
+    #      # do something
+    #   end 
+    #   
+    #   # Create inst of Something and pass args / options
+    #   c.when_called MyLib::Command::Something
+    #   
+    #   # Create inst of Something and use arbitrary method
+    #    c.when_called MyLib::Command::Something, :some_method
+    #   
+    #   # Pass an object to handle callback (requires method symbol)
+    #   c.when_called SomeObject, :some_method
+    #
+    
+    def when_called *args, &block
+      raise ArgumentError, 'must pass an object, class, or block.' if args.empty? and !block
+      @when_called = block ? [block] : args
+    end
+    
+    ##
+    # Run the command with _args_.
+    #
+    # * parses options, call option blocks
+    # * invokes when_called proc
+    #
+    
+    def run *args
+      call parse_options_and_call_procs(*args)
+    end
+    
+    #:stopdoc:
+    
+    ##
+    # Parses options and calls associated procs, 
+    # returning the arguments remaining.
+    
+    def parse_options_and_call_procs *args
+      return args if args.empty?
+      @options.inject OptionParser.new do |opts, option| 
+        opts.on *option[:args], &option[:proc]
+        opts
+      end.parse! args
+    end
+    
+    ##
+    # Call the commands when_called block with _args_.
+    
+    def call args = []
+      object = @when_called.shift
+      meth = @when_called.shift || :call
+      options = proxy_option_struct
+      case object
+      when Proc  ; object.call(args, options)
+      when Class ; meth != :call ? object.new.send(meth, args, options) : object.new(args, options)
+      else         object.send(meth, args, options) if object
+      end 
+    end
+    
+    ##
+    # Creates an Options instance populated with the option values
+    # collected by the #option_proc.
+    
+    def proxy_option_struct
+      proxy_options.inject Options.new do |options, (option, value)|
+        options.__send__ :"#{option}=", value
+        options
+      end
+    end
+    
+    ##
+    # Option proxy proc used when a block is not explicitly passed
+    # via the #option method. This allows commander to auto-populate
+    # and work with option values.
+    
+    def option_proc switches
+      lambda { |value| proxy_options << [Runner.switch_to_sym(switches.last), value] } 
+    end
+    
+    def inspect 
+      "<Commander::Command:#{name}>"
+    end
+    
+  end
+end

data/lib/commander/core_ext.rb

@@ -0,0 +1,3 @@
+
+require 'commander/core_ext/array'
+require 'commander/core_ext/object'

data/lib/commander/core_ext/array.rb

@@ -0,0 +1,25 @@
+
+class Array 
+  
+  ##
+  # Split _string_ into an array. Used in
+  # conjunction with Highline's #ask, or #ask_for_array
+  # methods, which must respond to #parse.
+  #
+  # This method allows escaping of whitespace. For example
+  # the arguments foo bar\ baz will become ['foo', 'bar baz']
+  #
+  # === Example
+  #  
+  #   # ask invokes Array#parse
+  #   list = ask 'Favorite cookies:', Array
+  #
+  #   # or use ask_for_CLASS
+  #   list = ask_for_array 'Favorite cookies: '
+  #
+  
+  def self.parse string
+    eval "%w(#{string})"
+  end
+    
+end

data/lib/commander/core_ext/object.rb

@@ -0,0 +1,11 @@
+
+class Object
+
+  ##
+  # Return the current binding.
+  
+  def get_binding
+    binding
+  end
+
+end

data/lib/commander/delegates.rb

@@ -0,0 +1,13 @@
+
+module Commander
+  module Delegates
+    %w( add_command command program run! global_option 
+        commands alias_command default_command ).each do |meth|
+      eval <<-END, binding, __FILE__, __LINE__
+        def #{meth} *args, &block
+          ::Commander::Runner.instance.#{meth} *args, &block
+        end
+      END
+    end
+  end
+end

data/lib/commander/help_formatters.rb

@@ -0,0 +1,8 @@
+
+module Commander
+  module HelpFormatter
+    autoload :Base, 'commander/help_formatters/base'
+    autoload :Terminal, 'commander/help_formatters/terminal'
+    autoload :TerminalCompact, 'commander/help_formatters/terminal_compact'
+  end
+end

data/lib/commander/help_formatters/base.rb

@@ -0,0 +1,18 @@
+
+module Commander
+  
+  ##
+  # = Help Formatter
+  #
+  # Commander's help formatters control the output when
+  # either the help command, or --help switch are called.
+  # The default formatter is Commander::HelpFormatter::Terminal.
+  
+  module HelpFormatter
+    class Base 
+      def initialize runner; @runner = runner  end
+      def render; 'Implement global help here' end
+      def render_command command; "Implement help for #{command.name} here" end
+    end
+  end
+end