libis-tools 0.9.12 → 0.9.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2acfb7ca3db4644a7c4001df1ee44999ccc8632f
-  data.tar.gz: 32a297ad8bdc665211b6d4ff51efd67f9e026589
+  metadata.gz: 22d6fc69dcf878e87ea28eb0fbfd5965b7d2f15b
+  data.tar.gz: 48b5bf0cfdbe91755bb535132ad0efe76b29a116
 SHA512:
-  metadata.gz: 609edc8e2ec6db1ced8bb0db45b1b55c9f00ebc7b8c6c45cdb12fe7d8dc44194871d5902310b7e173d54c61b4d23cf233919879c3f3feb2d2dc249caf82ceaf0
-  data.tar.gz: e967facb80617a24e4bd3cd4ae2e80995b13e8672fb0dc65d79b2d663883aa3d464d8ed5d61d0faf45cf118363aa60457b32b5eb896c01589ba4f03d77f91ede
+  metadata.gz: 2d90037281c4f2972f18bd44126efac4a1de466a4ea248f5f4e43aed724773f4badee3b66192620171f664ca65cf16fd91d3b6541974b8a152bf02192aef1236
+  data.tar.gz: fc29123e0c225e5b0755e32948c44f3a080d1697718b9a6ba2cf7e648fac341f134e5905280eb3d1d73fe8413c138cf09d17bc21000a9fe7d575adae9539b4a3

data/README.md

@@ -316,9 +316,70 @@ into the internal structure. A MarcRecord is created by supplying it an XML node
 Libis::Tools::XmlDocument) that contains child nodes with the MARC data of a single record. The code will strip
 namespaces from the input in order to greatly simplify working with the XML.
  
+## Parameter
 
-
-
+The class ::Libis::Tools::Parameter and the ::Libis::Tools::ParameterContainer module provide a simple framework for
+instance variables that are type-safe and can easily be documented and provide defaults.
+ 
+To use these parameters a class should include the ::Libis::Tools::ParameterContainer module and add 'parameter' 
+statements to the body of the class definition. 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 NilClass.
+
+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 a RuntimeError 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. The '[]=' 
+method silently ignores the exception. In any case the default value will not be changed.
+
+* 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.
+
+Besides enabling the 'parameter' class method to define parameters, the ::Libis::Tools::ParameterContainer add the class
+method 'parameters' that will return a Hash with parameter names as keys and their respective parameter definitions as
+values. On each class instance the 'parameter' method is added and serves as both getter and setter for parameter values:
+With only one argument (the parameter name) it returns the current value for the parameter, but the optional second 
+argument will cause the method to set the parameter value. If the parameter is not available or the given value is not 
+a valid value for the parameter, the method will return the special constant ::Libis::ParameterContainer::NO_VALUE. The 
+methods '[]' and '[]=' serve as aliases for the getter and setter calls.
+
+Additionally two protected methods are available on the instance:
+* 'parameters': returns the Hash that keeps track of the current parameter values for the instance.
+* 'get_parameter_defintion': retrieves the parameter definition from the instance's class for the given parameter name.
+
+Any class that derives from a class that included the ::Libis::Tools::ParameterContainer module will automatically 
+inherit all parameter definitions from all of it's base classes and can override any of these parameter definitions e.g. 
+to change the default values for the parameter.
 
 ## Contributing
 

data/lib/libis/tools/parameter.rb

@@ -5,13 +5,26 @@ require 'libis/tools/extend/struct'
 module Libis
   module Tools
 
+    class ParameterValidationError < RuntimeError;
+    end
+    class ParameterFrozenError < RuntimeError;
+    end
+
     # noinspection RubyConstantNamingConvention
-    Parameter = ::Struct.new(:name, :default, :datatype, :description, :constraint, :options) do
+    Parameter = ::Struct.new(:name, :default, :datatype, :description, :constraint, :frozen, :options) do
 
       def initialize(*args)
         # noinspection RubySuperCallWithoutSuperclassInspection
         super(*args)
