module Rubikon::HasArguments

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

Constants

ARGUMENT_MATCHERS

Provides a number of predefined regular expressions to check arguments against

@see initialize @since 0.6.0

Public Class Methods

new(app, name, *options, &block) click to toggle source

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 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. 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
Calls superclass method Rubikon::Parameter::new
# File lib/rubikon/has_arguments.rb, line 68
def initialize(app, name, *options, &block)
  super(app, name, &block)

  @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 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
  end
end

Public Instance Methods

[](arg) click to toggle source

Access the arguments of this parameter using a numeric or symbolic index

@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

# File lib/rubikon/has_arguments.rb, line 144
def [](arg)
  @args[arg]
end
args() click to toggle source

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

# File lib/rubikon/has_arguments.rb, line 155
def args
  @arg_names.empty? ? @args.values : @args
end
Also aliased as: arguments
arguments()
Alias for: args

Protected Instance Methods

<<(arg) click to toggle source

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

# File lib/rubikon/has_arguments.rb, line 173
def <<(arg)
  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
end
active!() click to toggle source

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!

Calls superclass method Rubikon::Parameter#active!
# File lib/rubikon/has_arguments.rb, line 195
def active!
  check_args
  super
end
arg_count() click to toggle source

Return the allowed range of argument counts this parameter takes

@return [Range] The allowed range of argument counts this parameter takes

# File lib/rubikon/has_arguments.rb, line 203
def arg_count
  @min_arg_count..@max_arg_count
end
args_full?() click to toggle source

Checks whether this parameter has all required arguments supplied

@return true if all required parameter arguments have been supplied @since 0.3.0

# File lib/rubikon/has_arguments.rb, line 211
def args_full?
  @args.size >= @min_arg_count
end
check_args() click to toggle source

Checks the arguments for this parameter

@raise [MissingArgumentError] if there are not enough arguments for

this parameter

@since 0.3.0

# File lib/rubikon/has_arguments.rb, line 220
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
method_missing(name, *args, &block) click to toggle source

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
Calls superclass method
# File lib/rubikon/has_arguments.rb, line 247
def method_missing(name, *args, &block)
  if args.empty? && !block_given? && @arg_names.include?(name)
    @args[name]
  else
    super
  end
end
more_args?() click to toggle source

Checks whether this parameter can take more arguments

@return true if this parameter can take more arguments @since 0.3.0

# File lib/rubikon/has_arguments.rb, line 259
def more_args?
  @max_arg_count == -1 || @args.size < @max_arg_count
end
reset() click to toggle source

Resets this parameter to its initial state

@see Parameter#reset @since 0.4.0

Calls superclass method Rubikon::Parameter#reset
# File lib/rubikon/has_arguments.rb, line 267
def reset
  super
  @args.clear
end
respond_to_missing?(name, include_private = false) click to toggle source

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

# File lib/rubikon/has_arguments.rb, line 279
def respond_to_missing?(name, include_private = false)
  @arg_names.include? name
end