visionmedia-commander 1.2.2 → 2.4.2

data/lib/commander/command.rb

@@ -1,34 +1,230 @@
 
+require 'optparse'
+require 'ostruct'
+
 module Commander
-	class Command 
-		
-		attr_accessor :description, :syntax, :examples, :options, :command, :manual
-		attr_reader :when_called_proc
-		
-		def initialize(command)
-			@command, @options, @examples = command, [], []
-		end
-		
-		# Adds an example in the help documentation of this sub-command. 
-		def example(description, code) 
-			@examples << { :description => description, :code => code }
-		end
-		
-		# Adds an option or 'flag'. These are parsed with +OptionParser+
-		# so please view its documentation for help.
-		def option(*args, &block)
-			@options << { :args => args, :proc => block }
-		end
-		
-		# This proc is called when the sub-command is invoked. 
-		# The proc has instant access to all methods found in 
-		# interaction.rb
-		def when_called(&block)
-		  @when_called_proc = block
-		end
-		
-		def invoke(method_name, *args)
-		  send(method_name).call *args
-		end
-	end
+  class Command
+    
+    attr_reader :name, :examples, :options, :proxy_options
+    attr_accessor :syntax, :description, :summary
+        
+    ##
+    # Initialize new command with specified _name_.
+    
+    def initialize name
+      @name, @examples, @when_called = name.to_s, [], {}
+      @options, @proxy_options = [], []
+    end
+    
+    #--
+    # Description aliases
+    #++
+    
+    alias :long_description= :description=
+    alias :short_description= :summary=
+    
+    ##
+    # 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 => description,
+        :command => 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
+    #    --[with]-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-parser and evaluate
+    # option arguments. Simply require 'optparse/time', or 'optparse/date', etc.
+    #
+    #   c.option '--time TIME', Time
+    #   c.option '--date [DATE]', Date
+    #
+    
+    def option *args, &block
+      switches, description = seperate_switches_from_description args
+      proc = block_given? ? block : populate_options_to_when_called(switches)
+      @options << {
+        :args => args,
+        :proc => proc,
+        :switches => switches,
+        :description => description,
+      }
+    end
+    
+    ##
+    # Handle execution of command.
+    #
+    # An array of _args_ are passed to the handler, as well as an OpenStruct
+    # containing option values (populated regardless of them being declared).
+    # 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
+      h = @when_called
+      unless args.empty?
+        case args.first
+        when Class
+          h[:class] = args.shift
+          h[:method] = args.shift
+        else
+          h[:object] = args.shift
+          h[:method] = args.shift
+        end
+      end
+      h[:proc] = block if block_given?
+    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
+    
+    ##
+    # Parses options and calls associated procs
+    # returning the arguments left.
+    
+    def parse_options_and_call_procs args = [] 
+      return args if args.empty?
+      opts = OptionParser.new
+      @options.each { |o| opts.on(*o[:args], &o[:proc]) }
+      opts.parse! args
+      args
+    end
+    
+    ##
+    # Call the commands when_called block with _args_.
+    
+    def call args = [] 
+      h = @when_called
+      case 
+      when h[:class]
+        if h[:method].nil?
+          h[:class].new args, proxy_option_struct
+        else
+          h[:class].new.send h[:method], args, proxy_option_struct
+        end
+      when h[:object] : h[:object].send(h[:method], args, proxy_option_struct)
+      when h[:proc] : h[:proc].call args, proxy_option_struct
+      end
+    end
+    
+    ##
+    # Attempts to generate a method name symbol from _switch_.
+    # For example:
+    # 
+    #   -h                 # => :h
+    #   --trace            # => :trace
+    #   --some-switch      # => :some_switch
+    #   --[with]-feature   # => :feature
+    #   --file FILE        # => :file
+    #   --list of, things  # => :list
+    
+    def sym_from_switch switch
+      switch.gsub(/\[.*\]/, '').scan(/-([a-z]+)/).join('_').to_sym rescue nil
+    end
+    
+    def inspect #:nodoc:
+      "#<Command:#{@name}>"
+    end
+    
+    private 
+    
+    def proxy_option_struct #:nodoc:
+      options = OpenStruct.new
+      @proxy_options.each { |o| options.send("#{o[:method]}=", o[:value]) } 
+      options
+    end
+    
+    def seperate_switches_from_description args #:nodoc:
+      # TODO: refactor this goodness
+      switches = args.find_all { |a| a.index('-') == 0 if a.is_a? String } 
+      description = args.last unless !args.last.is_a? String or args.last.index('-') == 0
+      [switches, description]
+    end
+    
+    ##
+    # Pass option values to the when_called proc when a block
+    # is not specifically supplied to #option.
+    
+    def populate_options_to_when_called switches #:nodoc:
+      Proc.new do |args|
+        @proxy_options << {
+          :method => sym_from_switch(switches.last),
+          :value => args,
+        }
+      end 
+    end
+    
+  end
 end

