rubikon 0.5.3 → 0.6.0

data/lib/rubikon/command.rb

@@ -1,10 +1,10 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'rubikon/application/base'
-require 'rubikon/exceptions'
+require 'rubikon/errors'
 require 'rubikon/has_arguments'
 require 'rubikon/parameter'
 
@@ -34,16 +34,14 @@ module Rubikon
     # @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 options (see HasArguments#initialize)
     # @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
-    # @see HasArguments#arg_count=
-    def initialize(app, name, arg_count = nil, &block)
+    def initialize(app, name, *options, &block)
       super
 
       @params = {}
@@ -58,8 +56,81 @@ 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)}"
+          help << "      #{param.description}" unless param.description.nil?
+        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)} ..."
+          help << "  #{param.description}" unless param.description.nil?
+          help << "\n"
+        end
+      end
+
+      help
+    end
+
     private
 
+    # Returns all parameters of this command that are active, i.e. that have
+    # been supplied on the command-line
+    #
+    # @return [Array<Parameter>] All currently active parameters of this
+    #         command
+    # @since 0.6.0
+    def active_params
+      @params.values.select { |param| param.active? }
+    end
+
     # Add a new parameter for this command
     #
     # @param [Parameter, Hash] parameter The parameter to add to this
@@ -96,7 +167,6 @@ module Rubikon
     # method will return the value of the parameter.
     #
     # @param (see ClassMethods#method_missing)
-    # @see DSLMethods#params
     #
     # @example
     #   option :user, [:who]
@@ -105,52 +175,17 @@ module Rubikon
     #     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.
-    #
-    # @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)
-      current_param = Application::InstanceMethods.
-        instance_method(:current_param).bind(@app)
-      set_current_param = Application::InstanceMethods.
-        instance_method(:current_param=).bind(@app)
-
-      @args = []
-      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?
-          current_param.call.send(:active!) unless current_param.call.nil?
-          set_current_param.call(parameter)
-          next
-        end
-
-        if current_param.call.nil? || !current_param.call.send(:more_args?)
-          self << arg
+      if args.empty? && !block_given?
+        if @params.key?(name)
+          return @params[name]
         else
-          current_param.call.send(:<<, arg)
+          active_params.each do |param|
+            return param.send(name) if param.respond_to_missing?(name)
+          end
         end
       end
 
-      current_param.call.send(:active!) unless current_param.call.nil?
-      set_current_param.call(nil)
+      super
     end
 
     # Resets this command to its initial state
@@ -172,15 +207,13 @@ module Rubikon
     # @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
+      @params.key?(name) ||
+      active_params.any? { |param| param.respond_to_missing?(name) } ||
+      super
     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)
+    def run
       check_args
       Application::InstanceMethods.instance_method(:sandbox).bind(@app).call.
         instance_eval(&@block)

data/lib/rubikon/config/auto_provider.rb

@@ -1,7 +1,7 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 module Rubikon
 
@@ -19,14 +19,39 @@ module Rubikon
       #
       # @param [String] file The path of the config file to load
       # @return [Hash] The configuration values loaded from the file
+      # @see IniProvider
       # @see YamlProvider
       def self.load_config(file)
+        provider_for(file).load_config(file)
+      end
+
+      # Saves a configuration Hash with the corresponding provider detected
+      # from the file extension
+      #
+      # @param [Hash] config The configuration to write
+      # @param [String] file The path of the file to write
+      # @see IniProvider
+      # @see YamlProvider
+      # @since 0.6.0
+      def self.save_config(config, file)
+        provider_for(file).save_config(config, file)
+      end
+
+      private
+
+      # Returns the correct provider for the given file
+      #
+      # The file format is guessed from the file extension.
+      #
+      # @return Object A provider for the given file format
+      # @since 0.6.0
+      def provider_for(file)
         ext = File.extname(file)
         case ext
           when '.ini'
-            IniProvider.load_config file
+            IniProvider
           when '.yaml', '.yml'
-            YamlProvider.load_config file
+            YamlProvider
           else
             raise UnsupportedConfigFormatError.new(ext)
         end

data/lib/rubikon/config/factory.rb

@@ -1,7 +1,7 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'rubikon/config/auto_provider'
 require 'rubikon/config/ini_provider'
@@ -45,19 +45,32 @@ module Rubikon
       #        configuration data from the files found
       def initialize(name, search_paths, provider = :yaml)
         provider = :auto unless PROVIDERS.include?(provider)
-        provider = Config.const_get("#{provider.to_s.capitalize}Provider")
+        @provider = Config.const_get("#{provider.to_s.capitalize}Provider")
       
         @files  = []
         @config = {}
         search_paths.each do |path|
           config_file = File.join path, name
           if File.exists? config_file
