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.



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"

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

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


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.



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

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')

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.



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.



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}


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.

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

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