-        self.options = {} unless self.options
+        self[:options] ||= {}
+        self[:datatype] ||= guess_datatype if args[1]
+      end
+
+      def dup
+        new_obj = super
+        # noinspection RubyResolve
+        new_obj[:options] = Marshal.load(Marshal.dump(self[:options]))
+        new_obj
       end
 
       def [](key)
@@ -20,19 +33,19 @@ module Libis
         self[:options][key]
       end
 
-      def []=(key,value)
+      def []=(key, value)
         # noinspection RubySuperCallWithoutSuperclassInspection
-        return super(key,value) if members.include?(key)
+        return super(key, value) if members.include?(key)
         self[:options][key] = value
       end
 
       def self.from_hash(h)
-        h.each { |k,v| self[k.to_s.to_sym] = v }
+        h.each { |k, v| self[k.to_s.to_sym] = v }
       end
 
       def to_h
         super.inject({}) do |hash, key, value|
-          key == :options ? value.each {|k,v| hash[k] = v} : hash[key] = value
+          key == :options ? value.each { |k, v| hash[k] = v } : hash[key] = value
           hash
         end
       end
@@ -41,12 +54,7 @@ module Libis
       FALSE_BOOL = %w'false no f n 0'
 
       def parse(value = nil)
-        result = if value.nil?
-                   send(:default)
-                 else
-                     dtype = guess_datatype.to_s.downcase
-                     convert(dtype, value)
-                 end
+        result = value.nil? ? self[:default] : convert(value)
         check_constraint(result)
         result
       end
@@ -60,36 +68,37 @@ module Libis
         true
       end
 
-      def guess_datatype
-        return send(:datatype) if send(:datatype)
-        case send(:default)
-          when TrueClass, FalseClass
-            'bool'
-          when NilClass
-            'string'
-          when Integer
-            'int'
-          when Float
-            'float'
-          when DateTime, Date, Time
-            'datetime'
-          when Array
-            'array'
-          when Hash
-            'hash'
-          else
-            send(:default).class.name.downcase
-        end
-      end
-
       private
 
-      def convert(dtype, v)
-        case dtype.to_s.downcase
+      def guess_datatype
+        self[:datatype] || case self[:default]
+                             when TrueClass, FalseClass
+                               'bool'
+                             when NilClass
+                               'string'
+                             when Integer
+                               'int'
+                             when Float
+                               'float'
+                             when DateTime, Date, Time
+                               'datetime'
+                             when Array
+                               'array'
+                             when Hash
+                               'hash'
+                             else
+                               self[:default].class.name.downcase
+                           end
+      end
+
+      def convert(v)
+        case self[:datatype]
           when 'boolean', 'bool'
             return true if TRUE_BOOL.include?(v.to_s.downcase)
             return false if FALSE_BOOL.include?(v.to_s.downcase)
-            raise ArgumentError, "No boolean information in '#{v.to_s}'. Valid values are: '#{TRUE_BOOL.join('\', \'')}' and '#{FALSE_BOOL.join('\', \'')}'."
+            raise ParameterValidationError, "No boolean information in '#{v.to_s}'. " +
+                                              "Valid values are: '#{TRUE_BOOL.join('\', \'')}" +
+                                              "' and '#{FALSE_BOOL.join('\', \'')}'."
           when 'string'
             return v.to_s.gsub('%s', Time.now.strftime('%Y%m%d%H%M%S'))
           when 'int'
@@ -105,17 +114,19 @@ module Libis
             return v.to_a if v.respond_to?(:to_a)
           when 'hash'
             return v when v.is_a?(Hash)
-            return Hash[(0...v.size).zip(v)] when v.is_a?(Array)
+                       return Hash[(0...v.size).zip(v)] when v.is_a?(Array)
           else
