lab42_data_class 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e64e5ffb63619de67de53f6618db6f25dc61e6a69b99fb6ae6cdc96446bbc490
-  data.tar.gz: ccf55ee9ef5d9bd3beabba0f852910ab37294a23415df78ca800e5ae411905ab
+  metadata.gz: 1819694c4684f3f4e377f04f4eb17d0842a1075ff7859eeef443c66dd7cfb458
+  data.tar.gz: 5af74933329ed924d51a1820d666c671973004edbd3ab00f6ba93378df71180f
 SHA512:
-  metadata.gz: c37f77d7fd444f7b64ba489e6d170b28e49ca176f74311f9aa0f269976e1561e56ba8561dd2f4b2f47cc526dc677943a98f9cd4c356c073bdc6bcebfcff29580
-  data.tar.gz: ed8a76bd074ad26ac625b17aec759d36300d5f0ba4ebe6ed6c827ee38149d6b8303d5bca7e8c62575fad3f2c29513577c89de0c607d15d5e109a9e813de7e59c
+  metadata.gz: 5e14f2656f03703aa867dce065bf9e4770cf043fd97d035cab9a6b869d9fb6e9749c2de3eef0b948e02c7ade07f85f75423c4b2412ed154574a6672e28411d9f
+  data.tar.gz: f831c9c8094f7224de088f6f03847791bcc91a33db6e565fc1ef3f45d5f3f5e29d18b05dfbcdbc7dcc422755d0ab87dc73f0c50a9de45dcd3df0916d87fb1c16

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
 
