portrayal 0.3.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 577a51dc874a79a5cb7aece4157c2d802005f3fa9c3daba4b807db522c7cd7ae
-  data.tar.gz: b30f1ea6a9438ba5b4574a68935602fce1dd0a447d15dce4227d0a67a10b2e87
+  metadata.gz: afdba4b2e460ce31fb430639e1270683d61d2b41bcb276a056e042ac8de8c61d
+  data.tar.gz: 39f66cc7e9224d04660d3cc1e1317f9c66752e2fd739eeb9068f10751275f9f8
 SHA512:
-  metadata.gz: a02d197cb3c56e88afcda74a58d5d7034ef4739de707380c05b7a1a76c95e8ae1c8aa9341fde97d8efa69e6b5fcc00df429b2ada5e1b18f5dc9c2c51cc73504a
-  data.tar.gz: 4c6f5e4d359551e7420dd4331192f857f8a4518ab679b8052f36c6854a34a100a97bd4af98358589dcd08144cff9ddda071f6b2bd4602dc7495d2fc8467c6994
+  metadata.gz: 894bcfa84622297c663f9fa88c4f829a8475fa092caff07d047768adef1a110e5726747f53a284e6d823c57ead388a14fc4e5d0bb68342c463a170a725fa9442
+  data.tar.gz: 19dc417df48b783a7847957fdc8899c143b0e92ac4aaef35f1b07342d7d02fbea1091d504d9d47318c7baee0cf538616209555903307f5e8aace2267fd777fce

data/.github/workflows/rspec.yml

@@ -1,24 +1,18 @@
 name: RSpec
-
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    branches: [ master ]
-
+on: [push, pull_request]
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        ruby: [ '2.4', '2.5', '2.6', '2.7' ]
+        ruby: [ '2.4', '2.5', '2.6', '2.7', '3.0' ]
 
     name: Ruby ${{ matrix.ruby }}
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-ruby@v1
+      - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-      - run: gem install bundler
-      - run: bundle install
+          bundler-cache: true
       - run: bundle exec rake

data/.gitignore

@@ -7,5 +7,8 @@
 /spec/reports/
 /tmp/
 
