Class: Libis::Tools::Parameter

Inherits:
Struct show all
Defined in:
lib/libis/tools/parameter.rb

Overview

A Parameter is like a class instance attribute on steroids. Contrary to regular attributes, Parameters are type-safe, can have a descriptive text explaining their use, a constraint that limits the values and any other properties for an application to use for their needs.

Parameters are inherited from base classes and can be overwritten without affecting the parameters in the parent class. For instance, a regular parameter in the parent class can be given a fixed value in the child class by giving it a default value and setting it’s frozen property to true. The same paremter in the parent class instances will still be modifieable. But the parameter in the child class instances will be frozen, even if accessed via the methods on parent class.

Important: the parameter will exist both on the class level as on the instance level, but the parameter on the class level is the parameter definition as described in the Parameter class. On the instance level, there are merely some parameter methods that access the parameter instance values with the help of the parameter definitions on the class. The implementation of the parameter instances is dealt with by the ParameterContainer module.

Constant Summary collapse

TRUE_BOOL =

Valid input strings for boolean parameter value, all converted to ‘true’

%w'true yes t y 1'
FALSE_BOOL =

Valid input strings for boolean parameter value, all converted to ‘false’

%w'false no f n 0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Struct

from_json, #set, #to_json

Constructor Details

#initialize(*args) ⇒ Parameter

Create a Parameter instance.

datatype can be omitted if the type can be derived from the

Parameters:

  • args (Array) —

    The values for:

    • name - Required. String for the name of the parameter. Any valid attribute name is acceptable.

    • default value - Any value. Will be coverted to the given datatype if present. Default is nil.

    • datatype - String. One of: bool, string, int, float, datetime, array, hash. If omitted it will be derived from the default value or set to the default ‘string’.

    • description - String describing the parameter’s use.

    • constraint - Array, Range, RegEx or single value. Default is nil meaning no constraint.

    • frozen - Boolean. Default is false; if true the parameter value cannot be changed from the default value.

    • options - Any Hash. It’s up to the applcation to interprete and use this info.



46
47
48
49
50
 
# File 'lib/libis/tools/parameter.rb', line 46

def initialize(*args)
  super(*args)
  self[:options] ||= {}
  self[:datatype] ||= guess_datatype
end

Instance Attribute Details

#constraint ⇒ Object

Returns the value of attribute constraint

Returns:

  • (Object) —

    the current value of constraint



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def constraint
  @constraint
end

#datatype ⇒ Object

Returns the value of attribute datatype

Returns:

  • (Object) —

    the current value of datatype



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def datatype
  @datatype
end

#default ⇒ Object

Returns the value of attribute default

Returns:

  • (Object) —

    the current value of default



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def default
  @default
end

#description ⇒ Object

Returns the value of attribute description

Returns:

  • (Object) —

    the current value of description



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def description
  @description
end

#frozen ⇒ Object

Returns the value of attribute frozen

Returns:

  • (Object) —

    the current value of frozen



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def frozen
  @frozen
end

#name ⇒ Object

Returns the value of attribute name

Returns:

  • (Object) —

    the current value of name



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def name
  @name
end

#options ⇒ Object

Returns the value of attribute options

Returns:

  • (Object) —

    the current value of options



33
34
35
 
# File 'lib/libis/tools/parameter.rb', line 33

def options
  @options
end

Class Method Details

.from_hash(h) ⇒ Object

Convience method to create a new Libis::Tools::Parameter from a Hash.

Parameters:

  • h (Hash) —

    Hash with parameter definition properties



92
93
94
 
# File 'lib/libis/tools/parameter.rb', line 92

def self.from_hash(h)
  h.each { |k, v| self[k.to_s.to_sym] = v }
end

Instance Method Details

#[](key) ⇒ Object

Retrieve a specific property of the parameter. If not found in the regular properties, the options Hash is scanned for the property.

Parameters:

  • key (Symbol) —

    name of the property



76
77
78
79
 
# File 'lib/libis/tools/parameter.rb', line 76

def [](key)
  return super(key) if members.include?(key)
  self[:options][key]
end

#[]=(key, value) ⇒ Object

Set a property of the parameter. If the property is not one of the regular properties, the property will be set in the options Hash.

Parameters:

  • value (Object) —

    value for the property. No type checking happens on this value

  • key (Symbol) —

    name of the property



85
86
87
88
 
# File 'lib/libis/tools/parameter.rb', line 85

def []=(key, value)
  return super(key, value) if members.include?(key)
  self[:options][key] = value
end

#dup ⇒ Object

Duplicates the parameter



53
54
55
56
57
58
 
# File 'lib/libis/tools/parameter.rb', line 53

def dup
  new_obj = super
  # noinspection RubyResolve
  new_obj[:options] = Marshal.load(Marshal.dump(self[:options]))
  new_obj
end

#merge!(other) ⇒ Object

Merges other parameter data into the current parameter

Parameters:



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/libis/tools/parameter.rb', line 62

def merge!(other)
  other.each do |k, v|
    if k == :options
      self[:options].merge!(v)
    else
      self[k] = v
    end
  end
  self
end

#parse(value = nil) ⇒ Object

Parse any value and try to convert to the correct datatype and check the constraints. Will throw an exception if not valid.

Parameters:

  • value (Object) (defaults to: nil) —

    Any value to parse, strings are best supported.

Returns:

  • (Object) —

    checked and converted value



116
117
118
119
120
 
# File 'lib/libis/tools/parameter.rb', line 116

def parse(value = nil)
  result = value.nil? ? self[:default] : convert(value)
  check_constraint(result)
  result
end

#to_h ⇒ Hash

Dumps the parameter properties into a Hash. The options properties are merged into the hash. If you do not want that, use Struct#to_h instead.

Returns:

  • (Hash) —

    parameter definition properties



100
101
102
103
104
105
 
# File 'lib/libis/tools/parameter.rb', line 100

def to_h
  super.inject({}) do |hash, key, value|
    key == :options ? value.each { |k, v| hash[k] = v } : hash[key] = value
    hash
  end
end

#valid_value?(value) ⇒ Boolean

Parse any value and try to convert to the correct datatype and check the constraints. Will return false if not valid, true otherwise.

Parameters:

  • value (Object) —

    Any value to check

Returns:

  • (Boolean) 


125
126
127
128
129
130
131
132
 
# File 'lib/libis/tools/parameter.rb', line 125

def valid_value?(value)
  begin
    parse(value)
  rescue
    return false
  end
  true
end