Module: Parameters

Defined in:
lib/parameters/param.rb,
lib/parameters/options.rb,
lib/parameters/version.rb,
lib/parameters/types/set.rb,
lib/parameters/types/uri.rb,
lib/parameters/parameters.rb,
lib/parameters/types/date.rb,
lib/parameters/types/hash.rb,
lib/parameters/types/proc.rb,
lib/parameters/types/time.rb,
lib/parameters/types/type.rb,
lib/parameters/class_param.rb,
lib/parameters/types/array.rb,
lib/parameters/types/class.rb,
lib/parameters/types/float.rb,
lib/parameters/types/types.rb,
lib/parameters/types/object.rb,
lib/parameters/types/regexp.rb,
lib/parameters/types/string.rb,
lib/parameters/types/symbol.rb,
lib/parameters/class_methods.rb,
lib/parameters/types/boolean.rb,
lib/parameters/types/integer.rb,
lib/parameters/instance_param.rb,
lib/parameters/module_methods.rb,
lib/parameters/types/date_time.rb,
lib/parameters/exceptions/missing_param.rb,
lib/parameters/exceptions/param_not_found.rb

Defined Under Namespace

Modules: ClassMethods, ModuleMethods, Options, Types Classes: ClassParam, InstanceParam, MissingParam, Param, ParamNotFound

Constant Summary collapse

VERSION =

The version of parameters

'0.4.4'

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



10
11
12
13
14
15
16
17
 
# 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

Instance Method Details

#class_params ⇒ Hash

Returns The parameteres of the class and it's ancestors.

Returns:

  • (Hash) —

    The parameteres of the class and it's ancestors.



117
118
119
 
# File 'lib/parameters/parameters.rb', line 117

def class_params
  self.class.params
end

#describe_param(name) ⇒ String

Returns the description of the parameter with a specific name.

Examples:

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

Parameters:

  • name (Symbol, String) —

    The name of the instance parameter to search for.

Returns:

  • (String) —

    The description of the instance parameter.

Raises:

  • (ParamNotFound) —

    Could not find the instance parameter with the specified name.



262
263
264
 
# File 'lib/parameters/parameters.rb', line 262

def describe_param(name)
  get_param(name).description
end

#each_param {|param| ... } ⇒ Object

Iterates over each instance parameter in the object.

Yields:

  • (param) —

    The block that will be passed each instance parameter.



167
168
169
 
# File 'lib/parameters/parameters.rb', line 167

def each_param(&block)
  self.params.each_value(&block)
end

#get_param(name) ⇒ InstanceParam

Searches for the instance parameter with a specific name.

Examples:

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

Parameters:

  • name (Symbol, String) —

    The name of the instance parameter to search for.

Returns:

  • (InstanceParam) —

    The instance parameter with the specified name.

Raises:

  • (ParamNotFound) —

    Could not find the instance parameter with the specified name.



202
203
204
205
206
207
208
209
210
 
# 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) ⇒ Boolean

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

Examples:

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

Returns:

  • (Boolean) —

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



181
182
183
 
# File 'lib/parameters/parameters.rb', line 181

def has_param?(name)
  self.params.has_key?(name.to_sym)
end

#initialize(*args, &block) ⇒ Object

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.



45
46
47
 
# File 'lib/parameters/parameters.rb', line 45

def initialize(*args,&block)
  initialize_params(args.first)
end

#initialize_params(values = {}) ⇒ Object

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

Parameters:

  • values (Hash) (defaults to: {}) —

    The names and values to initialize the instance parameters to.



28
29
30
31
32
33
34
35
36
 
# 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) ⇒ Object

Returns the value of the parameter with a specific name.

Examples:

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

Parameters:

  • name (Symbol, String) —

    The name of the instance parameter to search for.

Returns:

  • (Object) —

    The value of the instance parameter with the specified name.

Raises:

  • (ParamNotFound) —

    Could not find the instance parameter with the specified name.



283
284
285
 
# File 'lib/parameters/parameters.rb', line 283

def param_value(name)
  get_param(name).value
end

#parameter(name, options = {}) ⇒ InstanceParam

Adds a new parameter to the object.

Examples:

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

Parameters:

  • name (Symbol, String) —

    The name for the new instance parameter.

  • options (Hash) (defaults to: {}) —

    Additional options.

Options Hash (options):

  • :type (Class, Array[Class]) —

    The type to enforce the new parameter values to.

  • :default (Object, Proc) —

    The default value for the new parameter.

  • :description (String) —

    The description for the new parameter.

Returns:



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# 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 ⇒ Hash

Returns The instance parameters of the object.

Returns:

  • (Hash) —

    The instance parameters of the object.



127
128
129
 
# File 'lib/parameters/parameters.rb', line 127

def params
  @parameters ||= {}
end

#params=(values) ⇒ Object

Sets the values of existing parameters in the object.

Examples:

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

Parameters:

  • values (Hash) —

    The names and values to set the instance parameters to.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# 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

#require_params(*names) ⇒ true (protected)

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

Returns:

  • (true) —

    All the instance parameters have non nil values.

Raises:

  • (MissingParam) —

    One of the instance parameters was not set.



301
302
303
304
305
306
307
308
309
310
311
 
# 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

#set_param(name, value) ⇒ Object

Sets an instance parameter.

Examples:

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

Parameters:

  • name (Symbol, String) —

    The name of the instance parameter.

  • value (Object) —

    The new value for the instance parameter.

Returns:

  • (Object) —

    The new value of the instance parameter.

Raises:

  • (ParamNotfound) —

    No instance parameter with the specified name could be found.

Since:

  • 0.3.0



235
236
237
238
239
240
241
242
243
 
# 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