rubikon 0.2.1 → 0.3.0

data/lib/rubikon/application/instance_methods.rb

@@ -1,8 +1,12 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2009, Sebastian Staudt
+# Copyright (c) 2009-2010, Sebastian Staudt
 
+require 'rubikon/command'
+require 'rubikon/exceptions'
+require 'rubikon/flag'
+require 'rubikon/option'
 require 'rubikon/progress_bar'
 require 'rubikon/throbber'
 
@@ -10,183 +14,70 @@ module Rubikon
 
   module Application
 
+    # This module contains internal instance methods of +Application::Base+ and
+    # its subclasses.
+    #
+    # @author Sebastian Staudt
+    # @see Application::Base
+    # @since 0.2.0
     module InstanceMethods
 
-      # Initialize with default settings (see set for more detail)
-      #
-      # If you really need to override this in your application class, be sure to
-      # call +super+
-      def initialize
-        @actions     = {}
-        @aliases     = {}
-        @default     = nil
-        @initialized = false
-        @settings    = {
-          :autorun        => true,
-          :auto_shortopts => true,
-          :dashed_options => true,
-          :help_banner    => "Usage: #{$0}",
-          :istream        => $stdin,
-          :name           => self.class.to_s,
-          :ostream        => $stdout,
-          :raise_errors   => false
-        }
-      end
-
-      # Define an Application Action
-      #
-      # +name+::    The name of the action. Used as an option parameter.
-      # +options+:: A Hash of options to be used on the created Action
-      #             (default: <tt>{}</tt>)
-      # +block+::   A block containing the code that should be executed when this
-      #             Action is called, i.e. when the Application is called with
-      #             the associated option parameter
-      def action(name, options = {}, &block)
-        raise "No block given" unless block_given?
-
-        action = Action.new(options, &block)
-
-        key = name.to_s
-        if @settings[:dashed_options]
-          if @settings[:auto_shortopts]
-            short_key = "-#{key[0..0]}"
-            @actions[short_key.to_sym] = action unless @actions.key? short_key
-          end
-          key = "--#{key}"
-        end
-
-        @actions[key.to_sym] = action
-      end
-
-      # Define an alias to an Action
-      #
-      # +name+::   The name of the alias
-      # +action+:: The name of the Action that should be aliased
-      #
-      # Example:
-      #
-      #  action_alias :doit, :dosomething
-      def action_alias(name, action)
-        @aliases[name.to_sym] = action.to_sym
-      end
-
-      # Define the default Action of the Application
-      #
-      # +options+:: A Hash of options to be used on the created Action
-      #             (default: <tt>{}</tt>)
-      # +block+::   A block containing the code that should be executed when this
-      #             Action is called, i.e. when no option is given to the
-      #             Application
-      def default(options = {}, &block)
-        @default = Action.new(options, &block)
-      end
-
-      # Prompts the user for input
-      #
-      # If +prompt+ is not empty this will display a prompt using
-      # <tt>prompt.to_s</tt>.
-      #
-      # +prompt+:: A String or other Object responding to +to_s+ used for
-      #            displaying a prompt to the user (default: <tt>''</tt>)
-      #
-      # Example:
-      #
-      #  action 'interactive' do
-      #    # Display a prompt "Please type something: "
-      #    user_provided_value = input 'Please type something'
-      #
-      #    # Do something with the data
-      #    ...
-      #  end
-      def input(prompt = '')
-        unless prompt.to_s.empty?
-          ostream << "#{prompt}: "
-        end
-        @settings[:istream].gets[0..-2]
-      end
-
-      # Convenience method for accessing the user-defined output stream
-      #
-      # Use this if you want to work directly with the output stream
-      #
-      # Example:
-      #
-      #  ostream.flush
-      def ostream
-        @settings[:ostream]
-      end
-
-      # Displays a progress bar while the given block is executed
-      #
-      # Inside the block you have access to a instance of ProgressBar. So you
-      # can update the progress using <tt>ProgressBar#+</tt>.
-      #
-      # +options+:: A Hash of options that should be passed to the ProgressBar
-      #             object. For available options see ProgressBar
-      # +block+::   The block to execute
-      #
-      # Example:
-      #
-      #  progress_bar(:maximum => 5) do |progress|
-      #    5.times do |file|
-      #      File.read("any#{file}.txt")
-      #      progress.+
-      #    end
-      #  end
-      def progress_bar(*options, &block)
-        hidden_output do |ostream|
-          options = options[0]
-          options[:ostream] = ostream
-
-          progress = ProgressBar.new(options)
-
-          block.call(progress)
-        end
-      end
+      # @return [String] The absolute path of the application
+      attr_reader :path
 
