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, **options) ⇒ Parameter

Create a Parameter instance.

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

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
51
 
# File 'lib/libis/tools/parameter.rb', line 46

def initialize(*args, **options)
  super(*args)
  self[:options] ||= {}
  self[:options].merge!(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



93
94
95
96
97
 
# File 'lib/libis/tools/parameter.rb', line 93

def self.from_hash(h)
  p = new
  h.each { |k, v| p[k.to_s.to_sym] = v }
  p
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



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

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



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

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

#dup ⇒ Object

Duplicates the parameter



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

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:



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

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



119
120
121
122
123
 
# File 'lib/libis/tools/parameter.rb', line 119

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



103
104
105
106
107
108
 
# File 'lib/libis/tools/parameter.rb', line 103

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) 


128
129
130
131
132
133
134
135
 
# File 'lib/libis/tools/parameter.rb', line 128

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