lab42_data_class 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b6b4667c08da4511e2e4889bf35d21badc1018d7c8ce61efb66c65162c1ca0f
-  data.tar.gz: 0206dff912a52398e24488fd53aaac9c65ceceb3706b38bb562aac37d6d9d296
+  metadata.gz: 4d8b97ca60e61ad4b3ec85555649e5538ca35ef1018bcdf2a1cd9f86d4183718
+  data.tar.gz: 7076ca2be4a3a8e5428b2fa0fa14523c416d491d14a8ba254842405332215dba
 SHA512:
-  metadata.gz: 23d410a7701bbdf4d175ab650e62fea5845c91d825d8346fa31955007571e2b862deccf478a831dab3e4404ef1d7f9f96018e13c672fe74a9592a534aceea186
-  data.tar.gz: 1e349c67fa94a4633ad5e933e755a5ab762e3b13fa28cd5a7cdfdc18a70cfe7f5190dd9d2d0ac78474a44df2dcf4010785b155b8920706cd17da98125aa55ba7
+  metadata.gz: c74e746f2f71ac1cbd89a10566b5655e0cb4e2e9d6ff6031e147bb833b8af91b5e1251e89b0ed826401a1915e3654b8543d065138fc705491bf1c684d85d4b97
+  data.tar.gz: bf15dd5127834637d6c9e0e78cbaf4cb50e75afd03b3ba4d763e186ad65f00df9076892bd151bebad30d4e1d8d49b287225e00ef0ccf6eed3e7965ba1f47af62

data/README.md

@@ -1,12 +1,19 @@
 
-[![Gem Version](http://img.shields.io/gem/v/lab42_data_class.svg)](https://rubygems.org/gems/lab42_data_class)
+[![Issue Count](https://codeclimate.com/github/RobertDober/lab42_data_class/badges/issue_count.svg)](https://codeclimate.com/github/RobertDober/lab42_data_class)
 [![CI](https://github.com/robertdober/lab42_data_class/workflows/CI/badge.svg)](https://github.com/robertdober/lab42_data_class/actions)
 [![Coverage Status](https://coveralls.io/repos/github/RobertDober/lab42_data_class/badge.svg?branch=main)](https://coveralls.io/github/RobertDober/lab42_data_class?branch=main)
+[![Gem Version](http://img.shields.io/gem/v/lab42_data_class.svg)](https://rubygems.org/gems/lab42_data_class)
+[![Gem Downloads](https://img.shields.io/gem/dt/lab42_data_class.svg)](https://rubygems.org/gems/lab42_data_class)
 
 
 # Lab42::DataClass
 
-An immutable dataclass
+
+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
 
@@ -31,6 +38,8 @@ require 'lab42/data_class'
 
 Well let us [speculate about](https://github.com/RobertDober/speculate_about) it to find out:
 
+## Context `DataClass`
+
 ### Context: `DataClass` function
 
 Given
@@ -276,6 +285,229 @@ 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_
+
+
+They distinguish themselves from `DataClass` classes by accepting only positional arguments, and
+cannot be converted to hashes.
+
+These are actually two classes and not class factories as they have a fixed interface , but let us speculate about them to learn what they can do for us.
+
+### Context: Constructor functions
+
+Given a pair
+```ruby
+    let(:token) { Pair("12", 12) }
+    let(:node)  { Triple("42", 4, 2) }
+```
+
+Then we can access their elements
+```ruby
+    expect(token.first).to eq("12")
+    expect(token.second).to eq(12)
+    expect(node.first).to eq("42")
+    expect(node.second).to eq(4)
+    expect(node.third).to eq(2)
+```
+
+And we can treat them like _Indexable_
+```ruby
+    expect(token[1]).to eq(12)
+    expect(token[-2]).to eq("12")
+    expect(node[2]).to eq(2)
+```
+
+And convert them to arrays of course
+```ruby
+    expect(token.to_a).to eq(["12", 12])
+    expect(node.to_a).to eq(["42", 4, 2])
+```
+
+And they behave like arrays in pattern matching too
+```ruby
+    token => [str, int]
+    node  => [root, lft, rgt]
+    expect(str).to eq("12")
+    expect(int).to eq(12)
+    expect(root).to eq("42")
+    expect(lft).to eq(4)
+    expect(rgt).to eq(2)
+```
+
+And of course the factory functions are equivalent to the constructors
+```ruby
+    expect(token).to eq(Lab42::Pair.new("12", 12))
+    expect(node).to eq(Lab42::Triple.new("42", 4, 2))
+```
 
 # LICENSE
 

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,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.3.3"
+    VERSION = "0.5.0"
   end
 end
 #  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class.rb

@@ -1,12 +1,24 @@
 # 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'
 
 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/eq_and_patterns.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Lab42
+  module EqAndPatterns
+    def [](idx)
+      to_a[idx]
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        to_a == other.to_a
+    end
+
+    def deconstruct(*)
+      to_a
+    end
+  end
+end
+#  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/pair.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'eq_and_patterns'
+module Lab42
+  class Pair
+    attr_reader :first, :second
+    include EqAndPatterns
+
+    def to_a
+      [first, second]
+    end
+
+    private
+
+    def initialize(first, second)
+      @first = first
+      @second = second
+    end
+  end
+end
+#  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/triple.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'eq_and_patterns'
+module Lab42
+  class Triple
+    attr_reader :first, :second, :third
+    include EqAndPatterns
+
+    def to_a
+      [first, second, third]
+    end
+
+    private
+
+    def initialize(first, second, third)
+      @first = first
+      @second = second
+      @third = third
+    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.3.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Robert Dober
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-31 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,14 +24,22 @@ 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
+- lib/lab42/triple.rb
 homepage: https://github.com/robertdober/lab42_data_class
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -46,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: []