-      # Output text using +IO#<<+ of the output stream
+      # Initialize with default settings
       #
-      # +text+:: The text to write into the output stream
-      def put(text)
-        @settings[:ostream] << text
-        @settings[:ostream].flush
-      end
-
-      # Output a character using +IO#putc+ of the output stream
+      # If you really need to override this in your application class, be sure
+      # to call +super+
       #
-      # +char+:: The character to write into the output stream
-      def putc(char)
-        @settings[:ostream].putc char
-      end
-
-      # Output a line of text using +IO#puts+ of the output stream
-      #
-      # +text+:: The text to write into the output stream
-      def puts(text)
-        @settings[:ostream].puts text
+      # @see #set
+      def initialize
+        @commands              = {}
+        @current_command       = nil
+        @current_global_option = nil
+        @global_parameters     = {}
+        @initialized           = false
+        @parameters            = []
+        @path                  = File.dirname($0)
+        @settings              = {
+          :autorun         => true,
+          :help_as_default => true,
+          :help_banner     => "Usage: #{$0}",
+          :istream         => $stdin,
+          :name            => self.class.to_s,
+          :ostream         => $stdout,
+          :raise_errors    => false
+        }
       end
 
       # Run this application
       #
-      # +args+:: The command line arguments that should be given to the
-      #          application as options
+      # Calling this method explicitly is not required when you want to create
+      # a simple application (having one main class inheriting from
+      # Rubikon::Application). But it's useful for testing or if you want to
+      # have some sort of sub-applications.
       #
-      # Calling this method explicitly is not required when you want to create a
-      # simple application (having one main class inheriting from
-      # Rubikon::Application). But it's useful for testing or if you want to have
-      # some sort of sub-applications.
+      # @param [Array<String>] args The command line arguments that should be
+      #        given to the application as options
       def run(args = ARGV)
-        init unless @initialized
-        action_results = []
-
         begin
-          if !@default.nil? and args.empty?
-            action_results << @default.run
-          else
-            parse_options(args).each do |action, args|
-              action_results << @actions[action].run(*args)
+          init unless @initialized
+
+          command, parameters, args = parse_arguments(args)
+
+          parameters.each do |parameter|
+            if parameter.is_a? Option
+              parameter.check_args
+              @current_global_option = parameter
             end
+            parameter.active!
+            @current_global_option = nil
           end
+
+          @current_command = command
+          result = command.run(*args)
+          @current_command = nil
+          result
         rescue
           raise $! if @settings[:raise_errors]
 
@@ -194,96 +85,62 @@ module Rubikon
           puts "    #{$!.backtrace.join("\n    ")}" if $DEBUG
           exit 1
         end
-
-        action_results
-      end
-
-      # Sets an application setting
-      #
-      # +setting+:: The name of the setting to change, will be symbolized first.
-      # +value+::   The value the setting should be changed to
-      #
-      # Available settings
-      # +autorun+::        If true, let the application run as soon as its class
-      #                    is defined
-      # +dashed_options+:: If true, each option is prepended with a double-dash
-      #                    (<tt>-</tt><tt>-</tt>)
-      # +help_banner+::    Defines a banner for the help message (<em>unused</em>)
-      # +istream+::        Defines an input stream to use
-      # +name+::           Defines the name of the application
-      # +ostream+::        Defines an output stream to use
-      # +raise_errors+::   If true, raise errors, otherwise fail gracefully
-      #
-      # Example:
-      #
-      #  set :name, 'My App'
-      #  set :autorun, false
-      def set(setting, value)
-        @settings[setting.to_sym] = value
-      end
-
-      # Displays a throbber while the given block is executed
-      #
-      # Example:
-      #
-      #  action 'slow' do
-      #    throbber do
-      #      # Add some long running code here
-      #      ...
-      #    end
-      #  end
-      def throbber(&block)
-        hidden_output do |ostream|
-          code_thread = Thread.new { block.call }
-          throbber_thread = Throbber.new(ostream, code_thread)
-
-          code_thread.join
-          throbber_thread.join
-        end
       end
 
       private
 
