portrayal 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6b15fe5bee4f60e8369a839ecad908c35bdbba34559e324f71c3a8404586ad
-  data.tar.gz: 279dc9030eea091d806fa9e02178783d02063c6efc731bc601a48a68e50f8281
+  metadata.gz: acf906a0356260f40fbe25b94b12f72f8c696ee723dff3c2f7dc0f3817154fd0
+  data.tar.gz: 0bb4b5a5d4982a59f6e66cd7fa2fe7eeec93b7880537c9e605c47f2d1b0df009
 SHA512:
-  metadata.gz: a3c414e415b48127c4f86ee41b7b5d0eed7730ea7316c356afa533f539acd42bdf70c08e1c64f78ddd7ba444da47f4069dbdf8716d42592a8d1b15ec38ca7ff4
-  data.tar.gz: 2fdab00d88f76ae116af03e14d883346797cf60c21ab0569823f6dd869f3efe368db1b9b2d1e41548619e1666de8acf38d555647a2e29270f0c35e6e512d7aa8
+  metadata.gz: 5d3543a802ba4dad5b8c746fa2e187b0debb95bd52354509bb29c2d88e6977d622aeafc8fca3db0a65811a9918c7044985c3355bea78799a0b7730b84da28e21
+  data.tar.gz: 66f61afd2be1633c12739d49db088265d90279b622b4f4bf050bba2c4d7dc6444ce232e16be00485702ef9285fe2507758d8fdfee447414ac35bc44fe07a5e89

data/CHANGELOG.md

@@ -2,6 +2,21 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+## 0.9.0 - 2023-05-06
+
+None of these changes should break anything for you, only speed things up, unless you're doing something very weird.
+
+* Rewrite internals to improve runtime performance. No longer depend on `portrayal.attributes`, instead generating ruby code that references keywords literally (much more efficient).
+* All attr_readers and other methods such as `eql?`, `==`, `freeze`, etc are now included as a module, rather than class_eval'ed into your class. This lets you use `super` when overriding them.
+* Class method `portrayal` now appears when you call `extend Portrayal`, and not after the first `keyword` declaration. (Instance methods are still added upon `keyword`.)
+* Remove `portrayal[]` shortcut that accessed `portrayal.schema` (use `portrayal.schema[]` directly instead).
+* Remove `portrayal.render_initialize`.
+* Add `portrayal.module`, which is the module included in your struct.
+* Add `portrayal.render_module_code`, which renders the code for the module.
+* Bring back class comparison to `==` (reverses a change in 0.3.0). Upon further research, it seems class comparison is always necessary.
+* Methods `==`, `eql?`, `hash`, `initialize_dup`, `initialize_clone`, and `freeze` now operate on @instance @variables, not reader method return values.
+* Methods `deconstruct` and `deconstruct_keys` now quietly exclude private/protected keywords.
+
 ## 0.8.0 - 2023-01-27
 
 * Add pattern matching support (`#deconstruct` and `#deconstruct_keys`).

data/README.md