-            raise RuntimeError, "Datatype not supported: '#{dtype}'"
+            raise ParameterValidationError, "Datatype not supported: '#{self[:datatype]}'"
         end
         nil
       end
 
       def check_constraint(v, constraint = nil)
-        constraint ||= send(:constraint)
+        constraint ||= self[:constraint]
         return if constraint.nil?
-        raise ArgumentError, "Value '#{v}' is not allowed (constraint: #{constraint})." unless constraint_checker(v, constraint)
+        unless constraint_checker(v, constraint)
+          raise ParameterValidationError, "Value '#{v}' is not allowed (constraint: #{constraint})."
+        end
       end
 
       def constraint_checker(v, constraint)
@@ -142,23 +153,30 @@ module Libis
 
       module ClassMethods
 
-        def parameter(options = {})
-          if options.is_a? Hash
-            return nil if options.keys.empty?
-            param_def = options.shift
-            name = param_def.first.to_s.to_sym
-            default = param_def.last
-            parameters[name] = Parameter.new(name, default) if parameters[name].nil?
-            options.each { |key, value| parameters[name][key] = value if value }
-          else
-            param_def = parameters[options]
-            return param_def unless param_def.nil?
-            self.superclass.parameter(options) rescue nil
+        def parameter_defs
+          return @parameters if @parameters
+          @parameters = 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
 
-        def parameters
-          @parameters ||= Hash.new
+        def parameter(options = {})
+          return self.parameter_defs[options] unless options.is_a? Hash
+          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
 
       end
@@ -177,6 +195,9 @@ module Libis
           param_def.parse(param_value)
         else
           return NO_VALUE unless param_def.valid_value?(value)
+          if param_def[:frozen]
+            raise ParameterFrozenError, "Parameter '#{param_def[:name]}' is frozen in '#{self.class.name}'"
+          end
           parameters[name] = value
         end
       end
@@ -187,16 +208,18 @@ module Libis
 
       def []=(name, value)
         parameter name, value
+      rescue ParameterFrozenError
+        # ignored
       end
 
       protected
 
       def parameters
-        @parameters ||= Hash.new
+        @parameter_values ||= Hash.new
       end
 
       def get_parameter_definition(name)
-        self.class.parameter(name)
+        self.class.parameter_defs[name]
       end
 
     end # ParameterContainer

data/lib/libis/tools/version.rb

@@ -1,5 +1,5 @@
 module Libis
   module Tools
-    VERSION = '0.9.12'
+    VERSION = '0.9.13'
   end
 end

data/libis-tools.gemspec

@@ -32,7 +32,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'awesome_print'
 
   spec.add_runtime_dependency 'backports', '~> 3.6'
-  spec.add_runtime_dependency 'savon', '~> 2.0'
   spec.add_runtime_dependency 'nokogiri', '~> 1.6'
   spec.add_runtime_dependency 'gyoku',  '~> 1.2'
   spec.add_runtime_dependency 'nori', '~> 2.4'

data/spec/parameter_container_spec.rb

@@ -7,10 +7,10 @@ describe 'ParameterContainer' do
   class TestContainer
     include ::Libis::Tools::ParameterContainer
 
-    parameter check: true
-    parameter count: 0
-    parameter price: 1.0
-    parameter name: 'nobody'
+    parameter check: true, description: 'check parameter'
+    parameter count: 0, description: 'count parameter'
+    parameter price: 1.0, description: 'price parameter'
+    parameter name: 'nobody', description: 'name parameter'
     parameter calendar: Date.new(2014, 01, 01)
     parameter clock: Time.parse('10:10')
     parameter timestamp: DateTime.new(2014, 01, 01, 10, 10)
@@ -19,12 +19,18 @@ describe 'ParameterContainer' do
   end
 
   class DerivedContainer < TestContainer
-    parameter name: 'somebody'
-    parameter check: 'yes'
+    parameter name: 'somebody', description: 'derived name parameter', frozen: true
+    parameter check: 'no'
+    parameter new_derived_param: false
   end
 