data/lib/commander/core_ext/array.rb

@@ -0,0 +1,24 @@
+
+class Array 
+  
+  ##
+  # Split +string+ into an array. 
+  #
+  # === Highline example:
+  #  
+  #   # ask invokes Array#parse
+  #   list = ask 'Favorite cookies:', Array
+  #
+  
+  def self.parse string
+    string.split
+  end
+  
+  ##
+  # Delete switches such as -h or --help.
+  
+  def delete_switches
+    self.dup.delete_if { |v| v.to_s =~ /^-/ } 
+  end
+  
+end

data/lib/commander/core_ext/kernel.rb

@@ -0,0 +1,12 @@
+
+require 'forwardable'
+
+##
+# Make the following methods globally accessable:
+#
+# * HighLine#color
+
+module Kernel
+  extend Forwardable
+  def_delegators :$terminal, :color
+end

data/lib/commander/core_ext/object.rb

@@ -0,0 +1,13 @@
+
+class Object
+  
+  include Commander::UI
+  
+  ##
+  # Used with ERB in Commander::HelpFormatter::Base.
+  
+  def get_binding
+    binding
+  end
+  
+end

data/lib/commander/core_ext/string.rb

@@ -0,0 +1,33 @@
+
+class String
+    
+  ##
+  # Replace _hash_ keys with associated values. Mutative.
+  
+  def tokenize! hash
+    hash.each_pair do |k, v|
+      self.gsub! Regexp.new(":#{k}"), v.to_s
+    end
+    self
+  end
+    
+  ##
+  # Replace _hash_ keys with associated values.
+  
+  def tokenize hash
+    self.dup.tokenize! hash
+  end
+  
+  ##
+  # Converts a string to camelcase.
+  
+  def camelcase upcase_first_letter = true
+    up = upcase_first_letter
+    str = dup
+    str.gsub!(/\/(.?)/){ "::#{$1.upcase}" }
+    str.gsub!(/(?:_+|-+)([a-z])/){ $1.upcase }
+    str.gsub!(/(\A|\s)([a-z])/){ $1 + $2.upcase } if up
+    str
+  end
+    
+end

data/lib/commander/core_ext.rb

@@ -0,0 +1,5 @@
+
+require 'commander/core_ext/kernel'
+require 'commander/core_ext/array'
+require 'commander/core_ext/object'
+require 'commander/core_ext/string'

data/lib/commander/fileutils.rb

@@ -0,0 +1,30 @@
+
+require 'fileutils'
+
+module VerboseFileUtils
+  
+  include FileUtils
+  
+  ##
+  # Wrap _methods_ with _action_ log message.
+    
+  def self.log action, *methods
+    methods.each do |meth|
+      define_method meth do |*args|
+        Commander::UI.log "#{action}", *args
+        super
+      end
+    end
+  end
+  
+  log "remove", :rm, :rm_r, :rm_rf, :rmdir
+  log "create", :touch, :mkdir, :mkdir_p
+  log "copy", :cp, :cp_r
+  log "move", :mv
+  log "change", :cd
+  log "link", :ln, :ln_s
+  log "install", :install
+
+end
+
+include VerboseFileUtils

