rubikon 0.3.0 → 0.4.0

data/lib/rubikon/application/sandbox.rb

@@ -0,0 +1,70 @@
+# 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
+
+module Rubikon
+
+  module Application
+
+    # The application sandbox is a wrapper used to secure internal Rubikon
+    # logic from access by user generated application code.
+    #
+    # This is mostly to prevent accidental execution or change of Rubikon's
+    # internal code. But it also helps to prevent possible security problems
+    # depending on the code used inside the application logic.
+    #
+    # @see Application::InstanceMethods
+    # @since 0.4.0
+    class Sandbox
+
+      # Create a new application sandbox
+      #
+      # @param [Application::Base] app The application to be sandboxed
+      def initialize(app)
+        raise ArgumentError unless app.is_a? Application::Base
+        @__app__ = app
+      end
+
+      # Method calls on the sandbox wrapper will be relayed to the singleton
+      # instance. Methods defined in InstanceMethods are protected and will
+      # raise a NoMethodError.
+      #
+      # @param (see ClassMethods#method_missing)
+      # @raise [NoMethodError] if a method is called that is defined inside
+      #        InstanceMethods and should therefore be protected
+      # @see InstanceMethods
+      def method_missing(name, *args, &block)
+        if InstanceMethods.method_defined?(name) ||
+           InstanceMethods.private_method_defined?(name)
+          raise NoMethodError.new("Method `#{name}' is protected by the application sandbox", name)
+        end
+        @__app__.send(name, *args, &block)
+      end
+
+      # Relay putc to the instance method
+      #
+      # This is used to hide <tt>Kernel#putc</tt> so that the application's
+      # output IO object is used for printing characters
+      #
+      # @param [String, Numeric] char The character to write into the output
+      #        stream
+      def putc(text)
+        @__app__.send(:putc, text)
+      end
+
+      # Relay puts to the instance method
+      #
+      # This is used to hide <tt>Kernel#puts</tt> so that the application's
+      # output IO object is used for printing text
+      #
+      # @param [String] text The text to write into the output stream
+      def puts(text)
+        @__app__.send(:puts, text)
+      end
+
+    end
+
+  end
+
+end

data/lib/rubikon/command.rb

@@ -5,6 +5,7 @@
 
 require 'rubikon/application/base'
 require 'rubikon/exceptions'
+require 'rubikon/has_arguments'
 require 'rubikon/parameter'
 
 module Rubikon
@@ -16,31 +17,33 @@ module Rubikon
   # @since 0.3.0
   class Command
 
-    include Parameter
+    include HasArguments
 
+    # @return [String] The description of this command
     attr_accessor :description
-    attr_reader   :args, :params
-    alias_method  :arguments, :args
+
+    # @return [Array<Parameter>] The parameters of this command
+    attr_reader   :params
     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
+    # @param [Application::Base] app The application this command belongs to
+    # @param [Symbol, #to_sym] name The name of this command, used in application
     #        arguments
+    # @param [Range, Array, Numeric] arg_count The number of arguments this
+    #        command takes.
     # @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)
+    # @see HasArguments#arg_count=
+    def initialize(app, name, arg_count = nil, &block)
+      super
 
-      @app    = app
       @params = {}
 
       if block_given?
@@ -53,14 +56,14 @@ module Rubikon
       end
     end
 
-    # Add a new Parameter for this command
+    # Add a new parameter for this command
     #
-    # @param [Parameter, Hash] parameter The parameter to add to this 
+    # @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)
+    def add_param(parameter)
       if parameter.is_a? Hash
         parameter.each do |alias_name, name|
           alias_name = alias_name.to_sym
@@ -78,12 +81,33 @@ module Rubikon
         @params.each do |name, param|
           if param == parameter.name
             parameter.aliases << name
+            @params[name] = parameter
           end
         end
         @params[parameter.name] = parameter
       end
     end
 
+    # If a parameter with the specified method name exists, a call to that
+    # method will return the value of the parameter.
+    #
+    # @param (see ClassMethods#method_missing)
+    # @see DSLMethods#params
+    #
+    # @example
+    #   option :user, [:who]
+    #   command :hello, [:mood] do
+    #     puts "Hello #{user.who}"
+    #     puts "I feel #{mood}"
+    #   end
+    def method_missing(name, *args, &block)
+      if args.empty? && !block_given? && @params.key?(name)
+        @params[name]
+      else
+        super
+      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.
@@ -96,7 +120,6 @@ module Rubikon
     # @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]
@@ -104,21 +127,41 @@ module Rubikon
           raise UnknownParameterError.new(arg) if parameter.nil?
         end
 
-        unless parameter.nil? || parameter.active?
-          parameter.active!
+        unless parameter.nil?
+          @app.current_param.active! unless @app.current_param.nil?
+          @app.current_param = parameter
           next
         end
 
