rubikon 0.5.1 → 0.5.2

data/lib/core_ext/enumerable.rb

@@ -0,0 +1,31 @@
+# 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
+
+unless Enumerable.method_defined?(:max_by)
+
+  # Extends Ruby's own Enumrable module with method #max_by? for Ruby < 1.8.7
+  #
+  # @author Sebastian Staudt
+  # @since 0.5.0
+  module Enumerable
+
+    def find_index(obj)
+      
+    end
+
+    # Returns the object in enum that gives the maximum value from the given
+    # block.
+    #
+    # @yield [obj] The block to call on each element in the enum
+    # @yieldparam [Object] obj A single object in the enum
+    # @yieldreturn [Comparable] A value that can be compared (+<=>+) with the
+    #              values of the other objects in the enum
+    def max_by(&block)
+      max { |a , b| block.call(a) <=> block.call(b) }
+    end
+
+  end
+
+end

data/lib/rubikon/application/dsl_methods.rb

@@ -32,6 +32,7 @@ module Rubikon
       # user on the command-line.
       #
       # @param [#to_sym] name The name of the parameter to check
+      # @see Parameter
       # @since 0.2.0
       #
       # @example
@@ -73,6 +74,8 @@ module Rubikon
       #        is called with the associated parameter
       #
       # @return [Command]
+      # @see default
+      # @see Command
       # @since 0.2.0
       def command(name, arg_count = nil, description = nil, &block)
         command = nil
@@ -127,6 +130,8 @@ module Rubikon
       #        parameter is given to the application
       #
       # @return [Command] The default Command object
+      # @see Command
+      # @see command
       # @since 0.2.0
       def default(arg_count = nil, description = nil, &block)
         if arg_count.is_a? Symbol
@@ -275,6 +280,7 @@ module Rubikon
       #        arbitrary number of arguments
       # @param [Proc] block An optional code block that should be executed if
       #        this option is used
+      # @see Option
       # @since 0.2.0
       #
       # @example
@@ -439,6 +445,7 @@ module Rubikon
       #
       # @param [Proc] block The block to execute while the throbber is
       #        displayed
+      # @see Throbber
       # @since 0.2.0
       # @yield While the block is executed a throbber is displayed
       #

data/lib/rubikon/application/instance_methods.rb

@@ -51,6 +51,7 @@ module Rubikon
         @parameters           = []
         @sandbox              = Sandbox.new(self)
         @settings             = {
+          :autohelp        => true,
           :autorun         => true,
           :colors          => true,
           :config_file     => "#{self.class.to_s.downcase}.yml",
@@ -109,9 +110,14 @@ module Rubikon
         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
+            puts "r{Error:}\n    #{$!.message}"
+            debug "     at #{$!.backtrace.join("\n     at ")}"
+            exit 1
+          end
         ensure
           InstanceMethods.instance_method(:reset).bind(self).call
         end
@@ -149,6 +155,38 @@ module Rubikon
         global_flag :d => :debug
       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 +196,11 @@ module Rubikon
         global_parameters = @global_parameters
         settings = @settings
 
-        command :help, nil, 'Display this help screen' do
+        command :help, 0..1, 'Show help for the application or a single command' 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 +211,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 args.first.nil?
+            command = args.first.to_sym
+            if commands.keys.include?(command)
+              puts commands[command].help
+            else
+              app_help.call("The command \"#{command}\" is undefined. The following commands are available:")
+            end
+          else
+            app_help.call(nil)
           end
         end
       end
@@ -240,7 +273,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
 
@@ -299,19 +333,22 @@ module Rubikon
       #         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_arg = args.find { |arg| arg == '--' || !arg.start_with?('-') }
+        command_arg = nil if command_arg == '--'
+
+        if command_arg.nil?
           command = @commands[:__default]
-          args.unshift(command_arg) unless command_arg.nil?
           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}"}
+            arg[1..-1].split('').map { |a| "-#{a}" }
           else
             arg
           end
@@ -354,7 +391,7 @@ module Rubikon
       # @see Parameter#reset
       # @since 0.4.0
       def reset