-      # Assigns aliases to the actions that have been defined using action_alias
+      # Defines a global Flag for enabling debug output
       #
-      # Clears the aliases Hash afterwards
-      def assign_aliases
-        @aliases.each do |key, action|
-          if @settings[:dashed_options]
-            action = "--#{action}".to_sym
-            key = "--#{key}".to_sym
-          end
-
-          unless @actions.key? key
-            @actions[key] = @actions[action]
-          else
-            warn "There's already an action called \"#{key}\"."
-          end
+      # This will define a Flag <tt>--debug</tt> (with alias <tt>-d</tt>) to
+      # enable debug output.
+      # Using it sets Ruby's global variable <tt>$DEBUG</tt> to +true+.
+      #
+      # @return [Flag]
+      def debug_flag
+        global_flag :debug do
+          $DEBUG = true
         end
+        global_flag :d => :debug
       end
 
-      # Defines an action for displaying a help screen
+      # Defines a command for displaying a help screen
       #
-      # This takes any defined action and it's corresponding options and
+      # This takes any defined commands and it's corresponding options and
       # descriptions and displays them in a user-friendly manner.
-      def help_action
-        action 'help', { :description => 'Display this help screen' } do
+      def help_command
+        command :help, 'Display this help screen' do
+          put @settings[:help_banner]
+
           help = {}
-          @actions.each do |option, action|
-            help[action] = [] if help[action].nil?
-            help[action] << option.to_s
+          @commands.each_value do |command|
+            help[command.name.to_s] = command.description
           end
 
-          put @settings[:help_banner]
-          puts " [options]" unless @default.nil?
-          puts ''
+          global_params = ''
+          @global_parameters.values.uniq.sort {|a,b| a.name.to_s <=> b.name.to_s }.each do |param|
+            global_params << ' ['
+            ([param.name] + param.aliases).each_with_index do |name, index|
+              name = name.to_s
+              global_params << '|' if index > 0
+              global_params << '-' if name.size > 1
+              global_params << "-#{name}"
+            end
+            global_params << ' ...' if param.is_a?(Option)
+            global_params << ']'
+          end
 
-          help.each do |action, options|
-            help[action] = options.sort.join(', ')
+          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
-          max_options_length = help.values.max { |a,b| a.size <=> b.size }.size
-          help.sort_by { |action, options| options }.each do |action, options|
-            puts options.ljust(max_options_length) << "    " << action.description
+
+          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}"
           end
         end
       end
@@ -291,7 +148,8 @@ module Rubikon
       # Hide output inside the given block and print it after the block has
       # finished
       #
-      # +block+:: The block that should not print output while it's running
+      # @param [Proc] block The block that should not print output while it's
+      #        running
       #
       # If the block needs to print to the real IO stream, it can access it
       # using its first parameter.
@@ -310,32 +168,73 @@ module Rubikon
       # run, but <em>after</em> the application is setup, i.e. after the user
       # has defined the application class.
       def init
-        help_action
-        assign_aliases
+        debug_flag
+        help_command
+        verbose_flag
+
+        if @settings[:help_as_default] && !@commands.keys.include?(:__default)
+          default :help
+        end
+
         @initialized = true
       end
 
-      # Parses the options used when starting the application
-      #
-      # +options+:: An Array of Strings that should be used as application
-      #             options. Usually +ARGV+ is used for this.
-      def parse_options(options)
-        actions_to_call = {}
-        last_action     = nil
-
-        options.each do |option|
-          option_sym = option.to_s.to_sym
-          if @actions.keys.include? option_sym
-            actions_to_call[option_sym] = []
-            last_action = option_sym
-          elsif last_action.nil? || (option.is_a?(String) && @settings[:dashed_options] && option[0..1] == '--')
-            raise UnknownOptionError.new(option)
+      # Parses the command-line arguments given to the application by the
+      # 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.shift
+        if command_arg.nil? || command_arg.start_with?('-')
+          command = @commands[:__default]
+          args.unshift(command_arg) unless command_arg.nil?
+          raise NoDefaultCommandError if command.nil?
+        else
+          command = @commands[command_arg.to_sym]
+          raise UnknownCommandError.new(command_arg) if command.nil?
+        end
+
+        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]
           else
-            actions_to_call[last_action] << option
+            if !parameter.nil? && parameter.more_args?
+              parameter.args << args.delete(arg)
+            else
+              parameter = nil
+            end
+            next
+          end
+
+          unless parameter.nil?
+            parameters << parameter
+            args.delete(arg)
           end
         end
 
