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:

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

API:

  • semipublic



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:

  • The name of the instance parameter to search for.

Returns:

  • The description of the instance parameter.

Raises:

  • Could not find the instance parameter with the specified name.

API:

  • semipublic



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.

API:

  • semipublic



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:

  • The name of the instance parameter to search for.

Returns:

  • The instance parameter with the specified name.

Raises:

  • Could not find the instance parameter with the specified name.

API:

  • semipublic



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:

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

API:

  • semipublic



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.

API:

  • public



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:

  • (defaults to: {})

    The names and values to initialize the instance parameters to.

API:

  • public



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:

  • The name of the instance parameter to search for.

Returns:

  • The value of the instance parameter with the specified name.

Raises:

  • Could not find the instance parameter with the specified name.

API:

  • semipublic



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:

  • The name for the new instance parameter.

  • (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:

  • The newly created instance parameter.

API:

  • public



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:

  • The instance parameters of the object.

API:

  • semipublic



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:

  • The names and values to set the instance parameters to.

API:

  • semipublic



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:

  • All the instance parameters have non nil values.

Raises:

  • One of the instance parameters was not set.

API:

  • public



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:

  • The name of the instance parameter.

  • The new value for the instance parameter.

Returns:

  • The new value of the instance parameter.

Raises:

  • No instance parameter with the specified name could be found.

Since:

  • 0.3.0

API:

  • semipublic



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