Module: Libis::Tools::ParameterContainer::ClassMethods

Defined in:
lib/libis/tools/parameter.rb

Overview

Methods created on class level.

Instance Method Summary collapse

Instance Method Details

#parameter(name = nil, **options) ⇒ Object

DSL method that allows creating parameter definitions on the class level.

It takes only one mandatory argument which is a Hash. The first entry is interpreted as ‘<name>: <default>’. The name for the parameter should be unique and the default value can be any value of type TrueClass, FalseClass, String, Integer, Float, Date, Time, DateTime, Array, Hash or nil.

The second up to last Hash entries are optional properties for the parameter. These are:

  • datatype: the type of values the parameter will accept. Valid values are:

    • ‘bool’ or ‘boolean’

    • ‘string’

    • ‘int’

    • ‘float’

    • ‘datetime’

    • ‘array’

    • ‘hash’

    Any other value will raise an Exception when the parameter is used. The value is case-insensitive and if not present, the datatype will be derived from the default value with ‘string’ being the default for NilClass. In any case the parameter will try its best to convert supplied values to the proper data type. For instance, an Integer parameter will accept 3, 3.1415, ‘3’ and Rational(10/3) as valid values and store them as the integer value 3. Likewise DateTime parameters will try to interprete date and time strings.

  • description: any descriptive text you want to add to clarify what this parameter is used for. Any tool can ask the class for its parameters and - for instance - can use this property to provide help in a GUI when asking the user for input.

  • constraint: adds a validation condition to the parameter. The condition value can be:

    • an array: only values that convert to a value in the list are considered valid.

    • a range: only values that convert to a value in the given range are considered valid.

    • a regular expression: only values that match the regular expression are considered valid.

    • a string: only values that are ‘==’ to the constraint are considered valid.

  • frozen: if set to true, prevents the class instance to set the parameter to any value other than the default. Mostly useful when a derived class needs a parameter in the parent class to be set to a specific value. Setting a value on a frozen parameter with the ‘parameter(name,value)’ method throws a Libis::Tools::ParameterFrozenError.

  • options: a hash with any additional properties that you want to associate to the parameter. Any key-value pair in this hash is added to the retrievable properties of the parameter. Likewise any property defined, that is not in the list of known properties is added to the options hash. In this aspect the ::Libis::Tools::Parameter class behaves much like an OpenStruct even though it is implemented as a Struct.



303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/libis/tools/parameter.rb', line 303

def parameter(name = nil, **options)
  return self.parameter_defs[name.to_s.to_sym] unless name.to_s.empty?
  return nil if options.keys.empty?
  param_def = options.shift
  name = param_def.first.to_s.to_sym
  default = param_def.last
  param = (self.parameter_defs[name] ||= Parameter.new(name, default))
  options[:default] = default
  options.each { |key, value| param[key] = value if value }
  param
end

#parameter_defs ⇒ Hash

Get a list of all parameter definitions. The list is initialized with duplicates of the parameter definitions of the parent class and each new parameter definition updates or appends the list.

Returns:



253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/libis/tools/parameter.rb', line 253

def parameter_defs
  return @parameters if @parameters
  @parameters = ::Concurrent::Hash.new
  begin
    self.superclass.parameter_defs.
        each_with_object(@parameters) do |(name, param), hash|
      hash[name] = param.dup
    end
  rescue NoMethodError
    # ignored
  end
  @parameters
end