-        if parameter.nil? || !parameter.more_args?
-          @args << arg
+        if @app.current_param.nil? || !@app.current_param.more_args?
+          self << arg
         else
-          parameter << arg
+          @app.current_param << arg
         end
       end
 
-      @params.values.each do |param|
-        param.check_args if param.is_a?(Option) && param.active?
-      end
+      @app.current_param.active! unless @app.current_param.nil?
+      @app.current_param = nil
+    end
+
+    # Resets this command to its initial state
+    #
+    # @see HasArguments#reset
+    # @since 0.4.0
+    def reset
+      super
+      @params.values.uniq.each { |param| param.reset if param.is_a? Parameter }
+    end
+
+    # Checks whether a parameter with the given name exists for this command
+    #
+    # This is used to determine if a method call would successfully return the
+    # value of a parameter.
+    #
+    # @return +true+ if named parameter with the specified name exists
+    # @see #method_missing
+    def respond_to_missing?(name, include_private = false)
+      @params.key?(name) || super
     end
 
     # Run this command's code block
@@ -127,7 +170,8 @@ module Rubikon
     #        command
     def run(*args)
       parse_arguments(args)
-      @app.instance_eval(&@block)
+      check_args
+      @app.sandbox.instance_eval(&@block)
     end
 
   end

data/lib/rubikon/flag.rb

@@ -18,14 +18,6 @@ module Rubikon
 
     include Parameter
 
-    # Creates a new flag with the given name and an optional code block
-    #
-    # @param name (see Parameter#initialize)
-    # @param block (see Parameter#initialize)
-    def initialize(name, &block)
-      super(name, 0, &block)
-    end
-
     # Adds an argument to this flag
     #
     # @param arg (see Parameter#<<)

data/lib/rubikon/has_arguments.rb

@@ -0,0 +1,182 @@
+# 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/parameter'
+
+module Rubikon
+
+  # This module is included in all classes used for parsing command-line
+  # arguments
+  #
+  # @author Sebastian Staudt
+  # @see Application::InstanceMethods
+  # @see Command
+  # @see Option
+  # @since 0.4.0
+  module HasArguments
+
+    include Parameter
+
+    # @return [Array<String>] The arguments given to this parameter
+    attr_reader :args
+    alias_method :arguments, :args
+
+    # Creates a new parameter with arguments with the given name and an
+    # optional code block
+    #
+    # @param [Application::Base] app The application this parameter belongs to
+    # @param [Symbol, #to_sym] name The name of the option
+    # @param [Fixnum, Range, Array] arg_count A range or array allows any
+    #        number of arguments inside the limits between the first and the
+    #        last element of the range or array (-1 stands for an arbitrary
+    #        number of arguments). A positive number indicates the exact amount
+    #        of required arguments while a negative argument count indicates
+    #        the amount of required arguments, but allows additional, optional
+    #        arguments. A argument count of 0 means there are no required
+    #        arguments, but it allows optional arguments.
+    #        Finally an array of symbols enables named arguments where the
+    #        argument count is the size of the array and each argument is named
+    #        after the corresponding symbol.
+    # @param [Proc] block An optional code block to be executed if this
+    #        option is used
+    def initialize(app, name, arg_count = 0, &block)
+      super(app, name, &block)
+
+      @args      = []
+      @arg_names = nil
+      if arg_count.is_a? Fixnum
+        if arg_count > 0
+          @min_arg_count = arg_count
+          @max_arg_count = arg_count
+        elsif arg_count <= 0
+          @min_arg_count = -arg_count
+          @max_arg_count = -1
+        end
+      elsif arg_count.is_a?(Array) && arg_count.all? { |a| a.is_a? Symbol }
+        @max_arg_count = @min_arg_count = arg_count.size
+        @arg_names = arg_count
+      elsif arg_count.is_a?(Range) || arg_count.is_a?(Array)
+        @min_arg_count = arg_count.first
+        @max_arg_count = arg_count.last
+      else
+        @min_arg_count = 0
+        @max_arg_count = 0
+      end
+    end
+
+    # Access the arguments of this parameter using a numeric or symbolic index
+    #
+    # @param [Numeric, Symbol] The index of the argument to return. Numeric
+    #        indices can be used always while symbolic arguments are only
+    #        available for named arguments.
+    # @return The argument with the specified index
+    # @since 0.4.0
+    def [](arg)
+      arg = @arg_names.index(arg) if arg.is_a? Symbol
+      @args[arg]
+    end
+
+    # Adds an argument to this parameter. Arguments can be accessed inside the
+    # application code using the args method.
+    #
+    # @param [String] arg The argument to add to the supplied arguments of this
+    #        parameter
+    # @raise [ExtraArgumentError] if the parameter has all required arguments
+    #        supplied and does not take optional arguments
+    # @return [Array] The supplied arguments of this parameter
+    # @see #[]
+    # @see #args
+    # @since 0.3.0
+    def <<(arg)
+      if args_full? && @args.size == @max_arg_count
+        raise ExtraArgumentError.new(@name)
+      end
+      @args << arg
+    end
+
+    # Marks this parameter as active when it has been supplied by the user on
+    # the command-line. This also checks the arguments given to this parameter.
+    #
+    # @see #check_args
+    # @see Paramter#active!
+    def active!
+      check_args
+      super
+    end
+
+    # Return the allowed range of argument counts this parameter takes
+    #
+    # @return [Range] The allowed range of argument counts this parameter takes
+    def arg_count
+      @min_arg_count..@max_arg_count
+    end
+
+    # Checks whether this parameter has all required arguments supplied
+    #
+    # @return +true+ if all required parameter arguments have been supplied
+    # @since 0.3.0
+    def args_full?
+      @args.size >= @min_arg_count
+    end
+
+    # Checks the arguments for this parameter
+    #
+    # @raise [MissingArgumentError] if there are not enough arguments for
+    #        this parameter
+    # @since 0.3.0
+    def check_args
+      raise MissingArgumentError.new(@name) unless args_full?
+    end
+
+    # If a named argument with the specified method name exists, a call to that
+    # method will return the value of the argument.
+    #
+    # @param (see ClassMethods#method_missing)
+    # @see #args
+    # @see #[]
+    #
+    # @example
+    #   option :user, [:name] do
+    #     @user = name
+    #   end
+    def method_missing(name, *args, &block)
+      if args.empty? && !block_given? && !@arg_names.nil? && @arg_names.include?(name)
+        @args[@arg_names.index(name)]
+      else
+        super
+      end
+    end
+
+    # Checks whether this parameter can take more arguments
+    #
+    # @return +true+ if this parameter can take more arguments
+    # @since 0.3.0
+    def more_args?
+      @max_arg_count == -1 || @args.size < @max_arg_count
+    end
+
+    # Resets this parameter to its initial state
+    #
+    # @see Parameter#reset
+    # @since 0.4.0
+    def reset
+      super
+      @args.clear
+    end
+
+    # Checks whether an argument with the given name exists for this parameter
+    #
+    # This is used to determine if a method call would successfully return the
+    # value of an argument.
+    #
+    # @return +true+ if named argument with the specified name exists
+    # @see #method_missing
+    def respond_to_missing?(name, include_private = false)
+      !@arg_names.nil? && @arg_names.include?(name)
+    end
+
+  end
+
+end