-  class DerivedDerivedContainer < DerivedContainer; end
-  class DerivedDerivedDerivedContainer < DerivedDerivedContainer; end
+  class DerivedDerivedContainer < DerivedContainer
+    parameter price: 2.0, description: 'derived derived price parameter'
+  end
+
+  class DerivedDerivedDerivedContainer < DerivedDerivedContainer
+    parameter price: 3.0, description: 'derived derived derived price parameter'
+  end
 
   let(:test_container) { TestContainer.new }
   let(:derived_container) { DerivedContainer.new }
@@ -96,17 +102,51 @@ describe 'ParameterContainer' do
     expect(test_container.class.parameter(:with_options)[:c]).to be 3
   end
 
-  it 'derived class should override parameter values from parent class' do
+  it 'derived class should inherit parameters of the parent class' do
+    expect(derived_container.parameter(:price)).to eq 1.0
+    expect(derived_container.class.parameter(:price)[:description]).to eq 'price parameter'
+  end
+
+  it 'derived class should override parameter values and propertiesfrom parent class' do
     expect(derived_container.parameter(:name)).to eq 'somebody'
-    expect(derived_container.parameter(:check)).to eq 'yes'
+    expect(derived_container.parameter(:check)).to eq 'no'
   end
 
-  it 'derived class should be able to access parameters of parent class' do
-    expect(derived_container.parameter(:price)).to eq 1.0
+  it 'overrides in the derived classes should not change values in the parent classes' do
+    expect(test_container.parameter(:check)).to eq true
+    expect(test_container.parameter(:price)).to eq 1.0
+    expect(test_container.class.parameter(:price)[:description]).to eq 'price parameter'
   end
 
   it 'derivation should be supported over multiple levels' do
-    expect(derived_derived_derived_container.parameter(:price)).to eq 1.0
+    expect(derived_container.parameter(:price)).to eq 1.0
+    expect(derived_derived_container.parameter(:price)).to eq 2.0
+    expect(derived_derived_derived_container.parameter(:price)).to eq 3.0
+    expect(derived_container.class.parameter(:price)[:description]).to eq 'price parameter'
+    expect(derived_derived_container.class.parameter(:price)[:description]).to eq 'derived derived price parameter'
+    expect(derived_derived_derived_container.class.parameter(:price)[:description]).to eq 'derived derived derived price parameter'
+  end
+
+  it 'frozen parameters should be read-only' do
+    expect {
+      derived_container.parameter(:name, 'anybody')
+    }.to raise_error(::Libis::Tools::ParameterFrozenError)
+    expect(derived_container.parameter(:name)).to eq 'somebody'
+    expect {
+      derived_container[:name] = 'anybody'
+    }.not_to raise_error
+    expect(derived_container[:name]).to eq 'somebody'
+  end
+
+  it 'frozen state should not affect parameter in parent class' do
+    expect {
+      test_container.parameter(:name, 'anybody')
+    }.not_to raise_error
+    expect(test_container.parameter(:name)).to eq 'anybody'
+    expect {
+      test_container[:name] = 'everybody'
+    }.not_to raise_error
+    expect(test_container[:name]).to eq 'everybody'
   end
 
 end

data/spec/parameter_spec.rb

@@ -21,7 +21,7 @@ describe 'Parameter' do
 
   it 'should detect datatype from default value' do
     @parameter_types.each do |dtype|
-      expect(eval("@#{dtype}_parameter").guess_datatype).to eq dtype
+      expect(eval("@#{dtype}_parameter").send(:guess_datatype)).to eq dtype
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libis-tools
 version: !ruby/object:Gem::Version
-  version: 0.9.12
+  version: 0.9.13
 platform: ruby
 authors:
 - Kris Dekeyser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-07 00:00:00.000000000 Z
+date: 2015-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,20 +108,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: savon
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -310,7 +296,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: LIBIS toolbox.