clone 1.0.0.alpha → 1.0.0.beta

data/module/gems/commander-4.1.3/lib/commander.rb

@@ -0,0 +1,32 @@
+#--
+# 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'
+require 'commander/platform'

data/module/gems/commander-4.1.3/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/module/gems/commander-4.1.3/lib/commander/command.rb

@@ -0,0 +1,213 @@
+
+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
+    alias :action :when_called
+    
+    ##
+    # 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 that are present will evaluate to true
+        value = true if value.nil?
+        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/module/gems/commander-4.1.3/lib/commander/core_ext.rb

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

data/module/gems/commander-4.1.3/lib/commander/core_ext/array.rb

@@ -0,0 +1,26 @@
+
+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
+    # Using reverse + lookahead to work around Ruby 1.8's lack of lookbehind
+    string.reverse.split(/\s(?!\\)/).reverse.map { |s| s.reverse.gsub('\\ ', ' ') }
+  end
+
+end

data/module/gems/commander-4.1.3/lib/commander/core_ext/object.rb

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

data/module/gems/commander-4.1.3/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/module/gems/commander-4.1.3/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/module/gems/commander-4.1.3/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

data/module/gems/commander-4.1.3/lib/commander/help_formatters/terminal.rb

@@ -0,0 +1,20 @@
+
+require 'erb'
+
+module Commander
+  module HelpFormatter
+    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.join(File.dirname(__FILE__), 'terminal', "#{name}.erb")), nil, '-')
+      end
+    end
+  end
+end

data/module/gems/commander-4.1.3/lib/commander/help_formatters/terminal/command_help.erb

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

data/module/gems/commander-4.1.3/lib/commander/help_formatters/terminal/help.erb

@@ -0,0 +1,36 @@
+  <%= $terminal.color "NAME", :bold %>:
+
+    <%= program :name %>
+
+  <%= $terminal.color "DESCRIPTION", :bold %>:
+
+    <%= program :description %>
+
+  <%= $terminal.color "COMMANDS", :bold %>:
+<% for name, command in @commands.sort -%>
+	<% unless alias? name %>
+    <%= "%-20s %s" % [command.name, command.summary || command.description] -%>
+	<% end -%>
+<% end %>
+<% unless @aliases.empty? %>
+  <%= $terminal.color "ALIASES", :bold %>:
+  <% for alias_name, args in @aliases.sort %>
+    <%= "%-20s %s %s" % [alias_name, command(alias_name).name, args.join(' ')] -%>
+  <% end %>
+<% end %>
+<% unless @options.empty? -%>
+  <%= $terminal.color "GLOBAL OPTIONS", :bold %>:
+	<% for option in @options -%>
+
+    <%= option[:switches].join ', ' %> 
+        <%= option[:description] %>
+	<% end -%>
+<% end -%>
+<% if program :help -%>
+  <% for title, body in program(:help) %>
+  <%= $terminal.color title.to_s.upcase, :bold %>:
+
+    <%= body %>
+  <% end -%>
+<% end -%>
+

data/module/gems/commander-4.1.3/lib/commander/help_formatters/terminal_compact.rb

@@ -0,0 +1,12 @@
+
+require 'erb'
+
+module Commander
+  module HelpFormatter
+    class TerminalCompact < Terminal
+      def template name
+        ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal_compact', "#{name}.erb")), nil, '-')
+      end
+    end
+  end
+end