module Parameters

Constants

VERSION

The version of parameters

Public Class Methods

included(base) click to toggle source
# File lib/parameters/parameters.rb, line 10
def self.included(base)
  base.extend ClassMethods

  if base.kind_of?(Module)
    # add Module specific methods
    base.extend Parameters::ModuleMethods
  end
end
new(*args,&block) click to toggle source

Initializes the parameters using initialize_params. If a ‘Hash` is passed in as the first argument, it will be used to set the values of parameters described within the `Hash`.

@api public

# File lib/parameters/parameters.rb, line 45
def initialize(*args,&block)
  initialize_params(args.first)
end

Public Instance Methods

class_params() click to toggle source

@return [Hash]

The parameteres of the class and it's ancestors.

@api semipublic

# File lib/parameters/parameters.rb, line 117
def class_params
  self.class.params
end
describe_param(name) click to toggle source

Returns the description of the parameter with a specific name.

@param [Symbol, String] name

The name of the instance parameter to search for.

@return [String]

The description of the instance parameter.

@raise [ParamNotFound]

Could not find the instance parameter with the specified name.

@example

obj.describe_param('rhost') # => "remote host"

@api semipublic

# File lib/parameters/parameters.rb, line 262
def describe_param(name)
  get_param(name).description
end
each_param(&block) click to toggle source

Iterates over each instance parameter in the object.

@yield [param]

The block that will be passed each instance parameter.

@api semipublic

# File lib/parameters/parameters.rb, line 167
def each_param(&block)
  self.params.each_value(&block)
end
get_param(name) click to toggle source

Searches for the instance parameter with a specific name.

@param [Symbol, String] name

The name of the instance parameter to search for.

@return [InstanceParam]

The instance parameter with the specified name.

@raise [ParamNotFound]

Could not find the instance parameter with the specified name.

@example

obj.get_param('var') # => InstanceParam

@api semipublic

# File lib/parameters/parameters.rb, line 202
def get_param(name)
  name = name.to_sym

  unless has_param?(name)
    raise(Parameters::ParamNotFound,"parameter #{name.to_s.dump} was not found within #{self.inspect}")
  end

  return self.params[name]
end
has_param?(name) click to toggle source

@return [Boolean]

Specifies whether or not there is a instance parameter with the
specified name.

@example

obj.has_param?('rhost') # => true

@api semipublic

# File lib/parameters/parameters.rb, line 181
def has_param?(name)
  self.params.has_key?(name.to_sym)
end
initialize_params(values={}) click to toggle source

Initalizes the parameters of the object using the given values, which can override the default values of parameters.

@param [Hash] values

The names and values to initialize the instance parameters to.

@api public

# File lib/parameters/parameters.rb, line 28
def initialize_params(values={})
  if self.class.included_modules.include?(Parameters)
    self.class.each_param do |param|
      self.params[param.name] = param.to_instance(self)
    end
  end

  self.params = values if values.kind_of?(Hash)
end
param_value(name) click to toggle source

Returns the value of the parameter with a specific name.

@param [Symbol, String] name

The name of the instance parameter to search for.

@return [Object]

The value of the instance parameter with the specified name.

@raise [ParamNotFound]

Could not find the instance parameter with the specified name.

@example

obj.param_value('rhost') # => 80

@api semipublic

# File lib/parameters/parameters.rb, line 283
def param_value(name)
  get_param(name).value
end
parameter(name,options={}) click to toggle source

Adds a new parameter to the object.

@param [Symbol, String] name

The name for the new instance parameter.

@param [Hash] options

Additional options.

@option options [Class, Array] :type

The type to enforce the new parameter values to.

@option options [Object, Proc] :default

The default value for the new parameter.

@option options [String] :description

The description for the new parameter.

@return [InstanceParam]

The newly created instance parameter.

@example

obj.parameter('var')

@example

obj.parameter('var',:default => 3, :description => 'my variable')

@api public

# File lib/parameters/parameters.rb, line 78
def parameter(name,options={})
  name    = name.to_sym

  instance_eval %{
    # define the reader method for the parameter
    def #{name}
      get_param(#{name.inspect}).value
    end

    # define the writer method for the parameter
    def #{name}=(new_value)
      get_param(#{name.inspect}).value = new_value
    end

    def #{name}?
      !!get_param(#{name.inspect}).value
    end
  }

  # create the new parameter
  new_param = InstanceParam.new(
    self,
    name,
    options[:type],
    options[:description],
    options[:default]
  )

  # add the new parameter
  self.params[name] = new_param
  return new_param
end
params() click to toggle source

@return [Hash]

The instance parameters of the object.

@api semipublic

# File lib/parameters/parameters.rb, line 127
def params
  @parameters ||= {}
end
params=(values) click to toggle source

Sets the values of existing parameters in the object.

@param [Hash] values

The names and values to set the instance parameters to.

@example

obj.params = {:x => 5, :y => 2}
# => {:x=>5, :y=>2}

@api semipublic

# File lib/parameters/parameters.rb, line 143
def params=(values)
  values.each do |name,value|
    name = name.to_sym

    if has_param?(name)
      self.params[name].value = case value
                                when Parameters::ClassParam,
                                     Parameters::InstanceParam
                                  value.value
                                else
                                  value
                                end
    end
  end
end
set_param(name,value) click to toggle source

Sets an instance parameter.

@param [Symbol, String] name

The name of the instance parameter.

@param [Object] value

The new value for the instance parameter.

@return [Object]

The new value of the instance parameter.

@raise [ParamNotfound]

No instance parameter with the specified name could be found.

@example

obj.set_param('var',2)
# => 2

@since 0.3.0

@api semipublic

# File lib/parameters/parameters.rb, line 235
def set_param(name,value)
  name = name.to_sym

  unless has_param?(name)
    raise(Parameters::ParamNotFound,"parameter #{name.to_s.dump} was not found within #{self.to_s.dump}")
  end

  return self.params[name].value = value
end

Protected Instance Methods

require_params(*names) click to toggle source

Requires that the instance parameters with specific names have non ‘nil` values.

@return [true]

All the instance parameters have non `nil` values.

@raise [MissingParam]

One of the instance parameters was not set.

@api public

# File lib/parameters/parameters.rb, line 301
def require_params(*names)
  names.each do |name|
    name = name.to_s

    if instance_variable_get(:"@#{name}").nil?
      raise(Parameters::MissingParam,"parameter #{name.dump} has no value")
    end
  end

  return true
end