lab42_data_class 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e64e5ffb63619de67de53f6618db6f25dc61e6a69b99fb6ae6cdc96446bbc490
-  data.tar.gz: ccf55ee9ef5d9bd3beabba0f852910ab37294a23415df78ca800e5ae411905ab
+  metadata.gz: 4d8b97ca60e61ad4b3ec85555649e5538ca35ef1018bcdf2a1cd9f86d4183718
+  data.tar.gz: 7076ca2be4a3a8e5428b2fa0fa14523c416d491d14a8ba254842405332215dba
 SHA512:
-  metadata.gz: c37f77d7fd444f7b64ba489e6d170b28e49ca176f74311f9aa0f269976e1561e56ba8561dd2f4b2f47cc526dc677943a98f9cd4c356c073bdc6bcebfcff29580
-  data.tar.gz: ed8a76bd074ad26ac625b17aec759d36300d5f0ba4ebe6ed6c827ee38149d6b8303d5bca7e8c62575fad3f2c29513577c89de0c607d15d5e109a9e813de7e59c
+  metadata.gz: c74e746f2f71ac1cbd89a10566b5655e0cb4e2e9d6ff6031e147bb833b8af91b5e1251e89b0ed826401a1915e3654b8543d065138fc705491bf1c684d85d4b97
+  data.tar.gz: bf15dd5127834637d6c9e0e78cbaf4cb50e75afd03b3ba4d763e186ad65f00df9076892bd151bebad30d4e1d8d49b287225e00ef0ccf6eed3e7965ba1f47af62

data/README.md

@@ -8,7 +8,12 @@
 
 # Lab42::DataClass
 
-An immutable Dataclass, Tuples and Triples
+
+An Immutable DataClass for Ruby
+
+Exposes a class factory function `Kernel::DataClass` and a class
+modifer `Module#dataclass', also creates two _tuple_ classes, `Pair` and
+`Triple`
 
 ## Usage
 
@@ -280,6 +285,173 @@ Then we can pass it as keyword arguments
     expect(extract_value(**my_class.new)).to eq([1, base: 2])
 ```
 