-            @config.merge! provider.load_config(config_file)
+            @config.merge! @provider.load_config(config_file)
             @files << config_file
           end
         end
       end
 
+      # Save the given configuration into the specified file
+      #
+      # @param [Hash] The configuration to save
+      # @param [String] The file path where the configuration should be saved
+      # @since 0.6.0
+      def save_config(config, file)
+        unless config.is_a? Hash
+          raise ArgumentError.new('Configuration has to be a Hash')
+        end
+
+        @provider.save_config config, file
+      end
+
     end
 
   end

data/lib/rubikon/config/ini_provider.rb

@@ -1,7 +1,7 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 module Rubikon
 
@@ -53,6 +53,34 @@ module Rubikon
         config
       end
 
+      # Saves a configuration Hash into a INI file
+      #
+      # @param [Hash] config The configuration to write
+      # @param [String] file The path of the file to write
+      # @since 0.6.0
+      def self.save_config(config, file)
+        unless config.is_a? Hash
+          raise ArgumentError.new('Configuration has to be a Hash')
+        end
+
+        file = File.new file, 'w'
+
+        config.each do |key, value|
+          if value.is_a? Hash
+            file << "\n" if file.pos > 0
+            file << "[#{key.to_s}]\n"
+
+            value.each do |k, v|
+              file << "  #{k.to_s} = #{v.to_s unless v.nil?}\n"
+            end
+          else
+            file << "#{key.to_s} = #{value.to_s unless value.nil?}\n"
+          end
+        end
+
+        file.close
+      end
+
     end
 
   end

data/lib/rubikon/config/yaml_provider.rb

@@ -1,7 +1,7 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'yaml'
 
@@ -23,6 +23,21 @@ module Rubikon
         YAML.load_file file
       end
 
+      # Saves a configuration Hash into a YAML formatted file
+      #
+      # @param [Hash] config The configuration to write
+      # @param [String] file The path of the file to write
+      # @since 0.6.0
+      def self.save_config(config, file)
+        unless config.is_a? Hash
+          raise ArgumentError.new('Configuration has to be a Hash')
+        end
+
+        file = File.new file, 'w'
+        YAML.dump config, file
+        file.close
+      end
+
     end
 
   end

data/lib/rubikon/{exceptions.rb → errors.rb}

@@ -1,7 +1,7 @@
 # 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
 
 module Rubikon
 
@@ -62,8 +62,32 @@ module Rubikon
   # @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
+
+  # Raised if an argument is passed, that does not match a validation rule
+  #
+  # @author Sebastian Staudt
+  # @see HasArguments#check_args
+  # @since 0.6.0
+  class UnexpectedArgumentError < ArgumentError
+
+    # Creates a new error and stores the given argument value
+    #
+    # @param [Symbol] arg The given argument value
+    def initialize(arg)
+      super "Unexpected argument: #{arg}"
     end
 
   end

data/lib/rubikon/has_arguments.rb

@@ -1,7 +1,7 @@
 # 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
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'rubikon/parameter'
 
@@ -19,47 +19,114 @@ module Rubikon
 
     include Parameter
 
-    # @return [Array<String>] The arguments given to this parameter
-    attr_reader :args
-    alias_method :arguments, :args
+    # Provides a number of predefined regular expressions to check arguments
+    # against
+    #
+    # @see #initialize
+    # @since 0.6.0
+    ARGUMENT_MATCHERS = {
+      # Allow only alphanumeric characters
+      :alnum   => /[[:alnum:]]+/,
+      # Allow only floating point numbers as arguments
+      :float   => /-?[0-9]+(?:\.[0-9]+)?/,
+      # Allow only alphabetic characters
+      :letters => /[a-zA-Z]+/,
+      # Allow only numeric arguments
+      :numeric => /-?[0-9]+/
+    }
 
     # 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
+    # @param [Symbol, #to_sym] name The name of the parameter
+    # @param [Array] options A range allows any number of arguments inside the
+    #        limits 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.
+    #        arguments, but it allows optional arguments. 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. Finally a hash may be used to specify
+    #        options for named arguments. The keys of the hash will be the
+    #        names of the arguments and the values are options for this
+    #        argument. You may specify multiple options as an array. Possible
+    #        options are:
+    #        - +:optional+ makes the argument optional
+    #        - +:remainder+ makes the argument take all remaining arguments as
+    #          an array
+    #        - One or more strings will cause the argument to be checked to be
+    #          equal to one of the strings
+    #        - One or more regular expressions will cause the argument to be
+    #          checked to match one of the expressions
+    #        - Other symbols may reference to a predefined regular expression
+    #          from {ARGUMENT_MATCHERS}
     # @param [Proc] block An optional code block to be executed if this
     #        option is used
