visionmedia-commander 1.2.2 → 2.4.2

data/lib/commander/runner.rb

@@ -0,0 +1,219 @@
+
+require 'optparse'
+
+module Commander
+  class Runner
+    
+    #--
+    # Exceptions
+    #++
+
+    class CommandError < StandardError; end
+    class InvalidCommandError < CommandError; end
+    
+    ##
+    # Commands within the runner.
+    
+    attr_reader :commands
+    
+    ##
+    # Global options.
+    
+    attr_reader :options
+    
+    ##
+    # Initialize a new command runner.
+    
+    def initialize args = ARGV
+      @args = args
+      @commands, @options = {}, {}
+      @program = { 
+        :help_formatter => Commander::HelpFormatter::Terminal,
+        :int_message => "\nProcess interrupted",
+      }
+      create_default_commands
+      parse_global_options
+    end
+    
+    ##
+    # Run the command parsing and execution process immediately.
+    
+    def run!
+      %w[ name version description ].each { |k| ensure_program_key_set k.to_sym }
+      case 
+      when options[:version] : $terminal.say "#{@program[:name]} #{@program[:version]}" 
+      when options[:help] : get_command(:help).run
+      else active_command.run args_without_command
+      end
+    rescue InvalidCommandError
+      $terminal.say "invalid command. Use --help for more information"
+    rescue OptionParser::InvalidOption, 
+      OptionParser::InvalidArgument,
+      OptionParser::MissingArgument => e
+      $terminal.say e
+    end
+    
+    ##
+    # Assign program information.
+    #
+    # === Examples:
+    #    
+    #    # Set data
+    #    program :name, 'Commander'
+    #    program :version, Commander::VERSION
+    #    program :description, 'Commander utility program.'
+    #    program :help, 'Copyright', '2008 TJ Holowaychuk'
+    #    program :help, 'Anything', 'You want'
+    #    program :int_message 'Bye bye!'
+    #
+    #    # Get data
+    #    program :name # => 'Commander'
+    #
+    # === Keys:
+    #
+    #    :name            (required) Program name
+    #    :version         (required) Program version triple, ex: '0.0.1'
+    #    :description     (required) Program description
+    #    :help_formatter  Defaults to Commander::HelpFormatter::Terminal
+    #    :help            Allows addition of arbitrary global help blocks
+    #    :int_message     Message to display when interrupted (CTRL + C)
+    #
+    
+    def program key, *args
+      if key == :help and !args.empty?
+        @program[:help] ||= {}
+        @program[:help][args.first] = args[1]
+      else
+        @program[key] = *args unless args.empty?
+        @program[key] if args.empty?
+      end
+    end
+    
+    ##
+    # Generate a command object instance using a block
+    # evaluated with the command as its scope.
+    #
+    # === Examples:
+    #    
+    #    command :my_command do |c|
+    #      c.when_called do |args|
+    #        # Code
+    #      end
+    #    end
+    #
+    # === See:
+    #
+    # * Commander::Command
+    # * Commander::Runner#add_command
+    #
+    
+    def command name, &block
+      command = Commander::Command.new(name) and yield command
+      add_command command
+    end
+    
+    ##
+    # Add a command object to this runner.
+    
+    def add_command command
+      @commands[command.name] = command
+    end
+    
+    ##
+    # Get a command object if available or nil.
+    
+    def get_command name
+      @commands[name.to_s] or raise InvalidCommandError, "Invalid command '#{name || "nil"}'", caller
+    end
+    
+    ##
+    # Check if a command exists.
+    
+    def command_exists? name
+      @commands[name.to_s]
+    end
+    
+    ##
+    # Get active command within arguments passed to this runner.
+    #
+    # === See:
+    #
+    # * Commander::Runner#parse_global_options
+    #
+    
+    def active_command
+      @_active_command ||= get_command(command_name_from_args)
+    end
+    
+    ##
+    # Attemps to locate command from @args. Supports multi-word
+    # command names. 
+    
+    def command_name_from_args
+      @args.delete_switches.inject do |name, arg|
+        return name if command_exists? name
+        name << " #{arg}"
+      end
+    end
+    
+    ##
+    # Help formatter instance.
+    
+    def help_formatter
+      @_help_formatter ||= @program[:help_formatter].new self
+    end
+        
+    private
+    
+    ##
+    # Creates default commands such as 'help' which is 
+    # essentially the same as using the --help switch.
+    
+    def create_default_commands
+      command :help do |c|
+        c.syntax = "command help <sub_command>"
+        c.summary = "Display help documentation"
+        c.description = "Display help documentation for the global or sub commands"
+        c.example "Display global help", "command help"
+        c.example "Display help for 'foo'", "command help foo"
+        c.when_called do |args, options|
+          gen = help_formatter
+          if args.empty?
+            $terminal.say gen.render 
+          else
+            $terminal.say gen.render_command(get_command(args.shift.to_sym))
+          end
+        end
+      end
+    end
+            
+    ##
+    # Parse global command options.
+    #
+    # These options are used by commander itself 
+    # as well as allowing your program to specify 
+    # global commands such as '--verbose'.
+    #
+    # TODO: allow 'option' method for global program
+    #
+    
+    def parse_global_options
+      opts = OptionParser.new
+      opts.on("--help") { @options[:help] = true }
+      opts.on("--version") { @options[:version] = true }
+      opts.parse! @args.dup
+    rescue OptionParser::InvalidOption
+      # Ignore invalid options since options will be further 
+      # parsed by our sub commands.
+    end
+        
+    def ensure_program_key_set key #:nodoc:
+      raise CommandError, "Program #{key} required (use #program method)" if (@program[key].nil? || @program[key].empty?)
+    end
+    
+    def args_without_command #:nodoc:
+      @args.join(' ').sub(/^[\s]*#{active_command.name}/, '').split
+    end
+        
+  end
+end

data/lib/commander/user_interaction.rb

@@ -0,0 +1,202 @@
+
+module Commander
+  
+  ##
+  # = User Interaction
+  #
+  # Commander's user interacton module mixes in common
+  # methods which extend HighLine's functionality such 
+  # as a unified +password+ method rather than calling
+  # +ask+ directly.
+  
+  module UI
+    
+    ##
+    # Format used within #log.
+    
+    LOG_FORMAT = "%15s  %s"
+    
+    ##
+    # Ask the user for a password. Specify a custom
+    # _msg_ other than 'Password: ' or override the 
+    # default +mask+ of '*'.
+    
+    def password msg = "Password: ", mask = '*'
+      pass = ask(msg) { |q| q.echo = mask }
+      pass = password msg, mask if pass.empty?
+      pass
+    end
+    
+    ##
+    # 'Log' an _action_ to the terminal. This is typically used
+    # for verbose output regarding actions performed. For example:
+    #
+    #   create  path/to/file.rb
+    #   remove  path/to/old_file.rb
+    #   remove  path/to/old_file2.rb
+    #
+    # To alter this format simply change the Commander::UI::LOG_FORMAT
+    # constant to whatever you like.
+    
+    def log action, *args
+      say LOG_FORMAT % [action, args.join(' ')]
+    end
+    
+    ##
+    # = Progress Bar
+    #
+    # Terminal progress bar utility. In its most basic form
+    # requires that the developer specifies when the bar should
+    # be incremented:
+    #
+    #    uris = %w[ 
+    #      http://vision-media.ca
+    #      http://yahoo.com
+    #      http://google.com
+    #      ]
+    #
+    #    bar = Commander::UI::ProgressBar.new uris.length, options
+    #    threads = []
+    #    uris.each do |uri|
+    #      threads << Thread.new do
+    #        begin
+    #          res = open uri
+    #          bar.inc :uri => uri
+    #        rescue Exception => e
+    #          bar.inc :uri => "#{uri} failed"
+    #        end
+    #      end
+    #    end
+    #    threads.each { |t| t.join }
+    #
+    # The Kernel method #progress is also available, below are
+    # single and multi-threaded examples:
+    #
+    #    progress uris, :width => 10 do |uri|
+    #      res = open uri
+    #    end
+    #    
+    #    threads = uris.collect { |uri| Thread.new { res = open uri } } 
+    #    progress threads, :progress_char => '-' do |thread|
+    #      thread.join
+    #    end
+    #
+
+    class ProgressBar
+
+      ##
+      # Creates a new progress bar.
+      #
+      # === Options:
+      #    
+      #    :title              Title, defaults to "Progress"
+      #    :width              Width of :progress_bar
+      #    :progress_char      Progress character, defaults to "="
+      #    :incomplete_char    Incomplete bar character, defaults to '.'
+      #    :format             Defaults to ":title |:progress_bar| :percent_complete% complete "
+      #    :tokens             Additional tokens replaced within the format string
+      #    :complete_message   Defaults to "Process complete"
+      #
+      # === Tokens:
+      #
+      #    :title 
+      #    :percent_complete
+      #    :progress_bar
+      #    :current
+      #    :remaining
+      #    :total
+      #    :output
+      #    :time_elapsed
+      #    :time_remaining
+      #
+
+      def initialize total, options = {}
+        @total, @options, @current, @start = total, options, 0, Time.now
+        @options = {
+          :title => "Progress",
+          :width => 25,
+          :progress_char => "=",
+          :incomplete_char => ".",
+          :complete_message => "Process complete",
+          :format => ":title |:progress_bar| :percent_complete% complete ",
+          :output => $stderr, 
+          :tokens => {},
+        }.merge! options
+        show
+      end
+
+      ##
+      # Output the progress bar.
+
+      def show
+        unless @current >= (@total + 1)
+          erase_line
+          percent = (@current * 100) / @total
+          elapsed = Time.now - @start
+          remaining = @total - @current
+          tokens = {
+            :title => @options[:title],
+            :percent_complete => percent,
+            :progress_bar => (@options[:progress_char] * (@options[:width] * percent / 100)).ljust(@options[:width], @options[:incomplete_char]), 
+            :current => @current,
+            :remaining => remaining,
+            :total => @total, 
+            :time_elapsed => "%0.2fs" % [elapsed],
+            :time_remaining => "%0.2fs" % [(elapsed / @current) * remaining],
+          }.merge! @options[:tokens]
+          if completed?
+            @options[:output].print @options[:complete_message].tokenize(tokens) << "\n" if @options[:complete_message].is_a? String
+          else
+            @options[:output].print @options[:format].tokenize(tokens)
+          end
+        end
+      end
+
+      ##
+      # Weither or not the operation has completed.
+
+      def completed?
+        @current == @total
+      end
+      alias :finished? :completed?
+
+      ##
+      # Increment progress. Optionally pass _tokens_ which
+      # can be displayed in the output format.
+
+      def increment tokens = {}
+        @current += 1
+        @options[:tokens].merge! tokens if tokens.is_a? Hash
+        show
+      end
+      alias :inc :increment
+
+      ##
+      # Erase previous terminal line.
+
+      def erase_line
+        @options[:output].print "\r\e[K"
+      end
+
+      ##
+      # Output progress while iterating _enum_.
+      #
+      # === Example:
+      #
+      #    uris = %[ http://vision-media.ca http://google.com ]
+      #    ProgressBar.progress uris, :format => "Remaining: :time_remaining" do |uri|
+      #      res = open uri
+      #    end
+      #
+      # === See:
+      #
+      # * Kernel#progress
+
+      def self.progress enum, options = {}, &block
+        threads = []
+        bar = ProgressBar.new enum.length, options
+        enum.each { |v| bar.inc yield(v) } 
+      end
+    end
+  end
+end

data/lib/commander/version.rb

@@ -1,7 +1,7 @@
 
 module Commander
-  MAJOR = 1
-  MINOR = 2
-  TINY = 2
-  VERSION = [MAJOR, MINOR, TINY].join('.')  
+  module VERSION #:nodoc:
+    MAJOR, MINOR, TINY = [2, 4, 2]
+    STRING = [MAJOR, MINOR, TINY].join '.'
+  end
 end

data/lib/commander.rb

@@ -1,9 +1,49 @@
+#--
+# Copyright (c) 2008 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.
+#++
 
-$:.unshift(File.expand_path(File.dirname(__FILE__)))
+$:.unshift File.dirname(__FILE__)
 
-require 'commander/commander'
+require 'rubygems'
 require 'highline/import'
- 
-class Object
-  include Commander
-end
+require 'commander/version'
+require 'commander/user_interaction'
+require 'commander/fileutils'
+require 'commander/core_ext'
+require 'commander/runner'
+require 'commander/command'
+require 'commander/help_formatters'
+require 'commander/import'
+
+$command_runner = Commander::Runner.new
+
+# Highline terminal settings
+$terminal.wrap_at = HighLine::SystemExtensions.terminal_size.first - 10 rescue 80
+
+# Display friendly interruption message
+trap 'INT' do 
+  say program(:int_message)
+  exit
+end
+
+# Auto-execute command runner
+at_exit { $command_runner.run! }