-        actions_to_call
+        return command, parameters, args
+      end
+
+      # Defines a global Flag for enabling verbose output
+      #
+      # This will define a Flag <tt>--verbose</tt> and <tt>-v</tt> to enable
+      # verbose output.
+      # Using it sets Ruby's global variable <tt>$VERBOSE</tt> to +true+.
+      #
+      # @return [Flag] The debug Flag object
+      def verbose_flag
+        global_flag :verbose do
+          $VERBOSE = true
+        end
+        global_flag :v => :verbose
       end
 
     end

data/lib/rubikon/command.rb

@@ -0,0 +1,135 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2010, Sebastian Staudt
+
+require 'rubikon/application/base'
+require 'rubikon/exceptions'
+require 'rubikon/parameter'
+
+module Rubikon
+
+  # Instances of the Command class are used to define the real code that should
+  # be executed when running the Application.
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
+  class Command
+
+    include Parameter
+
+    attr_accessor :description
+    attr_reader   :args, :params
+    alias_method  :arguments, :args
+    alias_method  :parameters, :params
+
+    # Create a new application command with the given name with a reference to
+    # the app it belongs to
+    #
+    # @param [Application::Base] app A reference to the application 
+    #        instance this command belongs to
+    # @param [#to_sym] name The name of this command, used in application
+    #        arguments
+    # @param [Proc] block The code block which should be executed by this
+    #        command
+    # @raise [ArgumentError] if the given application object isn't a Rubikon
+    #        application
+    # @raise [BlockMissingError] if no command code block is given and a
+    #        command file does not exist
+    def initialize(app, name, &block)
+      raise ArgumentError unless app.is_a? Application::Base
+      super(name, nil)
+
+      @app    = app
+      @params = {}
+
+      if block_given?
+        @block = block
+      else
+        @file_name = "#{@app.path}/commands/#{name}.rb"
+        raise BlockMissingError unless File.exists?(@file_name)
+        code = open(@file_name).read
+        @block = Proc.new { instance_eval(code) }
+      end
+    end
+
+    # Add a new Parameter for this command
+    #
+    # @param [Parameter, Hash] parameter The parameter to add to this 
+    #        command. This might also be a Hash where every key will be an
+    #        alias to the corresponding value, e.g. <tt>{ :alias => :parameter
+    #        }</tt>.
+    # @see Parameter
+    def <<(parameter)
+      if parameter.is_a? Hash
+        parameter.each do |alias_name, name|
+          alias_name = alias_name.to_sym
+          name = name.to_sym
+          parameter = @params[name]
+          if parameter.nil?
+            @params[alias_name] = name
+          else
+            parameter.aliases << alias_name
+            @params[alias_name] = parameter
+          end
+        end
+      else
+        raise ArgumentError unless parameter.is_a? Parameter
+        @params.each do |name, param|
+          if param == parameter.name
+            parameter.aliases << name
+          end
+        end
+        @params[parameter.name] = parameter
+      end
+    end
+
+    # Parses the arguments of this command and sets each Parameter as active
+    # if it has been supplied by the user on the command-line. Additional
+    # arguments are passed to the individual parameters.
+    #
+    # @param [Array<String>] args The arguments that have been passed to this
+    #        command
+    # @raise [UnknownParameterError] if an undefined parameter is passed to the
+    #        command
+    # @see Flag
+    # @see Option
+    def parse_arguments(args)
+      @args = []
+      parameter = nil
+      args.each do |arg|
+        if arg.start_with?('-')
+          parameter_name = arg.start_with?('--') ? arg[2..-1] : arg[1..-1]
+          parameter = @params[parameter_name.to_sym]
+          raise UnknownParameterError.new(arg) if parameter.nil?
+        end
+
+        unless parameter.nil? || parameter.active?
+          parameter.active!
+          next
+        end
+
+        if parameter.nil? || !parameter.more_args?
+          @args << arg
+        else
+          parameter << arg
+        end
+      end
+
+      @params.values.each do |param|
+        param.check_args if param.is_a?(Option) && param.active?
+      end
+    end
+
+    # Run this command's code block
+    #
+    # @param [Array<String>] args The arguments that have been passed to this
+    #        command
+    def run(*args)
+      parse_arguments(args)
+      @app.instance_eval(&@block)
+    end
+
+  end
+
+end