data/lib/rubikon/option.rb

@@ -3,7 +3,7 @@
 #
 # Copyright (c) 2010, Sebastian Staudt
 
-require 'rubikon/parameter'
+require 'rubikon/has_arguments'
 
 module Rubikon
 
@@ -16,14 +16,7 @@ module Rubikon
   # @since 0.3.0
   class Option
 
-    # @return [Numeric] The number of arguments this parameter takes
-    attr_reader :arg_count
-
-    # @return [Array<String>] The arguments given to this parameter
-    attr_reader :args
-    alias_method :arguments, :args
-
-    include Parameter
+    include HasArguments
 
   end
 

data/lib/rubikon/parameter.rb

@@ -7,9 +7,10 @@ module Rubikon
 
   # A parameter is any command-line argument given to the application that is
   # not prefixed with one or two dashes. Once a parameter is supplied by the
-  # user, it is relayed to the Command it belongs to.
+  # user, it is relayed to the command it belongs to.
   #
   # @author Sebastian Staudt
+  # @see Command
   # @since 0.3.0
   module Parameter
 
@@ -21,38 +22,18 @@ module Rubikon
 
     # Creates a new parameter with the given name
     #
+    # @param [Application::Base] app The application this parameter belongs to
     # @param [Symbol, #to_sym] name The name of the parameter
-    # @param [Numeric] arg_count The number of arguments this parameter takes
-    #        if any
     # @param [Proc] block An optional code block to be executed if this
     #        parameter is used
-    #
-    # A positive argument count indicates the exact amount of required
-    # arguments, while a negative argument count indicates the amount of
-    # required arguments, but allows additional, optional arguments. A argument
-    # count of 0 means there are no required arguments, but it allows optional
-    # arguments. If you need a parameter that does not allow arguments at all
-    # you should use a flag instead.
-    def initialize(name, arg_count = 0, &block)
-      @active    = false
-      @aliases   = []
-      @arg_count = arg_count
-      @args      = []
-      @block     = block
-      @name      = name.to_sym
-    end
+    def initialize(app, name, &block)
+      raise ArgumentError unless app.is_a? Application::Base
 