-        ostream.rewind
+        ostream.rewind if ostream.is_a? StringIO || !ostream.stat.chardev?
         ColoredIO.remove_color_filter(ostream)
         (@commands.values + @global_parameters.values).uniq.each do |param|
           param.send :reset

data/lib/rubikon/command.rb

@@ -14,6 +14,8 @@ module Rubikon
   # be executed when running the Application.
   #
   # @author Sebastian Staudt
+  # @see Application::DSLMethods#command
+  # @see Application::DSLMethods#default
   # @since 0.3.0
   class Command
 
@@ -56,6 +58,66 @@ module Rubikon
       end
     end
 
+    # Generate help for this command
+    #
+    # @param [Boolean] show_usage If +true+, the returned String will also
+    #        include usage information
+    # @return [String] The contents of the help screen for this command
+    # @since 0.6.0
+    def help(show_usage = true)
+      help = ''
+
+      if show_usage
+        help << " #{name}" if name != :__default
+
+        @params.values.uniq.sort_by {|a| a.name.to_s }.each do |param|
+          help << ' ['
+          ([param.name] + param.aliases).each_with_index do |name, index|
+            name = name.to_s
+            help << '|' if index > 0
+            help << '-' if name.size > 1
+            help << "-#{name}"
+          end
+          help << ' ...' if param.is_a?(Option)
+          help << ']'
+        end
+      end
+
+      help << "\n\n#{description}" unless description.nil?
+
+      help_flags = {}
+      help_options = {}
+      params.each_value do |param|
+        if param.is_a? Flag
+          help_flags[param.name.to_s] = param
+        else
+          help_options[param.name.to_s] = param
+        end
+      end
+
+      param_name = lambda { |name| "#{name.size > 1 ? '-' : ' '}-#{name}" }
+      unless help_flags.empty? && help_options.empty?
+        max_param_length = (help_flags.keys + help_options.keys).
+          max_by { |a| a.size }.size + 2
+      end
+
+      unless help_flags.empty?
+        help << "\n\nFlags:"
+        help_flags.sort_by { |name, param| name }.each do |name, param|
+          help << "\n  #{param_name.call(name).ljust(max_param_length)}"
+        end
+      end
+
+      unless help_options.empty?
+      help << "\n\nOptions:\n"
+        help_options.sort_by { |name, param| name }.each do |name, param|
+          help << "  #{param_name.call(name).ljust(max_param_length)} ...\n"
+        end
+      end
+
+      help
+    end
+
     private
 
     # Add a new parameter for this command

data/lib/rubikon/exceptions.rb

@@ -45,6 +45,7 @@ module Rubikon
   # Raised if the user did not specify a command and no default command exists
   #
   # @author Sebastian Staudt
+  # @see Application::DSLMethods#default
   # @since 0.3.0
   class NoDefaultCommandError < ArgumentError
 
@@ -57,11 +58,20 @@ module Rubikon
   # Raised if a command has been supplied that does not exist
   #
   # @author Sebastian Staudt
+  # @see Application::DSLMethods#command
   # @since 0.3.0
   class UnknownCommandError < ArgumentError
 
+    # @return [Symbol] The name of the command that has been tried to access
+    attr_reader :command
+
+    # Creates a new error and stores the name of the command that could not be
+    # found
+    #
+    # @param [Symbol] name The name of the unknown command
     def initialize(name)
       super "Unknown command: #{name}"
+      @command = name
     end
 
   end
@@ -69,6 +79,10 @@ module Rubikon
   # Raised if a parameter has been supplied that does not exist
   #
   # @author Sebastian Staudt
+  # @see Application::DSLMethods#flag
+  # @see Application::DSLMethods#option
+  # @see Application::DSLMethods#global_flag
+  # @see Application::DSLMethods#global_option
   # @since 0.3.0
   class UnknownParameterError < ArgumentError
 

data/lib/rubikon/flag.rb

@@ -10,8 +10,8 @@ module Rubikon
   # A flag is an application parameter without arguments
   #
   # @author Sebastian Staudt