-    def initialize(app, name, arg_count = 0, &block)
+    def initialize(app, name, *options, &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
+      @arg_names  = []
+      @arg_values = {}
+      @args       = {}
+
+      @description = options.shift if options.first.is_a? String
+
+      if options.size == 1 && (options.first.nil? ||
+         options.first.is_a?(Fixnum) || options.first.is_a?(Range))
+        options = options.first
+      end
+
+      if options.is_a? Fixnum
+        if options > 0
+          @min_arg_count = options
+          @max_arg_count = options
+        elsif options <= 0
+          @min_arg_count = -options
           @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
+      elsif options.is_a? Range
+        @min_arg_count = options.first
+        @max_arg_count = options.last
+      elsif options.is_a? Array
+        @arg_names = []
+        @max_arg_count = 0
+        @min_arg_count = 0
+        options.each do |arg|
+          if arg.is_a? Hash
+            arg = arg.map do |arg_name, opt|
+              [arg_name, opt.is_a?(Array) ? opt : [opt]]
+            end
+            arg = arg.sort_by do |arg_name, opt|
+              opt.include?(:optional) ? 1 : 0
+            end
+            arg.each do |arg_name, opt|
+              matchers = opt.reject { |o| [:optional, :remainder].include? o }
+              opt -= matchers
+              @arg_names << arg_name.to_sym
+              if !matchers.empty?
+                matchers.map! do |m|
+                  ARGUMENT_MATCHERS[m] || (m.is_a?(Regexp) ? m : m.to_s)
+                end
+                @arg_values[arg_name] = /^#{Regexp.union *matchers}$/
+              end
+              unless opt.include? :optional
+                @min_arg_count += 1
+              end
+              if opt.include? :remainder
+                @max_arg_count = -1
+                break
+              end
+              @max_arg_count += 1
+            end
+          else
+            @arg_names << arg.to_sym
+            @min_arg_count += 1
+            @max_arg_count += 1
+          end
+        end
       else
         @min_arg_count = 0
         @max_arg_count = 0
@@ -68,17 +135,28 @@ module Rubikon
 
     # 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.
+    # @param [Numeric, Symbol] arg The name or 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
     # @see #args
     # @since 0.4.0
     def [](arg)
-      arg = @arg_names.index(arg) if arg.is_a? Symbol
       @args[arg]
     end
 
+    # Returns the arguments given to this parameter. They are given as a Hash
+    # when there are named arguments or as an Array when there are no named
+    # arguments
+    #
+    # @return [Array<String>, Hash<Symbol, String>] The arguments given to this
+    #         parameter
+    # @since 0.6.0
+    def args
+      @arg_names.empty? ? @args.values : @args
+    end
+    alias_method :arguments, :args
+
     protected
 
     # Adds an argument to this parameter. Arguments can be accessed inside the
@@ -93,10 +171,20 @@ module Rubikon
     # @see #args
     # @since 0.3.0
     def <<(arg)
-      if args_full? && @args.size == @max_arg_count
-        raise ExtraArgumentError.new(@name)
+      raise ExtraArgumentError.new(@name) unless more_args?
+
+      if @arg_names.size > @args.size
+        name = @arg_names[@args.size]
+        if @max_arg_count == -1 && @arg_names.size == @args.size + 1
+          @args[name] = [arg]
+        else
+          @args[name] = arg
+        end
+      elsif !@arg_names.empty? && @max_arg_count == -1
+        @args[@arg_names.last] << arg
+      else
+        @args[@args.size] = arg
       end
-      @args << arg
     end
 
     # Marks this parameter as active when it has been supplied by the user on
@@ -131,6 +219,18 @@ module Rubikon
     # @since 0.3.0
     def check_args
       raise MissingArgumentError.new(@name) unless args_full?
+      unless @arg_values.empty?
+        @args.each do |name, arg|
+          if @arg_values.key? name
+            arg = [arg] unless arg.is_a? Array
+            arg.each do |a|
+              unless a =~ @arg_values[name]
+                raise UnexpectedArgumentError.new(a)
+              end
+            end
+          end
+        end
+      end
     end
 
     # If a named argument with the specified method name exists, a call to that
@@ -145,8 +245,8 @@ module Rubikon
     #     @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)]
+      if args.empty? && !block_given? && @arg_names.include?(name)
+        @args[name]
       else
         super
       end
@@ -177,7 +277,7 @@ module Rubikon
     # @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)
+      @arg_names.include? name
     end
 
   end