@@ -1,4 +1,4 @@
-![RSpec](https://github.com/maxim/portrayal/workflows/RSpec/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/portrayal.svg)](https://badge.fury.io/rb/portrayal) ![RSpec](https://github.com/maxim/portrayal/workflows/RSpec/badge.svg)
 
 # Portrayal
 
@@ -8,7 +8,7 @@ Inspired by:
   - Piotr Solnica's [virtus](https://github.com/solnic/virtus)
   - Everything [Michel Martens](https://github.com/soveran)
 
-Portrayal is a minimalist gem (~130 loc, no dependencies) for building struct-like classes. It provides a small yet powerful step up from plain ruby with its one and only `keyword` method.
+Portrayal is a minimalist gem (~110 loc, no dependencies) for building struct-like classes. It provides a small yet powerful step up from plain ruby with its one and only `keyword` method.
 
 ```ruby
 class Person < MySuperClass
@@ -38,6 +38,7 @@ When you call `keyword`:
 * It defines `#hash` for hash equality
 * It defines `#dup` and `#clone` that propagate to all keyword values
 * It defines `#freeze` that propagates to all keyword values
+* It defines `#deconstruct` and `#deconstruct_keys` for pattern matching
 * It creates a nested class when you supply a block
 * It inherits parent's superclass when creating a nested class
 
@@ -76,6 +77,14 @@ class Person < MySuperClass
     super
   end
 
+  def deconstruct
+    [ name, age, favorite_fruit, address ]
+  end
+
+  def deconstruct_keys(*)
+    { name: name, age: age, favorite_fruit: favorite_fruit, address: address }
+  end
+
   def initialize_dup(source)
     @name = source.name.dup
     @age = source.age.dup
@@ -123,6 +132,14 @@ class Person < MySuperClass
       super
     end
 
+    def deconstruct
+      [ street, city ]
+    end
+
+    def deconstruct_keys(*)
+      { street: street, city: city }
+    end
+
     def initialize_dup(source)
       @street = source.street.dup
       @city = source.city.dup
@@ -336,9 +353,9 @@ else
 end # => "matched"
 ```
 
-### Schema
+### Introspection
 
-Every class that has at least one keyword defined in it automatically receives a class method called `portrayal`. This method is a schema of your object with some additional helpers.
+Every class that extends Portrayal receives a method called `portrayal`. This method is a schema of your object with some additional helpers.
 
 #### `portrayal.keywords`
 
@@ -348,7 +365,7 @@ Get all keyword names.
 Address.portrayal.keywords # => [:street, :city, :postcode, :country]
 ```
 
-#### `portrayal.attributes`
+#### `portrayal.attributes(object)`
 
 Get all names + values as a hash.
 
@@ -371,12 +388,14 @@ Portrayal steps back from things like type enforcement, coercion, and writer met
 
 #### Good Constructors
 
-The fact that we keep these portrayal structs read-only (nothing stops you from adding writers, but I will personally frown upon you), all of the responsibility of building them shifts into constructors. This is a good thing, because good constructors clearly define their dependencies, as well as giving us ample room for performing coercion.
+Since a portrayal object is read-only (nothing stops you from adding writers, but I will personally frown upon you), you must set all its values in a constructor. This is a good thing, because it lets us study, coerce, and validate all the passed-in arguments in one convenient place. We're assured that once instantiated, the object is valid. And of course we can have multiple constructors if needed. They serve as adapters for different kinds of input.
 
 ```ruby
 class Address < ApplicationStruct
   class << self
     def from_form(params)
+      raise ArgumentError, 'invalid postcode' unless postcode =~ /\A\d+\z/
+
       new \
         street:   params[:street].to_s,
         city:     params[:city].to_s,
@@ -400,16 +419,18 @@ class Address < ApplicationStruct
 end
 ```
 
-Good constructors can also depend on one another to successively break down dependnecies into essential parts. This is similar to how in functional languages one can use recursion and pattern matching.
+Good constructors can depend on one another to successively convert arguments into keywords. This is similar to how in functional languages one can use recursion and pattern matching.
 
 ```ruby
 class Email < ApplicationStruct
   class << self
+    # Extract parts of an email from JSON, and kick it over to from_parts.
     def from_publishing_service_json(json)
       subject, header, body, footer = *JSON.parse(json)
       from_parts(subject: subject, header: header, body: body, footer: footer)
     end
 
+    # Combine parts into the final keywords: subject and body.
     def from_parts(subject:, header:, body:, footer:)
       new(subject: subject, body: "#{header}#{body}#{footer}")
     end
@@ -443,15 +464,45 @@ class Address < ApplicationStruct
 end
 ```
 
+If a particular constructor doesn't belong on your object (i.e. a 3rd party module is responsible for parsing its own data and producing your object) — you don't need to have a special constructor. Remember that each portrayal object comes with `.new`, which accepts every keyword directly. Let the module do all the parsing on its side and call `.new` with final values.
+
 #### No Reinventing The Wheel
 
-Portrayal leans on Ruby to take care of enforcing required keyword arguments, and setting keyword argument defaults. It actually generates standard ruby keyword arguments for you behind the scenes. You can even see the code by checking `YourClass.portrayal.definition_of_initialize`.
+Portrayal leans on Ruby's built-in features as much as possible. For initialize and default values it generates standard ruby keyword arguments. You can see all the code portrayal generates for your objects by running `YourClass.portrayal.render_module_code`.
 
 ```irb
-Address.portrayal.definition_of_initialize
-=> "def initialize(street:,city:,postcode:,country: self.class.portrayal.call_default(:country)); @street = street; @city = city; @postcode = postcode; @country = country end"
+[1] pry(main)> puts Address.portrayal.render_module_code
+attr_accessor :street, :city, :postcode, :country
+protected :street=, :city=, :postcode=, :country=
+def initialize(street:, city:, postcode:, country: self.class.portrayal.schema[:country]); @street = street.is_a?(::Portrayal::Default) ? street.(self) : street; @city = city.is_a?(::Portrayal::Default) ? city.(self) : city; @postcode = postcode.is_a?(::Portrayal::Default) ? postcode.(self) : postcode; @country = country.is_a?(::Portrayal::Default) ? country.(self) : country end
+def hash; [self.class, {street: @street, city: @city, postcode: @postcode, country: @country}].hash end
+def ==(other); self.class == other.class && @street == other.instance_variable_get('@street') && @city == other.instance_variable_get('@city') && @postcode == other.instance_variable_get('@postcode') && @country == other.instance_variable_get('@country') end
+alias eql? ==
+def freeze; @street.freeze; @city.freeze; @postcode.freeze; @country.freeze; super end
+def initialize_dup(src); @street = src.instance_variable_get('@street').dup; @city = src.instance_variable_get('@city').dup; @postcode = src.instance_variable_get('@postcode').dup; @country = src.instance_variable_get('@country').dup; super end
+def initialize_clone(src); @street = src.instance_variable_get('@street').clone; @city = src.instance_variable_get('@city').clone; @postcode = src.instance_variable_get('@postcode').clone; @country = src.instance_variable_get('@country').clone; super end
+def deconstruct
+  public_syms = [:street, :city, :postcode, :country].select { |s| self.class.public_method_defined?(s) }
+  public_syms.map { |s| public_send(s) }
+end
+def deconstruct_keys(keys)
+  filtered_keys = [:street, :city, :postcode, :country].select {|s| self.class.public_method_defined?(s) }
+  filtered_keys &= keys if Array === keys
+  Hash[filtered_keys.map { |k| [k, public_send(k)] }]
+end
 ```
 
+#### Implementation decisions
+
+Here are some key architectural decisions that took a lot of thinking. If you have good counter-arguments please make an issue, or contact me on [mastodon](https://ruby.social/@maxim) / [twitter](https://twitter.com/hakunin).
+
+1. **Why do methods `#==`, `#eql?`, `#hash` rely on @instance @variables instead of calling reader methods?**  
+   Portrayal makes a careful assumption on what most people would expect from object equality: a comparison of type and runtime state (which is what instance variables are). Portrayal avoids comparing object structure and method return values, because it's too situational whether they should participate in equality or not. If you have such a situation, you're welcome to redefine `==` in your class.
+2. **Why do methods `clone` and `dup` copy @instance @variables instead of calling reader methods?**  
+   As with the reason for `==`, when we clone an object, we want to clone its type and runtime state. Not the artifacts of its structure. It's too presumptious for a clone to assume that method outputs are authoritative. If objects are written deterministically, then by cloning their inner runtime state we should get the same reader method outputs anyway. If you are doing something else, you're welcome to redefine `initialize_clone`/`initialize_dup` in your class.
+3. **Why does pattern matching (`deconstruct`/`deconstruct_keys`) call reader methods rather than reading @instance @variables?**  
+   Unlike equality or object replication, in case of pattern matching we're no longer trying to figure out object's identity, rather we are now an external caller working directly with the values that an object exposes. That's why portrayal lets pattern matching depend on reader methods that get to decide how to expose data outwardly, while making a conscious effort to exclude private and protected readers. You're welcome to override `deconstruct` and `deconstruct_keys` in your class if you'd like to do something different.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/bench

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'portrayal'
+require 'benchmark/ips'
+
+class Address1
+  extend Portrayal
+
+  keyword :street
+  keyword :city
+  keyword :postal_code
+
+  def ==(other)
+    self.class.portrayal.attributes(self) ==
+      other.class.portrayal.attributes(other)
+  end
+end
+
+class Address2
+  extend Portrayal
+
+  keyword :street
+  keyword :city
+  keyword :postal_code
+end
+
+Address2.portrayal.module.module_eval <<-RUBY
+  def ==(o)
+    street == o.street && city == o.city && postal_code == o.postal_code
+  end
+RUBY
+
+class Address3
+  extend Portrayal
+
+  keyword :street
+  keyword :city
+  keyword :postal_code
+
+  def ==(o)
+    { street: street, city: city, postal_code: postal_code } ==
+      { street: o.street, city: o.city, postal_code: o.postal_code }
+  end
+end
+
+a1 = Address1.new(street: 'street', city: 'city', postal_code: 123)
+a2 = Address2.new(street: 'street', city: 'city', postal_code: 123)
+a3 = Address3.new(street: 'street', city: 'city', postal_code: 123)
+
+
+Benchmark.ips do |x|
+  x.report("equality-via-hash-construction") {
+    a1 == a1
+  }
+
+  x.report("equality-via-boolean-expression") {
+    a2 == a2
+  }
+
+  x.report("equality-via-hash-literal") {
+    a3 == a3
+  }
+
+  x.compare!
+end
+
+Benchmark.ips do |x|
+  x.report("hash of literal Hash") {
+    { foo: 'foo', bar: 'bar', baz: 'baz' }.hash
+  }
+
+  x.report("hash of literal Array") {
+    [ [:foo, 'foo'], [:bar, 'bar'], [:baz, 'baz'] ].hash
+  }
+
+  x.compare!
+end

data/bin/module

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'portrayal'
+
+class Address
+  extend Portrayal
+
+  keyword :street
+  keyword :city
+  keyword :postcode
+  keyword :country, default: nil
+end
+
+puts Address.portrayal.render_module_code

data/lib/portrayal/default.rb

@@ -1,13 +1,12 @@
-module Portrayal
-  class Default
-    attr_reader :value
+class Portrayal::Default
+  attr_reader :value
+  protected :value
 
-    def initialize(value)
-      @value = value
-      @callable = value.is_a?(Proc) && !value.lambda?
-    end
-
-    def call?; @callable end
-    def initialize_dup(src); super; @value = src.value.dup end
+  def initialize(value)
+    @value = value
+    @callable = value.is_a?(Proc) && !value.lambda?
   end
+
+  def call(obj); @callable ? obj.instance_exec(&value) : value end
+  def initialize_dup(src); @value = src.value.dup; super end
 end

data/lib/portrayal/schema.rb

@@ -1,79 +1,72 @@
 require 'portrayal/default'
 
-module Portrayal
-  class Schema
-    attr_reader :schema
-
-    DEFINITION_OF_OBJECT_ENHANCEMENTS = <<~RUBY.freeze
-      def eql?(other); self.class == other.class && self == other end
-      def hash; [self.class, self.class.portrayal.attributes(self)].hash end
-      def deconstruct; self.class.portrayal.attributes(self).values end
-
-      def deconstruct_keys(keys)
-        keys ||= self.class.portrayal.keywords
-        keys &= self.class.portrayal.keywords
-        Hash[keys.map { |k| [k, send(k)] }]
-      end
-
-      def ==(other)
-        return super unless other.class.is_a?(Portrayal)
-
-        self.class.portrayal.attributes(self) ==
-          self.class.portrayal.attributes(other)
-      end
-
-      def freeze
-        self.class.portrayal.attributes(self).values.each(&:freeze)
-        super
-      end
-
-      def initialize_dup(source)
-        self.class.portrayal.attributes(source).each do |key, value|
-          instance_variable_set("@\#{key}", value.dup)
-        end
-        super
-      end
-
-      def initialize_clone(source)
-        self.class.portrayal.attributes(source).each do |key, value|
-          instance_variable_set("@\#{key}", value.clone)
-        end
-        super
-      end
-    RUBY
-
-    def initialize; @schema = {}  end
-    def keywords;   @schema.keys  end
-    def [](name);   @schema[name] end
-
-    def attributes(object)
-      Hash[object.class.portrayal.keywords.map { |k| [k, object.send(k)] }]
-    end
-
-    def camelize(string); string.to_s.gsub(/(?:^|_+)([^_])/) { $1.upcase } end
+class Portrayal::Schema
+  attr_reader :schema, :module
+  NULL = Object.new.freeze
+
+  def initialize;       @schema = {}; @module = Module.new                end
+  def keywords;         @schema.keys                                      end
+  def attributes(obj);  Hash[keywords.map { |k| [k, obj.send(k)] }]       end
+  def camelize(string); string.to_s.gsub(/(?:^|_+)([^_])/) { $1.upcase }  end
+
+  def initialize_dup(src)
+    @schema = src.schema.transform_values(&:dup)
+    @module = src.module.dup
+    super
+  end
 
-    def add_keyword(name, default)
-      name = name.to_sym
-      @schema.delete(name) # Forcing keyword to be added at the end of the hash.
-      @schema[name] = default.equal?(NULL) ? nil : Default.new(default)
-    end
+  def add_keyword(name, default)
+    name = name.to_sym
+    @schema.delete(name) # Forcing keyword to be added at the end of the hash.
+    @schema[name] = default.equal?(NULL) ? nil : Portrayal::Default.new(default)
+    @module.module_eval(render_module_code)
+  end
 
-    def initialize_dup(other)
-      super; @schema = other.schema.transform_values(&:dup)
+  def render_module_code
+    args, inits, syms, hash, eqls, dups, clones, setters, freezes =
+      '', '', '', '', '', '', '', '', ''
+
+    @schema.each do |k, default|
+      args  << "#{k}:#{default && " self.class.portrayal.schema[:#{k}]"}, "
+      inits << "@#{k} = #{k}.is_a?(::Portrayal::Default) ? #{k}.(self) : #{k}; "
+      syms  << ":#{k}, "
+      hash  << "#{k}: @#{k}, "
+      eqls  << "@#{k} == other.instance_variable_get('@#{k}') && "
+      dups  << "@#{k} = src.instance_variable_get('@#{k}').dup; "
+      clones  << "@#{k} = src.instance_variable_get('@#{k}').clone; "
+      setters << ":#{k}=, "
+      freezes << "@#{k}.freeze; "
     end
 
-    def definition_of_initialize
-      init_args = @schema.map { |name, default|
-        "#{name}:#{default && " self.class.portrayal[:#{name}]"}"
-      }.join(', ')
-
-      init_assigns = @schema.keys.map { |name|
-        "@#{name} = #{name}.is_a?(::Portrayal::Default) ? " \
-          "(#{name}.call? ? instance_exec(&#{name}.value) : #{name}.value) : " \
-          "#{name}"
-      }.join('; ')
-
-      "def initialize(#{init_args}); #{init_assigns} end"
-    end
+    args.chomp!(', ')    # key1:, key2: self.class.portrayal.schema[:key2]
+    inits.chomp!('; ')   # Assignments in initialize
+    syms.chomp!(', ')    # :key1, :key2
+    hash.chomp!(', ')    # key1: @key1, key2: @key2
+    eqls.chomp!(' && ')  # @key1 == other.instance_variable_get('@key1') &&
+    dups.chomp!('; ')    # @key1 = src.instance_variable_get('@key1').dup;
+    clones.chomp!('; ')  # @key1 = src.instance_variable_get('@key1').clone;
+    setters.chomp!(', ') # :key1=, :key2=
+    freezes.chomp!('; ') # @key1.freeze; @key2.freeze
+
+    <<-RUBY
+attr_accessor #{syms}
+protected #{setters}
+def initialize(#{args}); #{inits} end
+def hash; [self.class, {#{hash}}].hash end
+def ==(other); self.class == other.class && #{eqls} end
+alias eql? ==
+def freeze; #{freezes}; super end
+def initialize_dup(src); #{dups}; super end
+def initialize_clone(src); #{clones}; super end
+def deconstruct
+  public_syms = [#{syms}].select { |s| self.class.public_method_defined?(s) }
+  public_syms.map { |s| public_send(s) }
+end
+def deconstruct_keys(keys)
+  filtered_keys = [#{syms}].select {|s| self.class.public_method_defined?(s) }
+  filtered_keys &= keys if Array === keys
+  Hash[filtered_keys.map { |k| [k, public_send(k)] }]
+end
+    RUBY
   end
 end

data/lib/portrayal/version.rb

@@ -1,3 +1,3 @@
 module Portrayal
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/portrayal.rb

@@ -2,32 +2,20 @@ require 'portrayal/version'
 require 'portrayal/schema'
 
 module Portrayal
-  NULL = :_portrayal_value_not_set
+  attr_reader :portrayal
+  def self.extended(c); c.instance_variable_set(:@portrayal, Schema.new) end
 
-  def keyword(name, default: NULL, define: nil, &block)
-    unless respond_to?(:portrayal)
-      class << self
-        attr_reader :portrayal
-        def inherited(base)
-          base.instance_variable_set('@portrayal', portrayal.dup)
-        end
-      end
-
-      @portrayal = Schema.new
-      class_eval(Schema::DEFINITION_OF_OBJECT_ENHANCEMENTS)
-    end
-
-    attr_accessor name
-    protected "#{name}="
+  def inherited(c)
+    c.instance_variable_set(:@portrayal, portrayal.dup)
+    c.include(c.portrayal.module)
+  end
 
+  def keyword(name, default: Schema::NULL, define: nil, &block)
+    include portrayal.module
     portrayal.add_keyword(name, default)
-    class_eval(portrayal.definition_of_initialize)
-
-    if block_given?
-      kw_class = Class.new(superclass) { extend Portrayal }
-      const_set(define || portrayal.camelize(name), kw_class).class_eval(&block)
-    end
-
+    return name unless block_given?
+    nested = Class.new(superclass) { extend ::Portrayal }
+    const_set(define || portrayal.camelize(name), nested).class_eval(&block)
     name
   end
 end

data/portrayal.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.12'
   spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'benchmark-ips', '~> 2.11'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portrayal
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Max Chernyak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-28 00:00:00.000000000 Z
+date: 2023-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.11'
 description: Inspired by dry-initializer and virtus, portrayal is a minimalist gem
   that takes a somewhat different approach to building struct-like classes. It steps
   away from types, coersion, and writer methods in favor of encouraging well-designed
@@ -71,8 +85,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/bench
 - bin/console
 - bin/loc
+- bin/module
 - bin/setup
 - lib/portrayal.rb
 - lib/portrayal/default.rb