rubikon 0.3.0 → 0.4.0

data/README.md

@@ -28,7 +28,7 @@ Creating a Rubikon application is as simple as creating a Ruby class:
     require 'rubygems'
     require 'rubikon'
 
-    class MyApplication < Rubikon::Application
+    class MyApplication < Rubikon::Application::Base
     end
 
 If you save this code in a file called `myapp.rb` you can run it using
@@ -39,7 +39,7 @@ even more easily by typing `./myapp.rb`.
 Now go on and define what your application should do when the user runs it.
 This is done using `default`:
 
-    class MyApplication < Rubikon::Application
+    class MyApplication < Rubikon::Application::Base
 
       default do
         puts 'Hello World!'
@@ -49,9 +49,9 @@ This is done using `default`:
 
 If you run this application it will just print `Hello World!`.
 
-You can also add command-line options to your appication using `command`:
+You can also add command-line options to your application using `command`:
 
-    class MyApplication < Rubikon::Application
+    class MyApplication < Rubikon::Application::Base
 
       command :hello do
         puts 'Hello World!'
@@ -74,19 +74,18 @@ Flags and options are easily added to your application's commands using
 Rubikon's DSL:
 
     flag :more
-    option :name, 2
+    option :name, [:who]
     command :hello do
-      ...
+      puts "Hello #{who}"
     end
 
-
 Please see the `samples` directory for more in detail sample applications.
 
 **Warning**:
 
 Rubikon is still in an early development stage. If you want to use it be aware
-that you will probably run into problems and or restrictions. See the
-Contribute section if you want to help making Rubikon better.
+that you will might run into problems and or restrictions. See the Contribute
+section if you want to help to make Rubikon better.
 
 ## Features
 
@@ -132,8 +131,8 @@ You may also see Rubikon as a portmanteau word consisting of *"Ruby"* and
 ## License
 
 This code is free software; you can redistribute it and/or modify it under the
-terms of the new BSD License. A copy of this license can be found in the LICENSE
-file.
+terms of the new BSD License. A copy of this license can be found in the
+LICENSE file.
 
 ## Credits
 
@@ -146,6 +145,8 @@ file.
 * [GitHub project page][1]
 * [GitHub issue tracker][2]
 
