lab42_data_class 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6be60bd36bb2a9a538eb968067ff72eec653a4e9bc7dc3c8904558f803668e3
-  data.tar.gz: 4c1e75ab8907ce56ebcb71dd56d705afd9a1127e905ffe5344d846ddd0ade90a
+  metadata.gz: 70b03224373a4bdfe219cfb5d71d735f4a5b4d02c57531ea0f80a1729e542ce5
+  data.tar.gz: b04020b335831a2c8fb8070bb17056874bb9103c5dda7b0e313da93c8afd80a0
 SHA512:
-  metadata.gz: 33d4995e0048d390486d01bc3f07ad1be0e0dd5efbcf9693f656162e8691645be2e0b11e60df41defc771f9fc7108f1b35cef58aa4e0102b4912136094e06202
-  data.tar.gz: 02e403af2357e1b6b06e34afe9909777ab3f64a27d51843387ed20d1d349d96f7c9383fe22da386b42e7e5510180e6bc9a6a3d17c0b86cf16d1ff3f6cd02c8c3
+  metadata.gz: c360a0eb554b9356c92e0a395d09a2dd29dc76f64d2a805ef6ac8e1699a057bb01fc8a41be4bf2f34f3e3ec5d9eff336817541bc59d39f7d94c74131303e2f0d
+  data.tar.gz: 63395d4ede760ce63e7d92753ef370b2da666bafec309dee43f8c8549e768cc653d1976742441b583fd09a1a85535cc783834998ce494b903f2a40d380073a46

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 Maker.make_constraint(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,28 +77,34 @@ module Lab42
           define_method :initialize do |**params|
             proxy.check!(**params)
             proxy.init(self, **params)
+            proxy.validate!(self)
           end
         end
       end
 
       def _define_merge
-        proxy = self
         ->(*) do
           define_method :merge do |**params|
             values = to_h.merge(params)
-            DataClass(*proxy.positionals, **proxy.defaults, &proxy.block)
-              .new(**values)
+            self.class.new(**values)
           end
         end
       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.0"
+    VERSION = "0.5.1"
   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.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Robert Dober
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-19 00:00:00.000000000 Z
+date: 2022-02-24 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