rubikon 0.5.3 → 0.6.0

data/lib/rubikon/application/instance_methods.rb

@@ -1,16 +1,17 @@
 # This code is free software; you can redistribute it and/or modify it under
 # the terms of the new BSD License.
 #
-# Copyright (c) 2009-2010, Sebastian Staudt
+# Copyright (c) 2009-2011, Sebastian Staudt
 
 require 'pathname'
 require 'stringio'
 
 require 'rubikon/application/sandbox'
+require 'rubikon/argument_vector'
 require 'rubikon/colored_io'
 require 'rubikon/command'
 require 'rubikon/config/factory'
-require 'rubikon/exceptions'
+require 'rubikon/errors'
 require 'rubikon/flag'
 require 'rubikon/option'
 require 'rubikon/progress_bar'
@@ -41,16 +42,17 @@ module Rubikon
       #
       # @see #set
       def initialize
-        @commands             = {}
-        @current_command      = nil
-        @current_global_param = nil
-        @current_param        = nil
-        @global_parameters    = {}
-        @hooks                = {}
-        @initialized          = false
-        @parameters           = []
-        @sandbox              = Sandbox.new(self)
-        @settings             = {
+        @commands          = {}
+        @current_command   = nil
+        @current_param     = nil
+        @default_config    = {}
+        @global_parameters = {}
+        @hooks             = {}
+        @initialized       = false
+        @parameters        = []
+        @sandbox           = Sandbox.new(self)
+        @settings          = {
+          :autohelp        => true,
           :autorun         => true,
           :colors          => true,
           :config_file     => "#{self.class.to_s.downcase}.yml",
@@ -60,15 +62,17 @@ module Rubikon
           :raise_errors    => false
         }
 
-        @settings[:config_paths] = []
         if RUBY_PLATFORM.downcase =~ /mswin(?!ce)|mingw|bccwin/
-          @settings[:config_paths] << ENV['ALLUSERSPROFILE']
+          global_config_path = ENV['ALLUSERSPROFILE']
         else
-          @settings[:config_paths] << '/etc'
+          global_config_path = '/etc'
         end
-        @settings[:config_paths] << File.expand_path('~')
-        @settings[:config_paths] << File.expand_path('.')
 
+        @settings[:config_paths] = [
+          global_config_path, File.expand_path('~'), File.expand_path('.')
+        ]
+
+        self.estream = $stderr
         self.ostream = $stdout
       end
 
@@ -86,32 +90,46 @@ module Rubikon
 
         begin
           InstanceMethods.instance_method(:init).bind(self).call
-          command, parameters, args = InstanceMethods.
+          global_params, command, command_params = InstanceMethods.
             instance_method(:parse_arguments).bind(self).call(args)
 
-          parameters.each do |parameter|
-            @current_global_param = parameter
-            parameter.send :check_args if parameter.is_a? Option
-            parameter.send :active!
-            @current_global_param = nil
-          end
+          @config_factory = Config::Factory.new(@settings[:config_file],
+            @settings[:config_paths], @settings[:config_format])
+          @config = @default_config.merge @config_factory.config
 
-          @config = Config::Factory.new(@settings[:config_file],
-            @settings[:config_paths], @settings[:config_format]).config
+          global_params.each do |param|
+            @current_param = param
+            param.send :active!
+            @current_param = nil
+          end
 
           @current_command = command
           hook.call(:pre_execute)
-          result = command.send(:run, *args)
+
+          command_params.each do |param|
+            @current_param = param
+            param.send :active!
+            @current_param = nil
+          end
+
+          result = command.send(:run)
           hook.call(:post_execute)
           @current_command = nil
 
           result
+        rescue Interrupt
+          error "\nInterrupted... exiting."
         rescue
           raise $! if @settings[:raise_errors]
 
-          puts "r{Error:}\n    #{$!.message}"
-          puts "     at #{$!.backtrace.join("\n     at ")}" if $DEBUG
-          exit 1
+          if @settings[:autohelp] && @commands.key?(:help) &&
+             $!.is_a?(UnknownCommandError)
+            call :help, $!.command
+          else
+            error "r{Error:}\n    #{$!.message}"
+            error "     at #{$!.backtrace.join("\n     at ")}" if $DEBUG
+            exit 1
+          end
         ensure
           InstanceMethods.instance_method(:reset).bind(self).call
         end
@@ -141,7 +159,7 @@ module Rubikon
       # enable debug output.
       # Using it sets Ruby's global variable <tt>$DEBUG</tt> to +true+.
       #
-      # @return [Flag]
+      # @return [Flag] The debug flag
       def debug_flag
         global_flag :debug do
           $DEBUG = true
@@ -149,6 +167,54 @@ module Rubikon
         global_flag :d => :debug
       end
 
+      # Sets the error output stream of the application
+      #
+      # If colors are enabled, this checks if the stream supports the
+      # +color_filter+ method and enables the +ColoredIO+ if not.
+      #
+      # @param [IO] estream The output stream to use
+      # @see ColoredIO.add_color_filter
+      # @since 0.6.0
+      def estream=(estream)
+        if !estream.respond_to?(:color_filter)
+          ColoredIO.add_color_filter(estream, @settings[:colors])
+        end
+        @settings[:estream] = estream
+      end
+
+      # Prints a help screen for this application
+      #
+      # @param [String] info A additional information string to be displayed
+      #        right after usage information
+      # @since 0.6.0
+      def help(info = nil)
+        help = {}
+        @commands.each_value do |command|
+          help[command.name.to_s] = command.description
+        end
+        help.delete('__default')
+
+        if @commands.key? :__default
+          puts " [command] [args]\n\n"
+        else
+          puts " command [args]\n\n"
+        end
+
+        puts "#{info}\n\n" unless info.nil?
+
+        puts 'Commands:'
+        max_command_length = help.keys.max_by { |a| a.size }.size
+        help.sort_by { |name, description| name }.each do |name, description|
+          puts "  #{name.ljust(max_command_length)}    #{description}"
+        end
+
+        if @commands.key?(:__default) &&
+           @commands[:__default].description != '<hidden>'
+          put "\nYou can also call this application without a command:"
+          puts @commands[:__default].help(false) + "\n"
+        end
+      end
+
       # Defines a command for displaying a help screen
       #
       # This takes any defined commands and it's corresponding options and
@@ -158,16 +224,12 @@ module Rubikon
         global_parameters = @global_parameters
         settings = @settings
 
-        command :help, nil, 'Display this help screen' do
+        command :help, 'Show help for the application or a single command',
+                :cmd => :optional do
           put settings[:help_banner]
 
-          help = {}
-          commands.each_value do |command|
-            help[command.name.to_s] = command.description
-          end
-
           global_params = ''
-          global_parameters.values.uniq.sort {|a,b| a.name.to_s <=> b.name.to_s }.each do |param|
+          global_parameters.values.uniq.sort_by { |a| a.name.to_s }.each do |param|
             global_params << ' ['
             ([param.name] + param.aliases).each_with_index do |name, index|
               name = name.to_s
@@ -178,19 +240,19 @@ module Rubikon
             global_params << ' ...' if param.is_a?(Option)
             global_params << ']'
           end
+          put global_params
 
-          default_description = help.delete('__default')
-          if default_description.nil?
-            puts "#{global_params} command [args]\n\n"
-          else
-            puts "#{global_params} [command] [args]\n\n"
-            puts "Without command: #{default_description}\n\n"
-          end
+          app_help = lambda { |info| @__app__.instance_eval { help(info) } }
 
-          puts 'Commands:'
-          max_command_length = help.keys.max { |a, b| a.size <=> b.size }.size
-          help.sort_by { |name, description| name }.each do |name, description|
-            puts "  #{name.ljust(max_command_length)}    #{description}"
+          unless cmd.nil?
+            name = cmd.to_sym
+            if commands.key? name
+              puts commands[name].help
+            else
+              app_help.call("The command \"#{cmd}\" is undefined. The following commands are available:")
+            end
+          else
+            app_help.call(nil)
           end
         end
       end
@@ -240,7 +302,8 @@ module Rubikon
         InstanceMethods.instance_method(:help_command).bind(self).call
         InstanceMethods.instance_method(:verbose_flag).bind(self).call
 
-        if @settings[:help_as_default] && !@commands.keys.include?(:__default)
+        if @settings[:help_as_default] && @commands.key?(:help) &&
+           !@commands.key?(:__default)
           default :help
         end
 
@@ -267,7 +330,7 @@ module Rubikon
       #   end
       # @since 0.4.0
       def method_missing(name, *args, &block)
-        receiver = @current_param || @current_global_param || @current_command
+        receiver = @current_param || @current_command
         if receiver.nil? || (!receiver.respond_to?(name) &&
            !receiver.public_methods(false).include?(name))
           super
@@ -294,55 +357,40 @@ module Rubikon
       # user. This distinguishes between commands, global flags and command
       # flags
       #
-      # @param [Array] args The command-line arguments
-      # @return [Command, Array<Symbol>, Array] The command to execute, the
-      #         parameters of this command that have been supplied and any
-      #         additional command-line arguments supplied
-      def parse_arguments(args)
-        command_arg = args.find { |arg| arg == '--' || !arg.start_with?('-') }
-        command_arg = nil if command_arg == '--'
-
-        if command_arg.nil?
-          command = @commands[:__default]
-          raise NoDefaultCommandError if command.nil?
-        else
-          command = @commands[command_arg.to_sym]
-          args.delete_at args.index(command_arg)
-          raise UnknownCommandError.new(command_arg) if command.nil?
-        end
-
-        args.delete '--'
-        args = args.map do |arg|
-          if !arg.start_with?('--') && arg.start_with?('-') && arg.size > 2
-            arg[1..-1].split('').map { |a| "-#{a}" }
-          else
-            arg
-          end
-        end.flatten
-
-        parameter  = nil
-        parameters = []
-        args.dup.each do |arg|
-          if arg.start_with?('--')
-            parameter = @global_parameters[arg[2..-1].to_sym]
-          elsif arg.start_with?('-')
-            parameter = @global_parameters[arg[1..-1].to_sym]
+      # @param [String] argv The command-line arguments
+      # @raise [NoDefaultCommandError] if no command can be found and no
+      #        default command exists
+      # @raise [UnknownParameterError] if an unknown parameter is found
+      # @raise [UnknownParameterError] if an unknown command is found
+      # @return [Array<Parameter>] one All global parameters that have been
+      #         supplied
+      # @return [Command] two The command to execute, the parameters of this
+      #         command that have been supplied
+      # @return [Array<Parameter>] three All parameters of that command that have
+      #         been supplied
+      def parse_arguments(argv)
+        argv.extend ArgumentVector
+
+        argv.expand!
+
+        command, command_index = argv.command! @commands
+        raise NoDefaultCommandError if command.nil?
+
+        command_params = argv.params! command.params, command_index
+        global_params  = argv.params! @global_parameters
+
+        argv.scoped_args! command
+
+        unless argv.empty?
+          first = argv.first
+          if first.start_with? '-'
+            raise UnknownParameterError.new(first)
           else
-            if !parameter.nil? && parameter.send(:more_args?)
-              parameter.args << args.delete(arg)
-            else
-              parameter = nil
-            end
-            next
-          end
-
-          unless parameter.nil?
-            parameters << parameter
-            args.delete(arg)
+            raise UnknownCommandError.new(first)
           end
         end
 
-        return command, parameters, args
+        return global_params, command, command_params
       end
 
       # Resets this application to its initial state
@@ -357,8 +405,10 @@ module Rubikon
       # @see Parameter#reset
       # @since 0.4.0
       def reset
-        ostream.rewind if ostream.is_a? StringIO || !ostream.stat.chardev?
-        ColoredIO.remove_color_filter(ostream)
+        [estream, ostream].each do |stream|
+          stream.rewind if stream.is_a? StringIO || !stream.stat.chardev?
+          ColoredIO.remove_color_filter(estream)
+        end
         (@commands.values + @global_parameters.values).uniq.each do |param|
           param.send :reset
         end
@@ -370,7 +420,7 @@ module Rubikon
       # verbose output.
       # Using it sets Ruby's global variable <tt>$VERBOSE</tt> to +true+.
       #
-      # @return [Flag] The debug Flag object
+      # @return [Flag] The verbose Flag object
       def verbose_flag
         global_flag :verbose do
           $VERBOSE = true

data/lib/rubikon/argument_vector.rb

@@ -0,0 +1,119 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+module Rubikon
+
+  # This module will extend the argument array passed to the application,
+  # usually ARGV. It provides functionality to parse Rubikon specific tokens
+  # from the strings contained in the argument list passed to the application.
+  #
+  # @author Sebastian Staudt
+  # @since 0.6.0
+  module ArgumentVector
+
+    # Gets the command to use from the list of arguments passed to the
+    # application. The first argument matching a command name or alias will
+    # cause the corresponding command to be selected.
+    #
+    # The command and all arguments equal to '--' will be removed from the
+    # array.
+    #
+    # @param [Hash<Symbol, Command>] commands A list of available commands
+    # @return [Command] The command found in the argument list
+    # @return [Fixnum] The position of the command in the argument list
+    def command!(commands)
+      command = nil
+      command_index = 0
+      each_with_index do |arg, i|
+        break if arg == '--'
+
+        command = commands[arg.to_sym]
+        unless command.nil?
+          command_index = i
+          delete_at i
+          break
+        end
+      end
+      delete '--'
+
+      command ||= commands[:__default]
+
+      return command, command_index
+    end
+
+    # Turns arguments using a special syntax into arguments that are parseable.
+    #
+    # Single character parameters may be joined together like '-dv'. This
+    # method will split them into separate parameters like '-d -v'.
+    #
+    # Additionally a parameter argument may be attached to the parameter itself
+    # using '=' like '--path=/tmp'. This method will also split them into
+    # '--path /tmp'.
+    def expand!
+      each_with_index do |arg, i|
+        next if !arg.start_with?('-')
+        self[i] = arg.split('=', 2)
+        next if arg.start_with?('--')
+        self[i] = arg[1..-1].split('').uniq.map { |a| '-' + a }
+      end
+      flatten!
+    end
+
+    # Selects active parameters from a list of available parameters
+    #
+    # For every option found in the argument list {#scoped_args!} is called to
+    # find the arguments for that option.
+    #
+    # All parameters found will be removed from the array.
+    #
+    # @param [Hash<Symbol, Parameter>] params A list of available parameters
+    # @param [Fixnum] pos The position of the first argument that should be
+    #        checked. All arguments ahead of that position will be skipped.
+    # @return [Array<Parameter>] Parameters called from the given argument list
+    # @see #scoped_args
+    def params!(params, pos = 0)
+      active_params = []
+      to_delete     = []
+      each_with_index do |arg, i|
+        next if i < pos || arg.nil? || !arg.start_with?('-')
+
+        param = params[(arg.start_with?('--') ? arg[2..-1] : arg[1..1]).to_sym]
+        unless param.nil?
+          to_delete << i
+          scoped_args! param, i + 1 if param.is_a? Option
+          active_params << param
+        end
+      end
+
+      to_delete.reverse.each { |i| delete_at i }
+
+      active_params
+    end
+
+    # Gets all arguments passed to a specific scope, i.e. a command or an
+    # option.
+    #
+    # All arguments in the scope will be removed from the array.
+    #
+    # @param [HasArguments] has_args
+    # @param [Fixnum] pos The position of the first argument that should be
+    #        checked. All arguments ahead of that position will be skipped.
+    def scoped_args!(has_args, pos = 0)
+      to_delete = []
+
+      each_with_index do |arg, i|
+        next if i < pos
+        break if arg.start_with?('-') || !has_args.send(:more_args?)
+
+        to_delete << i
+        has_args.send(:<<, arg)
+      end
+
+      to_delete.reverse.each { |i| delete_at i }
+    end
+
+  end
+
+end