Module: Parameters

Defined in:
lib/parameters/param.rb,
lib/parameters/parser.rb,
lib/parameters/version.rb,
lib/parameters/parameters.rb,
lib/parameters/class_param.rb,
lib/parameters/class_methods.rb,
lib/parameters/instance_param.rb,
lib/parameters/exceptions/missing_param.rb,
lib/parameters/exceptions/param_not_found.rb

Defined Under Namespace

Modules: ClassMethods, Parser Classes: ClassParam, InstanceParam, MissingParam, Param, ParamNotFound

Constant Summary

VERSION =
'0.1.9'

Class Method Summary

Instance Method Summary

Class Method Details

+ (Object) included(base)



9
10
11
# File 'lib/parameters/parameters.rb', line 9

def self.included(base)
  base.extend ClassMethods
end

Instance Method Details

- (Hash) class_params

The parameteres of the class and it’s ancestors.

Returns:

  • (Hash) — The parameteres of the class and it’s ancestors.


121
122
123
# File 'lib/parameters/parameters.rb', line 121

def class_params
  self.class.params
end

- (String) describe_param(name)

Returns the description of the parameter with a specific name.

Examples:

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

Parameters:

  • (Symbol, String) name — 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.


219
220
221
# File 'lib/parameters/parameters.rb', line 219

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

- (Object) each_param(&block) {|param| ... }

Iterates over each instance parameter in the object.

Yields:

  • (param) — The block that will be passed each instance parameter.


163
164
165
# File 'lib/parameters/parameters.rb', line 163

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

- (InstanceParam) get_param(name)

Searches for the instance parameter with a specific name.

Examples:

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

Parameters:

  • (Symbol, String) name — 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.


194
195
196
197
198
199
200
201
202
# File 'lib/parameters/parameters.rb', line 194

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.to_s.dump}",caller)
  end

  return self.params[name]
end

- (Boolean) has_param?(name)

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.


175
176
177
# File 'lib/parameters/parameters.rb', line 175

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

- (Parameters) initialize(*args, &block)

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.



52
53
54
# File 'lib/parameters/parameters.rb', line 52

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

- (Object) initialize_params(values = {})

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

Parameters:

  • (Hash) values (defaults to: {}) — The names and values to initialize the instance parameters to.


20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# File 'lib/parameters/parameters.rb', line 20

def initialize_params(values={})
  self.class.each_param do |param|
    # do not override existing instance value if present
    if instance_variable_get("@#{param.name}".to_sym).nil?
      begin
        if param.value.kind_of?(Proc)
          value = if param.value.arity > 0
                    param.value.call(self)
                  else
                    param.value.call()
                  end
        else
          value = param.value.clone
        end
      rescue TypeError
        value = param.value
      end

      instance_variable_set("@#{param.name}".to_sym,value)
    end

    self.params[param.name] = InstanceParam.new(self,param.name,param.description)
  end

  self.params = values if values.kind_of?(Hash)
end

- (Object) param_value(name)

Returns the value of the parameter with a specific name.

Examples:

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

Parameters:

  • (Symbol, String) name — 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.


238
239
240
# File 'lib/parameters/parameters.rb', line 238

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

- (InstanceParam) parameter(name, options = {})

Adds a new parameter to the object.

Examples:

  obj.parameter('var')

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

Parameters:

  • (Symbol, String) name — The name for the new instance parameter.
  • (Hash) options (defaults to: {}) — Additional options.

Options Hash (options):

  • (String) :description N/A — The description for the new parameter.
  • (Object, Proc) :default N/A — The default value for the new parameter.

Returns:



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
110
111
112
113
114
115
# File 'lib/parameters/parameters.rb', line 80

def parameter(name,options={})
  name = name.to_sym
  default = options[:default]
  description = options[:description]

  # resolve the default value
  if default.kind_of?(Proc)
    value = if default.arity > 0
              default.call(self)
            else
              default.call()
            end
  else
    value = default
  end

  # set the instance variable
  instance_variable_set("@#{name}".to_sym,value)

  # add the new parameter
  self.params[name] = InstanceParam.new(self,name,description)

  instance_eval %{
    # define the reader method for the parameter
    def #{name}
      instance_variable_get("@#{name}".to_sym)
    end

    # define the writer method for the parameter
    def #{name}=(value)
      instance_variable_set("@#{name}".to_sym,value)
    end
  }

  return params[name]
end

- (Hash) params

The instance parameters of the object.

Returns:

  • (Hash) — The instance parameters of the object.


129
130
131
# File 'lib/parameters/parameters.rb', line 129

def params
  @params ||= {}
end

- (Object) params=(values)

Sets the values of existing parameters in the object.

Examples:

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

Parameters:

  • (Hash) values — The names and values to set the instance parameters to.


143
144
145
146
147
148
149
150
151
152
153
154
155
# File 'lib/parameters/parameters.rb', line 143

def params=(values)
  values.each do |name,value|
    name = name.to_sym

    if has_param?(name)
      if (value.kind_of?(Parameters::ClassParam) || value.kind_of?(Parameters::InstanceParam))
        value = value.value
      end

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

- (true) require_params(*names) (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.


254
255
256
257
258
259
260
261
262
263
264
# File 'lib/parameters/parameters.rb', line 254

def require_params(*names)
  names.each do |name|
    name = name.to_s

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

  return true
end