lab42_data_class 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c062e2633e5881141e65113d2d60878733611bece697c933876ef1d9f62270e
-  data.tar.gz: bb5e524274338fda67063a8514cbe17a27c92ec8b62106061793456245729e30
+  metadata.gz: c6be60bd36bb2a9a538eb968067ff72eec653a4e9bc7dc3c8904558f803668e3
+  data.tar.gz: 4c1e75ab8907ce56ebcb71dd56d705afd9a1127e905ffe5344d846ddd0ade90a
 SHA512:
-  metadata.gz: ddfaa83d7d62a4f3ccdb6df66cc1b3462ee626ac970b2654e138d338c3e0ba8e016882445552d8fff4ffb13636953f17757991625bc1c54b5b3883c1eed43f89
-  data.tar.gz: 4dae3c50dc6b01e5f311f61e4f8aaf2b712db66a4ace5172b91df242411246e71dc2b30f29cded81ab5b95c77c0858f81282e72a481aff0921d4dbeea990d2f6
+  metadata.gz: 33d4995e0048d390486d01bc3f07ad1be0e0dd5efbcf9693f656162e8691645be2e0b11e60df41defc771f9fc7108f1b35cef58aa4e0102b4912136094e06202
+  data.tar.gz: 02e403af2357e1b6b06e34afe9909777ab3f64a27d51843387ed20d1d349d96f7c9383fe22da386b42e7e5510180e6bc9a6a3d17c0b86cf16d1ff3f6cd02c8c3

data/README.md

@@ -1,12 +1,14 @@
 
-[![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, Tuples and Triples
 
 ## Usage
 
@@ -31,6 +33,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
@@ -179,6 +183,159 @@ Then we can access the included method
     expect(class_level.new.humanize).to eq("my value is 1")
 ```
 
+### Context: Pattern Matching
+
+A `DataClass` object behaves like the result of it's `to_h` in pattern matching
+
+Given
+```ruby
+    let(:numbers) { DataClass(:name, values: []) }
+    let(:odds) { numbers.new(name: "odds", values: (1..4).map{ _1 + _1 + 1}) }
+    let(:evens) { numbers.new(name: "evens", values: (1..4).map{ _1 + _1}) }
+```
+
+Then we can match accordingly
+```ruby
+    match = case odds
+            in {name: "odds", values: [1, *]}
+              :not_really
+            in {name: "evens"}
+              :still_naaah
+            in {name: "odds", values: [hd, *]}
+              hd
+            else
+              :strange
+            end
+    expect(match).to eq(3)
+```
+
+And in `in` expressions
+```ruby
+    evens => {values: [_, second, *]}
+    expect(second).to eq(4)
+```
+
+#### Context: In Case Statements
+
+Given a nice little dataclass `Box`
+```ruby
+    let(:box) { DataClass content: nil }
+```
+
+Then we can also use it in a case statement
+```ruby
+    value = case box.new
+      when box
+        42
+      else
+        0
+      end
+    expect(value).to eq(42)
+```
+
+And all the associated methods
+```ruby
+    expect(box.new).to be_a(box)
+    expect(box === box.new).to be_truthy
+```
+
+### Context: Behaving like a `Proc`
+
+It is useful to be able to filter heterogeneous lists of `DataClass` instances by means of `&to_proc`, therefore
+
+Given two different `DataClass` objects
+```ruby
+    let(:class1) { DataClass :value }
+    let(:class2) { DataClass :value }
+```
+
+And a list of instances
+```ruby
+    let(:list) {[class1.new(value: 1), class2.new(value: 2), class1.new(value: 3)]}
+```
+
+Then we can filter
+```ruby
+    expect(list.filter(&class2)).to eq([class2.new(value: 2)])
+```
+
+### Context: Behaving like a `Hash`
+
+We have already seen the `to_h` method, however if we want to pass an instance of `DataClass` as 
+keyword parameters we need an implementation of `to_hash`, which of course is just an alias
+
+Given this keyword method
+```ruby
+    def extract_value(value:, **others)
+      [value, others]
+    end
+```
+And this `DataClass`:
+```ruby
+    let(:my_class) { DataClass(value: 1, base: 2) }
+```
+
+Then we can pass it as keyword arguments
+```ruby
+    expect(extract_value(**my_class.new)).to eq([1, base: 2])
+```
+
+## 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/proxy/mixin.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Lab42
+  module DataClass
+    class Proxy
+      module Mixin
+        def ==(other)
+          other.is_a?(self.class) &&
+            to_h == other.to_h
+        end
+
+        def deconstruct_keys(*)
+          to_h
+        end
+      end
+    end
+  end
+end
+#  SPDX-License-Identifier: Apache-2.0

data/lib/lab42/data_class/proxy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require_relative 'proxy/mixin'
 module Lab42
   module DataClass
     class Proxy
@@ -16,6 +17,8 @@ module Lab42
         klass.module_eval(&_define_attr_reader)
         klass.module_eval(&_define_initializer)
         _define_methods
+        klass.include(Mixin)
+        klass.module_eval(&block) if block
         klass
       end
 
@@ -47,15 +50,6 @@ module Lab42
         end
       end
 
-      def _define_eql?
-        ->(*) do
-          define_method :== do |other|
-            other.is_a?(self.class) &&
-              to_h == other.to_h
-          end
-        end
-      end
-
       def _define_freezing_constructor
         ->(*) do
           define_method :new do |*a, **p, &b|
@@ -87,10 +81,9 @@ module Lab42
 
       def _define_methods
         (class << klass; self end).module_eval(&_define_freezing_constructor)
+        (class << klass; self end).module_eval(&_define_to_proc)
         klass.module_eval(&_define_to_h)
         klass.module_eval(&_define_merge)
-        klass.module_eval(&_define_eql?)
-        klass.module_eval(&block) if block
       end
 
       def _define_to_h
@@ -99,6 +92,15 @@ module Lab42
           define_method :to_h do
             proxy.to_hash(self)
           end
+          alias_method :to_hash, :to_h
+        end
+      end
+
+      def _define_to_proc
+        ->(*) do
+          define_method :to_proc do
+            ->(other) { self === other }
+          end
         end
       end
 

data/lib/lab42/data_class/version.rb

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

data/lib/lab42/data_class.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lab42_data_class
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Robert Dober
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-22 00:00:00.000000000 Z
+date: 2022-02-19 00:00:00.000000000 Z
 dependencies: []
 description: |
   An Immutable DataClass for Ruby
@@ -24,7 +24,11 @@ files:
 - README.md
 - lib/lab42/data_class.rb
 - lib/lab42/data_class/proxy.rb
+- lib/lab42/data_class/proxy/mixin.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