@@ -35,6 +40,7 @@ Well let us [speculate about](https://github.com/RobertDober/speculate_about) it
 
 ## Context `DataClass`
 
+
 ### Context: `DataClass` function
 
 Given
@@ -280,6 +286,214 @@ 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: Usage with `extend`
+
+All the above mentioned features can be achieved with a more conventional syntax by extending a class
+with `Lab42::DataClass`
+
+Given a class that extends `DataClass`
+```ruby
+    let :my_class do
+      Class.new do
+        extend Lab42::DataClass
+        attributes :age, member: false
+        constraint :member, Set.new([false, true])
+        validate(:too_young_for_member) { |instance| !(instance.member && instance.age < 18) }
+      end
+    end
+    let(:constraint_error) { Lab42::DataClass::ConstraintError }
+    let(:validation_error) { Lab42::DataClass::ValidationError }
+    let(:my_instance) { my_class.new(age: 42) }
+    let(:my_vip)      { my_instance.merge(member: true) }
+```
+
+Then we can observe that instances of such a class
+```ruby
+    expect(my_instance.to_h).to eq(age: 42, member: false)
+    expect(my_vip.to_h).to eq(age: 42, member: true)
+    expect(my_instance.member).to be_falsy
+```
+
+And we will get constraint errors if applicable
+```ruby
+    expect{my_instance.merge(member: nil)}
+      .to raise_error(constraint_error)
+```
+
+And of course validations still work too
+```ruby
+    expect{ my_vip.merge(age: 17) }
+      .to raise_error(validation_error, "too_young_for_member")
+```
+
+
 ## 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/kernel.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Kernel
+  def DataClass(*args, **kwds, &blk)
+    proxy = Lab42::DataClass::Proxy.new(*args, **kwds, &blk)
+    proxy.define_class!
+  end
+
+  def Pair(first, second)
+    Lab42::Pair.new(first, second)
+  end
+
+  def Triple(first, second, third)
+    Lab42::Triple.new(first, second, third)
+  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,90 @@
+# 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
+
+        def define_constraints(constraints)
+          errors = constraints.map(&define_constraint).compact
+          unless errors.empty?
+            raise ArgumentError,
+                  "constraints cannot be defined for undefined attributes #{errors.inspect}"
+          end
+
+          check_constraints_against_defaults(constraints)
+        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|
+              proxy.define_constraints(constraints)
+              self
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class Proxy
+      module Memos
+        def constraints
+          @__constraints__ ||= Hash.new { |h, k| h[k] = [] }
+        end
+
+        def defaults
+          @__defaults__ ||= {}
+        end
+
+        def members
+          @__members__ ||= unless (positionals + defaults.keys).empty?
+                             Set.new(positionals + defaults.keys)
+                           end
+        end
+
+        def positionals
+          @__positionals__ ||= []
+        end
+
+        def validations
+          @__validations__ ||= []
+        end
+
+        private
+
+        def _missing_initializers
+          @___missing_initializers__ ||=
+            positionals - actual_params.keys
+        end
+
+        def _illegal_initializers
+          @___illegal_initializers__ ||=
+            actual_params.keys - positionals - defaults.keys
+        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/memos'
+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, Memos, Validations
+
+      attr_reader :actual_params, :block, :klass
 
       def check!(**params)
         @actual_params = params
         raise ArgumentError, "missing initializers for #{_missing_initializers}" unless _missing_initializers.empty?
         raise ArgumentError, "illegal initializers #{_illegal_initializers}" unless _illegal_initializers.empty?
+
+        _check_constraints!(defaults.merge(params))
       end
 
       def define_class!
@@ -32,15 +39,22 @@ module Lab42
           .to_h
       end
 
+      def update!(with_positionals, with_keywords)
+        positionals.push(*with_positionals)
+        defaults.update(with_keywords)
+      end
+
       private
       def initialize(*args, **kwds, &blk)
-        @klass = Class.new
+        @klass = if Class === args.first
+                   args.shift
+                 else
+                   Class.new
+                 end
 
         @block = blk
-        @defaults = kwds
-        @members = Set.new(args + kwds.keys)
-        # TODO: Check for all symbols and no duplicates ⇒ v0.1.1
-        @positionals = args
+        defaults.update(kwds)
+        positionals.push(*args)
       end
 
       def _define_attr_reader
@@ -64,6 +78,7 @@ module Lab42
           define_method :initialize do |**params|
             proxy.check!(**params)
             proxy.init(self, **params)
+            proxy.validate!(self)
           end
         end
       end
@@ -78,12 +93,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
@@ -107,16 +129,6 @@ module Lab42
           data_class_instance.instance_variable_set("@#{key}", value)
         end
       end
-
-      def _missing_initializers
-        @___missing_initializers__ ||=
-          positionals - actual_params.keys
-      end
-
-      def _illegal_initializers
-        @___illegal_initializers__ ||=
-          actual_params.keys - positionals - defaults.keys
-      end
     end
   end
 end

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.6.0"
   end
 end
 #  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 
+require_relative './data_class/constraint_error'
+require_relative './data_class/kernel'
+require_relative './data_class/validation_error'
 require_relative './data_class/proxy'
 require_relative './pair'
 require_relative './triple'
 
-module Kernel
-  def DataClass(*args, **kwds, &blk)
-    proxy = Lab42::DataClass::Proxy.new(*args, **kwds, &blk)
-    proxy.define_class!
-  end
+module Lab42
+  module DataClass
+    def self.extended(extender)
+      proxy = Proxy.new(extender)
 
-  def Pair(first, second)
-    Lab42::Pair.new(first, second)
-  end
+      extender.module_eval do
+        define_singleton_method(:__data_class_proxy__){ proxy }
+      end
+    end
+
+    def attributes(*args, **kwds)
+      __data_class_proxy__.tap do |proxy|
+        proxy.update!(args, kwds)
+        proxy.define_class!
+      end
+    end
 
-  def Triple(first, second, third)
-    Lab42::Triple.new(first, second, third)
+    def constraint(member, constraint = nil, &block)
+      raise ArgumentError, "must not provide constraint (2nd argument) and a block" if block && constraint
+
+      __data_class_proxy__.define_constraints(member => constraint || block)
+    end
   end
 end
-
 #  SPDX-License-Identifier: Apache-2.0

metadata

@@ -1,20 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: lab42_data_class
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Robert Dober
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-22 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,15 @@ files:
 - LICENSE
 - README.md
 - lib/lab42/data_class.rb
+- lib/lab42/data_class/constraint_error.rb
+- lib/lab42/data_class/kernel.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/memos.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 +41,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 +57,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: []