+# Recommended for gems
+/Gemfile.lock
+
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -2,11 +2,50 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+## 0.7.1 - 2021-03-22
+
+* Fix default procs' behavior when overriding keywords in subclasses. Portrayal relies on an ordered ruby hash to initialize keywords in the correct order. However, if overriding the same keyword in a subclass (by declaring it again), it didn't move keyword to the bottom of the hash, so this would happen:
+
+    ```ruby
+    class Person
+      extend Portrayal
+      keyword :email, default: nil
+    end
+
+    class Employee < Person
+      keyword :employee_id
+      keyword :email, default: proc { "#{employee_id}@example.com" }
+    end
+
+    employee = Employee.new(employee_id: '1234')
+    employee.email # => "@example.com"
+    ```
+
+    The email is broken because it relies on having employee_id declared before email, but email was already declared first in the superclass. This change fixes situations like this by re-adding the keyword to the bottom of the hash on every re-declaration.
+
+## 0.7.0 - 2020-12-13
+
+* **Breaking change:** Remove `optional` setting. To update find all `optional: true` and change to `default: nil` instead.
+
+* **Breaking change:** Move `self` of default procs to `initialize` context. Before this change, default procs used to be executed naively in class context. Now they can access other keyword readers and instance methods since their `self` is now coming from `initialize`. To update, look through your default procs and replace any reference to current class's methods such as `method_name` with `self.class.method_name`.
+
+## 0.6.0 - 2020-08-10
+
+* Return keyword name from `keyword`, allowing usage such as `private keyword :foo`. [[commit]](https://github.com/scottscheapflights/portrayal/commit/9e9db2cafc7eae14789c5b84f70efd18898ace76)
+
+## 0.5.0 - 2020-05-28
+
+* Add option `define` for overriding nested class name. [[commit]](https://github.com/scottscheapflights/portrayal/commit/665ad297fb71fcdf5f641c672a457ccbe29e4a49)
+
+## 0.4.0 - 2020-05-16
+
+* Portrayal schema is deep-duped to subclasses. [[commit]](https://github.com/scottscheapflights/portrayal/commit/f346483a379ce9fbdece72cde8b0844f2d22b1cd)
+
 ## 0.3.1 - 2020-05-11
 
-* Fix the issue introduced in 0.3.0 where `==` and `eql?` were always treating rhs as another portrayal class.
+* Fix the issue introduced in 0.3.0 where `==` and `eql?` were always treating rhs as another portrayal class. [[commit]](https://github.com/scottscheapflights/portrayal/commit/f6ec8f373c6582f7e8d8f872d289222e4a58f8f6)
 
-## 0.3.0 - 2020-05-09
+## 0.3.0 - 2020-05-09 (yanked)
 
 * No longer compare classes in `==`, use `eql?` for that. [[commit]](https://github.com/scottscheapflights/portrayal/commit/9c5a37e4fb91e35d23b22e208344452930452af7)
 * Define a protected writer for every keyword - useful when applying changes after `dup`/`clone`. [[commit]](https://github.com/scottscheapflights/portrayal/commit/1c0fa6c6357a09760dae39165e864238d231a08e)

data/README.md

@@ -1,4 +1,4 @@
-![RSpec](https://github.com/scottscheapflights/portrayal/workflows/RSpec/badge.svg?branch=master)
+![RSpec](https://github.com/scottscheapflights/portrayal/workflows/RSpec/badge.svg)
 
 # Portrayal
 
@@ -8,14 +8,14 @@ Inspired by:
   - Piotr Solnica's [virtus](https://github.com/solnic/virtus)
   - Everything [Michel Martens](https://github.com/soveran)
 
-Portrayal is a minimalist gem (~115 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 (~120 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
   extend Portrayal
 
   keyword :name
-  keyword :age, optional: true
+  keyword :age, default: nil
   keyword :favorite_fruit, default: 'feijoa'
 
   keyword :address do
@@ -172,7 +172,7 @@ class Address < ApplicationStruct
   keyword :street
   keyword :city
   keyword :postcode
-  keyword :country, optional: true
+  keyword :country, default: nil
 end
 ```
 
@@ -198,6 +198,115 @@ Any other value works as normal.
 keyword :foo, default: 4
 ```
 
+#### Default procs
+
+Default procs are executed as though they were called in your class's `initialize`, so they have access to other keywords and instance methods.
+
+```ruby
+keyword :name
+keyword :greeting, default: proc { "Hello, #{name}" }
+```
+
+Defaults can also use results of other defaults.
+
+```ruby
+keyword :four,  default: proc { 2 + 2 }
+keyword :eight, default: proc { four * 2 }
+```
+
+Or instance methods of the class.
+
+```ruby
+keyword :id, default: proc { generate_id }
+
+private
+
+def generate_id
+  SecureRandom.alphanumeric
+end
+```
+
+Note: The order in which you declare keywords matters when specifying defaults that depend on other keywords. This will not have the desired effect:
+
+```ruby
+keyword :greeting, default: proc { "Hello, #{name}" }
+keyword :name
+```
+
+### Nested Classes
+
+When you pass a block to a keyword, it creates a nested class named after camelized keyword name.
+
+```ruby
+class Person
+  extend Portrayal
+
+  keyword :address do
+    keyword :street
+  end
+end
+```
+
+The above block created class `Person::Address`.
+
+If you want to change the name of the created class, use the option `define`.
+
+```ruby
+class Person
+  extend Portrayal
+
+  keyword :visited_countries, define: 'Country' do
+    keyword :name
+  end
+end
+```
+
+This defines `Person::Country`, while the accessor remains `visited_countries`.
+
+### Subclassing
+
+Portrayal supports subclassing.
+
+```ruby
+class Person
+  extend Portrayal
+  
+  class << self
+    def from_contact(contact)
+      new name:    contact.full_name,
+          address: contact.address.to_s,
+          email:   contact.email
+    end
+  end
+  
+  keyword :name
+  keyword :address
+  keyword :email, default: nil
+end
+```
+
+```ruby
+class Employee < Person
+  keyword :employee_id
+  keyword :email, default: proc { "#{employee_id}@example.com" }
+end
+```
+
+Now when you call `Employee.new` it will accept keywords of both superclass and subclass. You can also see how `email`'s default is overridden in the subclass.
+
+However, if you try calling `Employee.from_contact(contact)` it will error out, because that constructor doesn't set an `employee_id` required in the subclass. You can remedy that with a small change.
+
+```ruby
+    def from_contact(contact, **kwargs)
+      new name:    contact.full_name,
+          address: contact.address.to_s,
+          email:   contact.email,
+          **kwargs
+    end
+```
+
+If you add `**kwargs` to `Person.from_contact` and pass them through to new, then you are now able to call `Employee.from_contact(contact, employee_id: 'some_id')`
+
 ### Schema
 
 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.
@@ -224,7 +333,7 @@ Address.portrayal.attributes(address) # => {street: '34th st', city: 'NYC', post
 Get everything portrayal knows about your keywords in one hash.
 
 ```ruby
-Address.portrayal.schema # => {:street=>{:optional=>false, :default=>nil}, :city=>{:optional=>false, :default=>nil}, :postcode=>{:optional=>false, :default=>nil}, :country=>{:optional=>true, :default=>[:return, nil]}}
+Address.portrayal.schema # => {:street=>nil, :city=>nil, :postcode=>nil, :country=><Portrayal::Default @value=nil @callable=false>}
 ```
 
 ## Philosophy
@@ -258,7 +367,7 @@ class Address < ApplicationStruct
   keyword :street
   keyword :city
   keyword :postcode
-  keyword :country, optional: true
+  keyword :country, default: nil
 end
 ```
 
@@ -301,7 +410,7 @@ class Address < ApplicationStruct
   keyword :street
   keyword :city
   keyword :postcode
-  keyword :country, optional: true
+  keyword :country, default: nil
 end
 ```
 
@@ -330,4 +439,4 @@ The gem is available as open source under the terms of the [Apache License Versi
 
 ## Code of Conduct
 
-Everyone interacting in the Portrayal project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/scottscheapflights/portrayal/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Portrayal project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/scottscheapflights/portrayal/blob/main/CODE_OF_CONDUCT.md).

data/lib/portrayal.rb

@@ -4,23 +4,30 @@ require 'portrayal/schema'
 module Portrayal
   NULL = :_portrayal_value_not_set
 
-  def keyword(name, optional: NULL, default: NULL, &block)
+  def keyword(name, default: NULL, define: nil, &block)
     unless respond_to?(:portrayal)
-      class << self; attr_reader :portrayal end
+      class << self
+        attr_reader :portrayal
+        def inherited(base)
+          base.instance_variable_set('@portrayal', portrayal.dup)
+        end
+      end
+
       @portrayal = Schema.new
-      class_eval(portrayal.definition_of_object_enhancements)
+      class_eval(Schema::DEFINITION_OF_OBJECT_ENHANCEMENTS)
     end
 
     attr_accessor name
     protected "#{name}="
 
-    portrayal.add_keyword(name, optional, default)
+    portrayal.add_keyword(name, default)
     class_eval(portrayal.definition_of_initialize)
 
     if block_given?
-      keyword_class = Class.new(superclass) { extend Portrayal }
-      keyword_class.class_eval(&block)
-      const_set(portrayal.camelcase(name), keyword_class)
+      kw_class = Class.new(superclass) { extend Portrayal }
+      const_set(define || portrayal.camelize(name), kw_class).class_eval(&block)
     end
+
+    name
   end
 end

data/lib/portrayal/default.rb

@@ -0,0 +1,13 @@
+module Portrayal
+  class Default
+    attr_reader :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
+  end
+end

data/lib/portrayal/schema.rb

@@ -1,56 +1,10 @@
+require 'portrayal/default'
+
 module Portrayal
   class Schema
     attr_reader :schema
 
-    def initialize
-      @schema = {}
-      @equality_defined = false
-    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 add_keyword(name, optional, default)
-      optional, default =
-        case [optional == NULL, default == NULL]
-        when [true,  true];  [false, nil]
-        when [false, true];  [optional, optional ? [:return, nil] : nil]
-        when [true,  false]; [true, [default_strategy(default), default]]
-        else; [optional, optional ? [default_strategy(default), default] : nil]
-        end
-
-      @schema[name.to_sym] = { optional: optional, default: default }
-    end
-
-    def camelcase(string)
-      string.to_s.gsub(/(?:^|_+)([^_])/) { $1.upcase }
-    end
-
-    def get_default(name)
-      action, value = @schema[name][:default]
-      action == :call ? value.call : value
-    end
-
-    def default_strategy(value)
-      (value.is_a?(Proc) && !value.lambda?) ? :call : :return
-    end
-
-    def definition_of_initialize
-      init_args = @schema.map { |name, config|
-        config[:optional] ?
-          "#{name}: self.class.portrayal.get_default(:#{name})" : "#{name}:"
-      }.join(',')
-
-      init_assigns = @schema.keys.map { |name| "@#{name} = #{name}" }.join('; ')
-      "def initialize(#{init_args}); #{init_assigns} end"
-    end
-
-    def definition_of_object_enhancements
-      <<-RUBY
+    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
 
@@ -68,18 +22,51 @@ module Portrayal
 
       def initialize_dup(source)
         self.class.portrayal.attributes(source).each do |key, value|
-          instance_variable_set('@' + key.to_s, value.dup)
+          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.to_s, value.clone)
+          instance_variable_set("@\#{key}", value.clone)
         end
         super
       end
-      RUBY
+    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
+
+    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 initialize_dup(other)
+      super; @schema = other.schema.transform_values(&:dup)
+    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
   end
 end

data/lib/portrayal/version.rb

@@ -1,3 +1,3 @@
 module Portrayal
-  VERSION = "0.3.1"
+  VERSION = '0.7.1'
 end

data/portrayal.gemspec

@@ -1,6 +1,4 @@
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'portrayal/version'
+require_relative 'lib/portrayal/version'
 
 Gem::Specification.new do |spec|
   spec.name    = 'portrayal'
@@ -13,6 +11,11 @@ Gem::Specification.new do |spec|
   spec.homepage    = 'https://github.com/scottscheapflights/portrayal'
   spec.license     = 'Apache-2.0'
 
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = 'https://github.com/scottscheapflights/portrayal/blob/main/CHANGELOG.md'
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
   spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^spec/}) }
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portrayal
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Maxim Chernyak
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-11 00:00:00.000000000 Z
+date: 2021-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -82,21 +82,24 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
 - lib/portrayal.rb
+- lib/portrayal/default.rb
 - lib/portrayal/schema.rb
 - lib/portrayal/version.rb
 - portrayal.gemspec
 homepage: https://github.com/scottscheapflights/portrayal
 licenses:
 - Apache-2.0
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/scottscheapflights/portrayal
+  source_code_uri: https://github.com/scottscheapflights/portrayal
+  changelog_uri: https://github.com/scottscheapflights/portrayal/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -104,7 +107,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -112,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A minimal builder for struct-like classes
 test_files: []

data/Gemfile.lock

@@ -1,41 +0,0 @@
-PATH
-  remote: .
-  specs:
-    portrayal (0.3.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    coderay (1.1.2)
-    diff-lcs (1.3)
-    method_source (1.0.0)
-    pry (0.13.1)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-    rake (13.0.1)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.1)
-  portrayal!
-  pry (~> 0.13)
-  rake (~> 13.0)
-  rspec (~> 3.9)
-
-BUNDLED WITH
-   2.1.4