-    # Adds an argument to this parameter. Parameter arguments can be accessed
-    # inside the Application code using the parameter's args method.
-    #
-    # @param [String] arg The argument to add to the supplied arguments of this
-    #        parameter
-    # @raise [ExtraArgumentError] if the parameter has all required arguments
-    #        supplied and does not take optional arguments
-    # @return [Array] The supplied arguments of this parameter
-    def <<(arg)
-      raise ExtraArgumentError.new(@name) if args_full? && @arg_count > 0
-      @args << arg
+      @active  = false
+      @aliases = []
+      @app     = app
+      @block   = block
+      @name    = name.to_sym
     end
 
     # Marks this parameter as active when it has been supplied by the user on
@@ -60,7 +41,7 @@ module Rubikon
     # exists
     def active!
       @active = true
-      @block.call unless @block.nil?
+      @app.sandbox.instance_eval(&@block) unless @block.nil?
     end
 
     # Returns whether this parameter has is active, i.e. it has been supplied
@@ -70,30 +51,13 @@ module Rubikon
     def active?
       @active
     end
+    alias_method :given?, :active?
 
-    # Checks whether this parameter has all required arguments supplied
-    #
-    # @return +true+ if all required parameter arguments have been supplied
-    def args_full?
-      arg_count = @arg_count
-      arg_count = -arg_count if arg_count < 0
-
-      arg_count == 0 || @args.size >= arg_count
-    end
-
-    # Checks the arguments for this parameter
-    #
-    # @raise [MissingArgumentError] if there are not enough arguments for
-    #                               this parameter
-    def check_args
-      raise MissingArgumentError.new(@name) unless args_full?
-    end
-
-    # Checks whether this parameter can take more arguments
+    # Resets this parameter to its initial state
     #
-    # @return +true+ if this parameter can take more arguments
-    def more_args?
-      arg_count <= 0 || @args.size < arg_count
+    # @since 0.4.0
+    def reset
+      @active = false
     end
 
   end

data/lib/rubikon/progress_bar.rb

@@ -72,7 +72,7 @@ module Rubikon
       if add_progress > 0
         @ostream << @progress_char * add_progress
         @ostream.flush
-        @ostream.puts '' if @progress == @size
+        @ostream.putc 10 if @progress == @size
       end
 
       self

data/lib/rubikon.rb

@@ -6,15 +6,24 @@
 libdir = File.dirname(__FILE__)
 $:.unshift(libdir) unless $:.include?(libdir)
 
+require 'core_ext/object'
 require 'core_ext/string'
 require 'rubikon/application/base'
 
-# A namespace module for all Rubikon related code
+# Rubikon is a simple to use, yet powerful Ruby framework for building
+# console-based applications. Rubikon aims to provide an easy to write and easy
+# to read domain-specific language (DSL) to speed up development of
+# command-line applications. With Rubikon it's a breeze to implement
+# applications with only few options as well as more complex programs like
+# RubyGems, Homebrew or even Git.
+#
+# This is the namespace module for all Rubikon related code.
 #
 # @author Sebastian Staudt
 # @since 0.1.0
 module Rubikon
 
-  VERSION = '0.3.0'
+  # This is the current version of the Rubikon gem
+  VERSION = '0.4.0'
 
 end

data/samples/helloworld/hello_world.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+#
+# 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
+
+if ENV['RUBIKON_DEV']
+  require File.join(File.expand_path(File.dirname(__FILE__)), '..', '..', 'lib', 'rubikon')
+else
+  require 'rubygems'
+  require 'rubikon'
+end
+
+# A relatively simple Hello World application using Rubikon
+class HelloWorld < Rubikon::Application::Base
+
+  # Greet the whole world per default
+  flag :more
+  option :name, [:who]
+  option :names, -1
+  default 'Simple hello world' do
+    debug 'Starting to greet the world...'
+    if given? :name
+      greet parameters[:name].who
+    elsif given? :names
+      names.args.each do |name|
+        greet name
+      end
+    else
+      greet 'World'
+    end
+    puts 'Nice to see you.' if given? :more
+  end
+
+  # Interactive mode
+  #
+  # Ask the user for his name and greet him
+  command :interactive, 'Greet interactively' do
+    name = input 'Please enter your name'
+    greet name
+  end
+
+  # Show a progress bar while iterating through a loop
+  command :progress, 'Display a progress bar' do
+    put 'Watch my progress while I greet the world: '
+    x = 1000000
+    progress_bar(:char => '+', :maximum => x, :size => 30) do |progress|
+      x.times do
+        progress.+
+      end
+    end
+  end
+
+  # Sleep for 5 seconds while displaying a throbber
+  command :throbber, 'Display a throbber' do
+    put 'Greeting the whole world takes some time... '
+    throbber do
+      sleep 5
+    end
+    puts 'done.'
+  end
+
+  # A standard Ruby class method for greeting
+  def greet(someone)
+    puts "Hello #{someone}!"
+  end
+
+end