data/lib/commander/help_formatters/base.rb

@@ -0,0 +1,38 @@
+
+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 
+      
+      ##
+      # Access the current command runner via +@runner+.
+
+      def initialize runner
+        @runner = runner
+      end
+      
+      ##
+      # Renders global help.
+      
+      def render
+        "Implement global help here"
+      end
+      
+      ##
+      # Renders +command+ specific help.
+      
+      def render_command command
+        "Implement help for #{command.name} here"
+      end
+      
+    end
+  end
+end

data/lib/commander/help_formatters/terminal/command_help.erb

@@ -0,0 +1,35 @@
+
+  <%= color "NAME", :bold %>:
+
+    <%= @name %>
+
+  <%= color "DESCRIPTION", :bold %>:
+
+    <%= @description || @summary || 'No description.' -%>
+
+<% if @syntax -%>
+
+  <%= color "SYNOPSIS", :bold %>:
+
+    <%= @syntax -%>
+
+<% end -%>
+<% unless @examples.empty? -%>
+
+  <%= color "EXAMPLES", :bold %>:
+	<% @examples.each do |example| -%>
+
+    # <%= example[:description] %>
+    <%= example[:command] %>
+	<% end -%>
+<% end -%>
+<% unless @options.empty? -%>
+
+  <%= color "OPTIONS", :bold %>:
+	<% @options.each do |option| -%>
+
+    <%= option[:switches].join ', ' %> 
+        <%= option[:description] %>
+	<% end -%>
+<% end -%>
+

data/lib/commander/help_formatters/terminal/help.erb

@@ -0,0 +1,21 @@
+
+  <%= color "NAME", :bold %>:
+
+    <%= program :name %>
+
+  <%= color "DESCRIPTION", :bold %>:
+
+    <%= program :description %>
+
+  <%= color "SUB-COMMANDS", :bold %>:
+<% @commands.each_pair do |name, command| %>
+    <%= "%-14s %s" % [command.name, command.summary || command.description] -%>
+<% end %>
+<% if program :help -%>
+  <% program(:help).each_pair do |title, body| %>
+  <%= color title.to_s.upcase, :bold %>:
+	
+    <%= body %>
+  <% end %>
+<% end -%>
+

data/lib/commander/help_formatters/terminal.rb

@@ -0,0 +1,27 @@
+
+require 'erb'
+
+module Commander
+  module HelpFormatter
+    
+    ##
+    # = Terminal
+    #
+    # Outputs help in a terminal friendly format,
+    # utilizing asni formatting via the highline gem.
+    
+    class Terminal < Base
+      def render
+        template(:help).result @runner.get_binding
+      end
+      
+      def render_command command
+        template(:command_help).result command.get_binding
+      end
+      
+      def template name
+        ERB.new(File.read(File.expand_path(File.dirname(__FILE__)) + "/terminal/#{name}.erb"), nil, "-")
+      end
+    end
+  end
+end

data/lib/commander/help_formatters.rb

@@ -0,0 +1,6 @@
+
+require 'commander/help_formatters/base'
+
+module Commander::HelpFormatter
+  autoload :Terminal, 'commander/help_formatters/terminal'
+end

data/lib/commander/import.rb

@@ -0,0 +1,28 @@
+
+require "forwardable"
+
+##
+# Makes the following Commander methods globally available:
+#
+# * Commander::Runner#add_command
+# * Commander::Runner#get_command
+# * Commander::Runner#command
+# * Commander::Runner#commands
+# * Commander::Runner#program
+# * Commander::UI::ProgressBar#progress
+
+module Kernel
+  extend Forwardable
+  def_delegators :$command_runner, :add_command, :get_command, :command, :program, :run!, :commands
+  def_delegators Commander::UI::ProgressBar, :progress
+  
+  def command_runner #:nodoc:
+    $command_runner
+  end
+  
+  def method_missing meth, *args, &block
+    if meth.to_s =~ /^ask_for_([\w]+)/
+      $terminal.ask args.first, eval($1.camelcase)
+    end
+  end
+end