+Follow Rubikon on Twitter [@rubikonrb](http://twitter.com/rubikonrb).
+
  [1]: http://github.com/koraktor/rubikon
  [2]: http://github.com/koraktor/rubikon/issues
  [3]: http://koraktor.github.com/rubikon

data/Rakefile

@@ -5,6 +5,7 @@
 
 require 'rake/testtask'
 
+samples_files = Dir.glob(File.join('samples', '**', '*.rb'))
 src_files = Dir.glob(File.join('lib', '**', '*.rb'))
 test_files = Dir.glob(File.join('test', '**', '*.rb'))
 
@@ -13,7 +14,7 @@ task :default => :test
 # Test task
 Rake::TestTask.new do |t|
   t.libs << 'lib' << 'test'
-  t.pattern = 'test/**/*_tests.rb'
+  t.pattern = 'test/**/test_*.rb'
   t.verbose = true
 end
 
@@ -31,13 +32,14 @@ begin
     gem.email = 'koraktor@gmail.com'
     gem.description = 'A simple to use, yet powerful Ruby framework for building console-based applications.'
     gem.date = Time.now
-    gem.files = %w(README.md Rakefile LICENSE) + src_files + test_files
+    gem.files = %w(README.md Rakefile LICENSE) + samples_files + src_files + test_files
     gem.has_rdoc = false
     gem.homepage = 'http://koraktor.github.com/rubikon'
     gem.name = gem.rubyforge_project = 'rubikon'
     gem.summary = 'Rubikon - A Ruby console app framework'
 
     gem.add_development_dependency('jeweler')
+    gem.add_development_dependency('shoulda')
     gem.add_development_dependency('yard')
   end
 rescue LoadError

data/lib/core_ext/object.rb

@@ -0,0 +1,43 @@
+# 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 Object.method_defined?(:respond_to_missing?)
+
+  # Extends Ruby's own Object class with method #start_with? for Ruby < 1.9.2
+  #
+  # @author Sebastian Staudt
+  # @since 0.4.0
+  class Object
+
+    # Returns +true+ if _obj_ responds to the given method. Private methods
+    # are included in the search only if the optional second parameter
+    # evaluates to +true+.
+    #
+    # If the method is not implemented, as Process.fork on Windows,
+    # File.lchmod on GNU/Linux, etc., +false+ is returned.
+    #
+    # If the method is not defined, respond_to_missing? method is called and
+    # the result is returned.
+    #
+    # @see #respond_to_missing?
+    def respond_to?(symbol, include_private = false)
+      super || respond_to_missing?(symbol, include_private)
+    end
+
+    # Hook method to return whether the _obj_ can respond to _id_ method or
+    # not.
+    #
+    # @param [Symbol] symbol The id of the method to check
+    # @return [Boolean] +true+ if this object responds to this method via
+    #         via method_missing
+    # @see #method_missing
+    # @see #respond_to?
+    def respond_to_missing?(symbol, include_private = false)
+      false
+    end
+
+  end
+
+end

data/lib/core_ext/string.rb

@@ -5,8 +5,16 @@
 
 unless String.method_defined?(:start_with?)
 
+  # Extends Ruby's own String class with method #start_with? for Ruby < 1.8.7
+  #
+  # @author Sebastian Staudt
+  # @since 0.3.0
   class String
 
+    # Returns true if this string starts with the given substring
+    #
+    # @param [String] start The substring to check
+    # @return [Boolean] +true+ if this String starts with the given substring
     def start_with?(start)
       !/^#{start}/.match(self).nil?
     end

data/lib/rubikon/application/base.rb

@@ -3,15 +3,17 @@
 #
 # Copyright (c) 2009-2010, Sebastian Staudt
 
-require 'singleton'
-require 'yaml'
-
 require 'rubikon/application/class_methods'
 require 'rubikon/application/dsl_methods'
 require 'rubikon/application/instance_methods'
 
 module Rubikon
 
+  # The Application module contains all basic functionality of a Rubikon
+  # application
+  #
+  # @author Sebastian Staudt
+  # @since 0.2.0
   module Application
 
     # The main class of Rubikon. Let your own application class inherit from
@@ -21,13 +23,10 @@ module Rubikon
     # @since 0.2.0
     class Base
 
-      class << self
-        include Rubikon::Application::ClassMethods
-      end
+      extend ClassMethods
 
-      include Rubikon::Application::DSLMethods
-      include Rubikon::Application::InstanceMethods
-      include Singleton
+      include DSLMethods
+      include InstanceMethods
 
     end
 

data/lib/rubikon/application/class_methods.rb

@@ -3,6 +3,8 @@
 #
 # Copyright (c) 2009-2010, Sebastian Staudt
 
+require 'singleton'
+
 module Rubikon
 
   module Application
@@ -30,8 +32,8 @@ module Rubikon
       # @param [Class] subclass The subclass inheriting from Application::Base.
       #        This is the user's application.
       def inherited(subclass)
-        super
-        Singleton.__init__(subclass)
+        subclass.class_eval { include Singleton }
+        subclass.send(:base_file=, File.expand_path(caller.first.split(':').first))
         at_exit { subclass.run if subclass.send(:autorun?) }
       end
 

data/lib/rubikon/application/dsl_methods.rb

@@ -16,25 +16,13 @@ module Rubikon
     # @since 0.3.0
     module DSLMethods
 
-      private
+      # @return [String] The (first) definition file of the application
+      attr_reader :base_file
 
-      # Returns the arguments for the currently executed Command
-      #
-      # @return [Array]
-      # @since 0.2.0
-      #
-      # @example
-      #  command :something do
-      #    puts arguments[0]
-      #  end
-      def args
-        unless @current_command.nil?
-          @current_command.arguments
-        else
-          @current_global_option.arguments
-        end
-      end
-      alias_method :arguments, :args
+      # @return [String] The absolute path of the application
+      attr_reader :path
+
+      private
 
       # Define a new application Command or an alias to an existing one
       #
@@ -50,7 +38,7 @@ module Rubikon
       #
       # @return [Command]
       # @since 0.2.0
-      def command(name, description = nil, &block)
+      def command(name, arg_count = nil, description = nil, &block)
         if name.is_a? Hash
           name.each do |alias_name, command_name|
             command = @commands[command_name]
@@ -62,7 +50,7 @@ module Rubikon
             end
           end
         else
-          command = Command.new(self, name, &block)
+          command = Command.new(self, name, arg_count, &block)
           command.description = description unless description.nil?
           @commands.each do |command_alias, command_name|
             if command_name == command.name
@@ -75,7 +63,7 @@ module Rubikon
 
         unless command.nil? || @parameters.empty?
           @parameters.each do |parameter|
-            command << parameter
+            command.add_param(parameter)
           end
           @parameters.clear
         end
@@ -131,7 +119,7 @@ module Rubikon
         if name.is_a? Hash
           @parameters << name
         else
-          @parameters << Flag.new(name, &block)
+          @parameters << Flag.new(self, name, &block)
         end
       end
 
@@ -144,15 +132,16 @@ module Rubikon
       # @example
       #  flag :status
       #  command :something do
-      #    print_status if given? :status
+      #    print_status if active? :status
       #  end
-      def given?(name)
+      def active?(name)
         name = name.to_sym
         parameter = @global_parameters[name]
         parameter = @current_command.parameters[name] if parameter.nil?
         return false if parameter.nil?
         parameter.active?
       end
+      alias_method :given?, :active?
 
       # Create a new flag with the given name to be used globally
       #
@@ -184,7 +173,7 @@ module Rubikon
             end
           end
         else
-          flag = Flag.new(name, &block)
+          flag = Flag.new(self, name, &block)
           @global_parameters.each do |flag_alias, flag_name|
             if flag_name == flag.name
               @global_parameters[flag_alias] = flag
@@ -225,7 +214,7 @@ module Rubikon
             end
           end
         else
-          option = Option.new(name, arg_count, &block)
+          option = Option.new(self, name, arg_count, &block)
           @global_parameters.each do |option_alias, option_name|
             if option_name == option.name
               @global_parameters[option_alias] = option
@@ -243,7 +232,7 @@ module Rubikon
       # @since 0.2.0
       #
       # @example Display a prompt "Please type something: "
-      #  action 'interactive' do
+      #  command 'interactive' do
       #    user_provided_value = input 'Please type something'
       #
       #    # Do something with the data
@@ -280,7 +269,7 @@ module Rubikon
         if name.is_a? Hash
           @parameters << name
         else
-          @parameters << Option.new(name.to_s, arg_count, &block)
+          @parameters << Option.new(self, name.to_s, arg_count, &block)
         end
       end
 
@@ -297,46 +286,44 @@ module Rubikon
         @settings[:ostream]
       end
 
-      # Returns the parameters for the currently executed command
-      #
-      # @return [Array] The parameters of the currently executed command
-      # @see Command
-      # @since 0.2.0
-      #
-      # @example
-      #  option :message, 1
-      #  command :something do
-      #    puts parameters[:message].args[0] if given? :message
-      #  end
-      def params
-        @current_command.parameters
+      # Defines a block of code used as a hook that should be executed after
+      # the command execution has finished
+      #
+      # @param [Proc] The code block to execute after the command execution has
+      #        finished
+      # @since 0.4.0
+      def post_execute(&block)
+        @hooks[:post_execute] = block
       end
-      alias_method :parameters, :params
 
-      # Output text using +IO#<<+ of the output stream
-      #
-      # @param [String] text The text to write into the output stream
-      # @since 0.2.0
-      def put(text)
-        @settings[:ostream] << text
-        @settings[:ostream].flush
+      # Defines a block of code used as a hook that should be executed after
+      # the application has been initialized
+      #
+      # @param [Proc] The code block to execute after the application has been
+      #        initialized
+      # @since 0.4.0
+      def post_init(&block)
+        @hooks[:post_init] = block
       end
 
-      # Output a character using +IO#putc+ of the output stream
-      #
-      # @param [String, Numeric] char The character to write into the output
-      #        stream
-      # @since 0.2.0
-      def putc(char)
-        @settings[:ostream].putc char
+      # Defines a block of code used as a hook that should be executed before
+      # the command has been started
+      #
+      # @param [Proc] The code block to execute before the command has been
+      #        started
+      # @since 0.4.0
+      def pre_execute(&block)
+        @hooks[:pre_execute] = block
       end
 
-      # Output a line of text using +IO#puts+ of the output stream
-      #
-      # @param [String] text The text to write into the output stream
-      # @since 0.2.0
-      def puts(text)
-        @settings[:ostream].puts text
+      # Defines a block of code used as a hook that should be executed before
+      # the application has been initialized
+      #
+      # @param [Proc] The code block to execute before the application has been
+      #        initialized
+      # @since 0.4.0
+      def pre_init(&block)
+        @hooks[:pre_init] = block
       end
 
       # Displays a progress bar while the given block is executed
@@ -373,6 +360,32 @@ module Rubikon
         end
       end
 
+      # Output text using +IO#<<+ of the output stream
+      #
+      # @param [String] text The text to write into the output stream
+      # @since 0.2.0
+      def put(text)
+        @settings[:ostream] << text
+        @settings[:ostream].flush
+      end
+
+      # Output a character using +IO#putc+ of the output stream
+      #
+      # @param [String, Numeric] char The character to write into the output
+      #        stream
+      # @since 0.2.0
+      def putc(char)
+        @settings[:ostream].putc char
+      end
+
+      # Output a line of text using +IO#puts+ of the output stream
+      #
+      # @param [String] text The text to write into the output stream
+      # @since 0.2.0
+      def puts(text)
+        @settings[:ostream].puts text
+      end
+
       # Sets an application setting
       #
       # @param [Symbol, #to_sym] setting The name of the setting to change

data/lib/rubikon/application/instance_methods.rb

@@ -3,6 +3,9 @@
 #
 # Copyright (c) 2009-2010, Sebastian Staudt
 
+require 'pathname'
+
+require 'rubikon/application/sandbox'
 require 'rubikon/command'
 require 'rubikon/exceptions'
 require 'rubikon/flag'
@@ -22,8 +25,11 @@ module Rubikon
     # @since 0.2.0
     module InstanceMethods
 
-      # @return [String] The absolute path of the application
-      attr_reader :path
+      # @return [Parameter] The parameter that's currently executed
+      attr_accessor :current_param
+
+      # @return [Application::Sandbox] The sandbox this application runs in
+      attr_reader :sandbox
 
       # Initialize with default settings
       #
@@ -32,17 +38,18 @@ module Rubikon
       #
       # @see #set
       def initialize
-        @commands              = {}
-        @current_command       = nil
-        @current_global_option = nil
-        @global_parameters     = {}
-        @initialized           = false
-        @parameters            = []
-        @path                  = File.dirname($0)
-        @settings              = {
+        @commands             = {}
+        @current_command      = nil
+        @current_global_param = nil
+        @current_param        = nil
+        @global_parameters    = {}
+        @hooks                = {}
+        @initialized          = false
+        @parameters           = []
+        @sandbox              = Sandbox.new(self)
+        @settings             = {
           :autorun         => true,
           :help_as_default => true,
-          :help_banner     => "Usage: #{$0}",
           :istream         => $stdin,
           :name            => self.class.to_s,
           :ostream         => $stdout,
@@ -61,22 +68,25 @@ module Rubikon
       #        given to the application as options
       def run(args = ARGV)
         begin
-          init unless @initialized
-
+          init
           command, parameters, args = parse_arguments(args)
 
           parameters.each do |parameter|
+            @current_global_param = parameter
             if parameter.is_a? Option
               parameter.check_args
-              @current_global_option = parameter
             end
             parameter.active!
-            @current_global_option = nil
+            @current_global_param = nil
           end
 
           @current_command = command
+          hook :pre_execute
           result = command.run(*args)
+          hook :post_execute
           @current_command = nil
+
+          reset
           result
         rescue
           raise $! if @settings[:raise_errors]
@@ -89,6 +99,22 @@ module Rubikon
 
       private
 
+      # Sets the (first) file this application has been defined in.
+      #
+      # This also sets the path of the application used to load external
+      # command code and the default banner for the help screen.
+      #
+      # @param [String] file The (first) file of the class definition
+      # @see DSLMethods#base_file
+      # @see DSLMethods#path
+      # @since 0.4.0
+      def base_file=(file)
+        @base_file = file
+        @path      = File.dirname(file)
+
+        @settings[:help_banner] ||= "Usage: #{Pathname.new(file).relative_path_from(Pathname.new(Dir.getwd))}"
+      end
+
       # Defines a global Flag for enabling debug output
       #
       # This will define a Flag <tt>--debug</tt> (with alias <tt>-d</tt>) to
@@ -108,16 +134,20 @@ module Rubikon
       # This takes any defined commands and it's corresponding options and
       # descriptions and displays them in a user-friendly manner.
       def help_command
-        command :help, 'Display this help screen' do
-          put @settings[:help_banner]
+        commands = @commands
+        global_parameters = @global_parameters
+        settings = @settings
+
+        command :help, nil, 'Display this help screen' do
+          put settings[:help_banner]
 
           help = {}
-          @commands.each_value do |command|
+          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 {|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
@@ -137,7 +167,7 @@ module Rubikon
             puts "Without command: #{default_description}\n\n"
           end
 
-          puts "Commands:"
+          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}"
@@ -163,11 +193,27 @@ module Rubikon
         @settings[:ostream] = current_ostream
       end
 
+      # Executes the hook with the secified name
+      #
+      # @param [Symbol] name The name of the hook to execute
+      # @since 0.4.0
+      def hook(name)
+        @sandbox.instance_eval &@hooks[name] unless @hooks[name].nil?
+      end
+
       # This method is called once for each application and is used to
       # initialize anything that needs to be ready before the application is
       # run, but <em>after</em> the application is setup, i.e. after the user
       # has defined the application class.
       def init
+        return if @initialized
+
+        @current_command      = nil
+        @current_param        = nil
+        @current_global_param = nil
+
+        hook :pre_init
+
         debug_flag
         help_command
         verbose_flag
@@ -177,6 +223,34 @@ module Rubikon
         end
 
         @initialized = true
+
+        hook :post_init
+      end
+
+      # This is used to determine the receiver of a method call inside the
+      # application code.
+      #
+      # This is used to have a convenient way to access e.g. paramter
+      # arguments.
+      #
+      # This will delegate a method call to the currently executed parameter
+      # if the receiving object exists and responds to the desired method.
+      # Currently executed means the application's execution is inside a
+      # parameter's code block at the moment, i.e. a call to a missing method
+      # inside a parameter's code block will trigger this behavior.
+      #
+      # @example Access a command's arguments
+      #   command :args, [:one, :two] do
+      #     puts "One: #{one}, Two: #{two}"
+      #   end
+      # @since 0.4.0
+      def method_missing(name, *args, &block)
+        receiver = @current_param || @current_global_param || @current_command
+        if receiver.nil? || !receiver.respond_to?(name)
+          super
+        else
+          receiver.send(name, *args, &block)
+        end
       end
 
       # Parses the command-line arguments given to the application by the
@@ -223,6 +297,18 @@ module Rubikon
         return command, parameters, args
       end
 
+      # Resets this application to its initial state
+      #
+      # @see Command#reset
+      # @see HasArguments#reset
+      # @see Parameter#reset
+      # @since 0.4.0
+      def reset
+        (@commands.values + @global_parameters.values).uniq.each do |param|
+          param.reset
+        end
+      end
+
       # Defines a global Flag for enabling verbose output
       #
       # This will define a Flag <tt>--verbose</tt> and <tt>-v</tt> to enable