+### Context: Constraints
+
+Values of attributes of a `DataClass` can have constraints
+
+Given a `DataClass` with constraints
+```ruby
+    let :switch do
+      DataClass(on: false).with_constraint(on: -> { [false, true].member? _1 })
+    end
+```
+
+Then boolean values are acceptable
+```ruby
+    expect{ switch.new }.not_to raise_error
+    expect(switch.new.merge(on: true).on).to eq(true)
+```
+
+But we can neither construct or merge with non boolean values
+```ruby
+    expect{ switch.new(on: nil) }
+     .to raise_error(Lab42::DataClass::ConstraintError, "value nil is not allowed for attribute :on")
+    expect{ switch.new.merge(on: 42) }
+     .to raise_error(Lab42::DataClass::ConstraintError, "value 42 is not allowed for attribute :on")
+```
+
+And therefore defaultless attributes cannot have a constraint that is violated by a nil value
+```ruby
+    error_head = "constraint error during validation of default value of attribute :value"
+    error_body = "  undefined method `>' for nil:NilClass"
+    error_message = [error_head, error_body].join("\n")
+
+    expect{ DataClass(value: nil).with_constraint(value: -> { _1 > 0 }) }
+      .to raise_error(Lab42::DataClass::ConstraintError, /#{error_message}/)
+```
+
+And defining constraints for undefined attributes is not the best of ideas
+```ruby
+    expect { DataClass(a: 1).with_constraint(b: -> {true}) }
+      .to raise_error(ArgumentError, "constraints cannot be defined for undefined attributes [:b]")
+```
+
+
+#### Context: Convenience Constraints
+
+Often repeating patterns are implemented as non lambda constraints, depending on the type of a constraint
+it is implicitly converted to a lambda as specified below:
+
+Given a shortcut for our `ConstraintError`
+```ruby
+    let(:constraint_error) { Lab42::DataClass::ConstraintError }
+    let(:positive) { DataClass(:value) }
+```
+
+##### Symbols
+
+... are sent to the value of the attribute, this is not very surprising of course ;)
+
+Then a first implementation of `Positive`
+```ruby
+    positive_by_symbol = positive.with_constraint(value: :positive?)
+
+    expect(positive_by_symbol.new(value: 1).value).to eq(1)
+    expect{positive_by_symbol.new(value: 0)}.to raise_error(constraint_error)
+```
+
+##### Arrays
+
+... are also sent to the value of the attribute, this time we can provide paramaters
+And we can implement a different form of `Positive`
+```ruby
+    positive_by_ary = positive.with_constraint(value: [:>, 0])
+
+    expect(positive_by_ary.new(value: 1).value).to eq(1)
+    expect{positive_by_ary.new(value: 0)}.to raise_error(constraint_error)
+```
+
+If however we are interested in membership we have to wrap the `Array` into a `Set`
+
+##### Membership
+
+And this works with a `Set`
+```ruby
+    positive_by_set = positive.with_constraint(value: Set.new([*1..10]))
+
+    expect(positive_by_set.new(value: 1).value).to eq(1)
+    expect{positive_by_set.new(value: 0)}.to raise_error(constraint_error)
+```
+
+And also with a `Range`
+```ruby
+    positive_by_range = positive.with_constraint(value: 1..Float::INFINITY)
+
+    expect(positive_by_range.new(value: 1).value).to eq(1)
+    expect{positive_by_range.new(value: 0)}.to raise_error(constraint_error)
+```
+
+##### Regexen
+
+This seems quite obvious, and of course it works
+
+Then we can also have a regex based constraint
+```ruby
+    vowel = DataClass(:word).with_constraint(word: /[aeiou]/)
+
+    expect(vowel.new(word: "alpha").word).to eq("alpha")
+    expect{vowel.new(word: "krk")}.to raise_error(constraint_error)
+```
+
+##### Other callable objects as constraints
+
+
+Then we can also use instance methods to implement our `Positive`
+```ruby
+    positive_by_instance_method = positive.with_constraint(value: Fixnum.instance_method(:positive?))
+
+    expect(positive_by_instance_method.new(value: 1).value).to eq(1)
+    expect{positive_by_instance_method.new(value: 0)}.to raise_error(constraint_error)
+```
+
+Or we can use methods to implement it
+```ruby
+    positive_by_method = positive.with_constraint(value: 0.method(:<))
+
+    expect(positive_by_method.new(value: 1).value).to eq(1)
+    expect{positive_by_method.new(value: 0)}.to raise_error(constraint_error)
+```
+
+#### Context: Global Constraints aka __Validations__
+
+So far we have only speculated about constraints concerning one attribute, however sometimes we want
+to have arbitrary constraints which can only be calculated by access to more attributes
+
+Given a `Point` DataClass
+```ruby
+    let(:point) { DataClass(:x, :y).validate{ |point| point.x > point.y } }
+    let(:validation_error) { Lab42::DataClass::ValidationError }
+```
+
+Then we will get a `ValidationError` if we construct a point left of the main diagonal
+```ruby
+    expect{ point.new(x: 0, y: 1) }
+      .to raise_error(validation_error)
+```
+
+But as validation might need more than the default values we will not execute them at compile time
+```ruby
+    expect{ DataClass(x: 0, y: 0).validate{ |inst| inst.x > inst.y } }
+      .to_not raise_error
+```
+
+And we can name validations to get better error messages
+```ruby
+    better_point = DataClass(:x, :y).validate(:too_left){ |point| point.x > point.y }
+    ok_point     = better_point.new(x: 1, y: 0)
+    expect{ ok_point.merge(y: 1) }
+      .to raise_error(validation_error, "too_left")
+```
+
+And remark how bad unnamed validation errors might be
+```ruby
+    error_message_rgx = %r{
+       \#<Proc:0x[0-9a-f]+ \s .* spec/speculations/README_spec\.rb: \d+ > \z
+    }x
+    expect{ point.new(x: 0, y: 1) }
+      .to raise_error(validation_error, error_message_rgx)
+```
+
 ## Context: `Pair` and `Triple`
 
 Two special cases of a `DataClass` which behave like `Tuple` of size 2 and 3 in _Elixir_

data/lib/lab42/data_class/constraint_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class ConstraintError < RuntimeError
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/proxy/constraints/maker.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class Proxy
+      module Constraints
+        module Maker
+          extend self
+
+          def make_constraint(constraint)
+            case constraint
+            when Proc, Method
+              constraint
+            when Symbol
+              -> { _1.send(constraint) }
+            when Array
+              -> { _1.send(*constraint) }
+            when Regexp
+              -> { constraint.match?(_1) }
+            when UnboundMethod
+              -> { constraint.bind(_1).() }
+            else
+              _make_member_constraint(constraint)
+            end
+          end
+
+          private
+
+          def _make_member_constraint(constraint)
+            if constraint.respond_to?(:member?)
+              -> { constraint.member?(_1) }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/proxy/constraints.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "constraints/maker"
+module Lab42
+  module DataClass
+    class Proxy
+      module Constraints
+        def check_constraints_against_defaults(constraints)
+          errors = constraints
+                   .map(&_check_constraint_against_default)
+                   .compact
+          raise ConstraintError, errors.join("\n\n") unless errors.empty?
+        end
+
+        def define_constraint
+          ->((attr, constraint)) do
+            if members.member?(attr)
+              constraints[attr] << Maker.make_constraint(constraint)
+              nil
+            else
+              attr
+            end
+          end
+        end
+
+        private
+
+        def _check_constraint_against_default
+          ->((attr, constraint)) do
+            if defaults.key?(attr)
+              _check_constraint_against_default_value(attr, defaults[attr], constraint)
+            end
+          end
+        end
+
+        def _check_constraint_against_default_value(attr, value, constraint)
+          unless constraint.(value)
+            "default value #{value.inspect} is not allowed for attribute #{attr.inspect}"
+          end
+        rescue StandardError => e
+          "constraint error during validation of default value of attribute #{attr.inspect}\n  #{e.message}"
+        end
+
+        def _check_constraints_for_attr!
+          ->((k, v)) do
+            constraints[k]
+              .map(&_check_constraint!(k, v))
+          end
+        end
+
+        def _check_constraint!(attr, value)
+          ->(constraint) do
+            "value #{value.inspect} is not allowed for attribute #{attr.inspect}" unless constraint.(value)
+          rescue StandardError => e
+            "constraint error during validation of attribute #{attr.inspect}\n  #{e.message}"
+          end
+        end
+
+        def _check_constraints!(params)
+          errors = params
+                   .flat_map(&_check_constraints_for_attr!)
+                   .compact
+
+          raise ConstraintError, errors.join("\n\n") unless errors.empty?
+        end
+
+        def _define_with_constraint
+          proxy = self
+          ->(*) do
+            define_method :with_constraint do |**constraints|
+              errors = constraints.map(&proxy.define_constraint).compact
+              unless errors.empty?
+                raise ArgumentError,
+                      "constraints cannot be defined for undefined attributes #{errors.inspect}"
+              end
+
+              proxy.check_constraints_against_defaults(constraints)
+              self
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/proxy/validations.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class Proxy
+      module Validations
+        def validate!(instance)
+          errors = validations
+                   .map(&_check_validation!(instance))
+                   .compact
+
+          raise ValidationError, errors.join("\n") unless errors.empty?
+        end
+
+        private
+
+        def _define_with_validations
+          proxy = self
+          ->(*) do
+            define_method :validate do |name = nil, &block|
+              proxy.validations << [name, block]
+              self
+            end
+          end
+        end
+
+        def _check_validation!(instance)
+          ->((name, validation)) do
+            unless validation.(instance)
+              name || validation
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/proxy.rb

@@ -1,16 +1,23 @@
 # frozen_string_literal: true
 
 require 'set'
+require_relative 'proxy/constraints'
+require_relative 'proxy/validations'
 require_relative 'proxy/mixin'
 module Lab42
   module DataClass
     class Proxy
-      attr_reader :actual_params, :block, :defaults, :klass, :members, :positionals
+      include Constraints, Validations
+
+      attr_reader :actual_params, :all_params, :block, :constraints, :defaults, :klass, :members, :positionals
 
       def check!(**params)
         @actual_params = params
+        @all_params = defaults.merge(params)
         raise ArgumentError, "missing initializers for #{_missing_initializers}" unless _missing_initializers.empty?
         raise ArgumentError, "illegal initializers #{_illegal_initializers}" unless _illegal_initializers.empty?
+
+        _check_constraints!(all_params)
       end
 
       def define_class!
@@ -32,14 +39,20 @@ module Lab42
           .to_h
       end
 
+      def validations
+        @__validations__ ||= []
+      end
+
       private
       def initialize(*args, **kwds, &blk)
         @klass = Class.new
 
+        @constraints = Hash.new { |h, k| h[k] = [] }
+
         @block = blk
         @defaults = kwds
         @members = Set.new(args + kwds.keys)
-        # TODO: Check for all symbols and no duplicates ⇒ v0.1.1
+        # TODO: Check for all symbols and no duplicates ⇒ v0.5.1
         @positionals = args
       end
 
@@ -64,6 +77,7 @@ module Lab42
           define_method :initialize do |**params|
             proxy.check!(**params)
             proxy.init(self, **params)
+            proxy.validate!(self)
           end
         end
       end
@@ -78,12 +92,19 @@ module Lab42
       end
 
       def _define_methods
-        (class << klass; self end).module_eval(&_define_freezing_constructor)
-        (class << klass; self end).module_eval(&_define_to_proc)
+        class << klass; self end
+          .tap { |singleton| _define_singleton_methods(singleton) }
         klass.module_eval(&_define_to_h)
         klass.module_eval(&_define_merge)
       end
 
+      def _define_singleton_methods(singleton)
+        singleton.module_eval(&_define_freezing_constructor)
+        singleton.module_eval(&_define_to_proc)
+        singleton.module_eval(&_define_with_constraint)
+        singleton.module_eval(&_define_with_validations)
+      end
+
       def _define_to_h
         proxy = self
         ->(*) do

data/lib/lab42/data_class/validation_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class ValidationError < RuntimeError
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/version.rb

@@ -2,7 +2,7 @@
 
 module Lab42
   module DataClass
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end
 #  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative './data_class/constraint_error'
+require_relative './data_class/validation_error'
 require_relative './data_class/proxy'
 require_relative './pair'
 require_relative './triple'

metadata

@@ -1,20 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: lab42_data_class
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Robert Dober
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-22 00:00:00.000000000 Z
+date: 2022-02-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   An Immutable DataClass for Ruby
 
   Exposes a class factory function `Kernel::DataClass` and a class
-  modifer `Module#dataclass'
+  modifer `Module#dataclass', also creates two _tuple_ classes, `Pair` and
+  `Triple`
 email: robert.dober@gmail.com
 executables: []
 extensions: []
@@ -23,8 +24,13 @@ files:
 - LICENSE
 - README.md
 - lib/lab42/data_class.rb
+- lib/lab42/data_class/constraint_error.rb
 - lib/lab42/data_class/proxy.rb
+- lib/lab42/data_class/proxy/constraints.rb
+- lib/lab42/data_class/proxy/constraints/maker.rb
 - lib/lab42/data_class/proxy/mixin.rb
+- lib/lab42/data_class/proxy/validations.rb
+- lib/lab42/data_class/validation_error.rb
 - lib/lab42/data_class/version.rb
 - lib/lab42/eq_and_patterns.rb
 - lib/lab42/pair.rb
@@ -33,7 +39,7 @@ homepage: https://github.com/robertdober/lab42_data_class
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -49,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.3
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Finally a dataclass in ruby
 test_files: []