-  # @see Application::InstanceMethods#flag
-  # @see Application::InstanceMethods#global_flag
+  # @see Application::DSLMethods#flag
+  # @see Application::DSLMethods#global_flag
   # @see Parameter
   # @since 0.3.0
   class Flag

data/lib/rubikon/has_arguments.rb

@@ -72,6 +72,7 @@ module Rubikon
     #        indices can be used always while symbolic arguments are only
     #        available for named arguments.
     # @return The argument with the specified index
+    # @see #args
     # @since 0.4.0
     def [](arg)
       arg = @arg_names.index(arg) if arg.is_a? Symbol

data/lib/rubikon/option.rb

@@ -11,7 +11,8 @@ module Rubikon
   # arguments.
   #
   # @author Sebastian Staudt
-  # @see Application::InstanceMethods#option
+  # @see Application::DSLMethods#option
+  # @see Application::DSLMethods#global_option
   # @see Parameter
   # @since 0.3.0
   class Option

data/lib/rubikon/parameter.rb

@@ -11,6 +11,8 @@ module Rubikon
   #
   # @author Sebastian Staudt
   # @see Command
+  # @see Flag
+  # @see Option
   # @since 0.3.0
   module Parameter
 

data/lib/rubikon/progress_bar.rb

@@ -9,7 +9,7 @@ module Rubikon
   # A class for displaying and managing progress bars
   #
   # @author Sebastian Staudt
-  # @see Application::InstanceMethods#throbber
+  # @see Application::DSLMethods#progress_bar
   # @since 0.2.0
   class ProgressBar
 

data/lib/rubikon/throbber.rb

@@ -8,7 +8,7 @@ module Rubikon
   # A class for displaying and managing throbbers
   #
   # @author Sebastian Staudt
-  # @see Application::InstanceMethods#throbber
+  # @see Application::DSLMethods#throbber
   # @since 0.2.0
   class Throbber < Thread
 

data/lib/rubikon.rb

@@ -24,6 +24,6 @@ require 'rubikon/application/base'
 module Rubikon
 
   # This is the current version of the Rubikon gem
-  VERSION = '0.5.1'
+  VERSION = '0.5.2'
 
 end

data/test/test_application.rb

@@ -120,7 +120,7 @@ class TestApplication < Test::Unit::TestCase
 
     should 'have a working help command' do
       @app.run(%w{help})
-      assert_match /Usage: [^ ]* \[--debug\|-d\] \[--gflag\|--gf1\|--gf2\] \[--gopt\|--go1\|--go2 \.\.\.\] \[--verbose\|-v\] command \[args\]\n\nCommands:\n  arguments      \n  globalopt      \n  help           Display this help screen\n  input          \n  object_id      \n  parameters     \n  progressbar    \n  sandbox        \n  throbber       \n/, @ostream.string
+      assert_match /Usage: [^ ]* \[--debug\|-d\] \[--gflag\|--gf1\|--gf2\] \[--gopt\|--go1\|--go2 \.\.\.\] \[--verbose\|-v\] \[command\] \[args\]\n\nCommands:\n  arguments      \n  globalopt      \n  help           Show help for the application or a single command\n  input          \n  object_id      \n  parameters     \n  progressbar    \n  sandbox        \n  throbber       \n/, @ostream.string
     end
 
     should 'have a working DSL for command parameters' do

data/test/testapps.rb

@@ -13,6 +13,7 @@ end
 
 class TestApp < Application::Base
 
+  set :autohelp, false
   set :autorun, false
   set :name, 'Rubikon test application'
   set :raise_errors, true
@@ -29,7 +30,7 @@ class TestApp < Application::Base
   end
   global_option :go2 => :gopt
 
-  default do
+  default nil, :hidden do
     'default command'
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rubikon
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 15
   prerelease: false
   segments: 
   - 0
   - 5
-  - 1
-  version: 0.5.1
+  - 2
+  version: 0.5.2
 platform: ruby
 authors: 
 - Sebastian Staudt
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-01 00:00:00 +01:00
+date: 2010-12-04 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -74,6 +74,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/core_ext/enumerable.rb
 - lib/core_ext/object.rb
 - lib/core_ext/string.rb
 - lib/rubikon.rb