opt_struct 0.9.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54518e9eca18b69463f611c221bd896a94cbd5293bd804a23319b0dd7441573d
-  data.tar.gz: 36584d846f30ebf6517d541a31668678a1a8dbd9025a4d9bef032eea2372c50f
+  metadata.gz: 824012017028badde180165fa6280f398cbf138f09f8600319625e92fbaf67ed
+  data.tar.gz: 2c612d601c220eb88aaaf656917cd06d0edc7a87b70f84c67cda6b17e6cbbe94
 SHA512:
-  metadata.gz: ff0a53a81253354676e0578028d775785eda00d30c7201b3f36414009b26ad551893f789dc9aabf82ec212b7abd5544432a045cfe4f973e59136ffeec1258867
-  data.tar.gz: fbbd6f407b889e2cca7b6b9d5ce891cdad58bb73db10a1e437515d74d1221af442da0cbb7715f8f20db05ea0799035951e094d9ad5bece86775f7c05fdd17c1e
+  metadata.gz: f7cf9e8c1d9e0b9c40a2f08c1f32784fa61b38a14edac39f4bef3f887845827a57f9b813e2f8df6dbb0436734c8f5895d7b25f45adb2bff3fa82eb7e87766fee
+  data.tar.gz: aea1084efba08f15951e7d8629c1a8211d66bddd720dfee19a1c1ec5a8eb52d6c73f047ac4ae8c5b7a969912113b0093249f48f991415ca932170d64e69b956d

data/README.md

@@ -1,4 +1,7 @@
-# The Opt Struct
+# The Opt Struct [![Build Status][travis-image]][travis-link]
+
+[travis-image]: https://travis-ci.org/carlzulauf/opt_struct.svg?branch=master
+[travis-link]: http://travis-ci.org/carlzulauf/opt_struct
 
 A struct around a hash. Great for encapsulating actions with complex configuration, like interactor/action classes.
 
@@ -6,137 +9,342 @@ A struct around a hash. Great for encapsulating actions with complex configurati
 gem "opt_struct"
 ```
 
-## Example 1
+# Examples
 
-Can work mostly like a regular struct, while accepting options
+## Creating an OptStruct
 
 ```ruby
-MyClass = OptStruct.new(:foo, :bar)
+class User < OptStruct.new
+  required :email, :name
+  option :role, default: "member"
+  
+  def formatted_email
+    %{"#{name}" <#{email}>}
+  end
+end
+```
 
-MyClass.new
-# => argument error
+## Using an OptStruct
 
-MyClass.new "foo", "bar"
-# => #<MyClass>
+```ruby
+user = User.new(email: "admin@user.com", name: "Ms. Admin", role: "admin")
+
+# option accessors are available
+user.name
+# => "Ms. Admin"
+user.formatted_email
+# => "\"Ms. Admin\" <admin@user.com>"
+user.name = "Amber Admin"
+# => "Amber Admin"
+
+# values are also accessible through the `#options` Hash
+user.options
+# => {:email=>"admin@user.com", :name=>"Amber Admin", :role=>"admin"}
+user.options.fetch(:role)
+# => "admin"
+```
 
-MyClass.new foo: "foo", bar: "bar"
-# => #<MyClass>
+# Documentation
 
-i = MyClass.new "foo", "bar", yin: "yang"
-i.options
-# => {yin: "yang"}
-i.fetch(:yin)
-# => "yang"
-```
+## Use As Inheritable Class
+
+`OptStruct.new` returns an instance of `Class` that can be inherited or initialized directly.
 
-## Example 2
+The following are functionally equivalent
 
-Passing a hash promotes the keys (`:foo` below) to an `option` giving it getter/setter methods on the class. The value becomes the default. This is equivalent and can be combined with using the `option` macro.
+```ruby
+class User < OptStruct.new
+  required :email
+  option :name
+end
+```
+
+```ruby
+User = OptStruct.new do
+  required :email
+  option :name
+end
+```
 
-If an option is required it needs to be called out as such using `required`.
+`OptStruct` classes can safely have descendants with their own isolated options.
 
 ```ruby
-class MyClass < OptStruct.new(foo: "bar")
-  required :yin # equivalent to: `option :yin, required: true`
-  option :bar, default: "foo"
+class AdminUser < User
+  required :token
 end
 
-MyClass.new
-# => missing keyword argument :yin
+User.new(email: "regular@user.com")
+# => #<User:0x0... @options={:email=>"regular@user.com"}>
+
+AdminUser.new(email: "admin@user.com")
+# ArgumentError: missing required keywords: [:token]
 
-i = MyClass.new yin: "yang"
-# => #<MyClass>
-i.foo
-# => "bar"
-i.bar
-# => "foo"
-i.foo = "foo"
-i.options
-# => {foo: "foo", bar: "foo", yin: "yang"}
+AdminUser.new(email: "admin@user.com", token: "a2236843f0227af2")
+# => #<AdminUser:0x0... @options={:email=>"admin@user.com", :token=>"..."}>
 ```
 
-## Example 3
+## Use As Mixin Module
 
-Works as a plain old mixin as well.
+`OptStruct.build` returns an instance of `Module` that can be included into a class or another module.
+
+The following are functionally equivalent
 
 ```ruby
-class MyClass
-  include OptStruct
-  required :foo
+module Visitable
+  include OptStruct.build
+  options :expected_at, :arrived_at, :departed_at
+end
+
+class AuditLog
+  include Visitable
 end
+```
 
-MyClass.new
-# => missing keyword argument :foo
+```ruby
+Visitable = OptStruct.build { options :expected_at, :arrived_at, :departed_at }
 
-MyClass.new(foo: "bar").foo
-# => "bar"
+class AuditLog
+  include Visitable
+end
 ```
 
-## Example 4
+These examples result in an `AuditLog` class with identical behavior, but no explicit `Visitable` module.
 
-Options passed to `new` can be passed to `build` when used in module form.
+```ruby
+class AuditLog
+  include OptStruct.build
+  options :expected_at, :arrived_at, :departed_at
+end
+```
 
 ```ruby
-class MyClass
-  include OptStruct.build(:foo, bar: nil)
+class AuditLog
+  include(OptStruct.build do
+    options :expected_at, :arrived_at, :departed_at
+  end)
 end
+```
+
+## Optional Arguments
+
+Optional arguments are simply accessor methods for values expected to be in the `#options` Hash. Optional arguments can be defined in multiple ways.
 
-MyClass.new
-# => argument error
+All of the examples in this section are functionally equivalent.
 
-i = MyClass.new("something", bar: "foo")
-[i.foo, i.bar]
-# => ["something", "foo"]
+```ruby
+class User < OptStruct.new
+  option :email
+  option :role, default: "member"
+end
 ```
 
-## Example 5
+```ruby
+class User < OptStruct.new
+  options :email, role: "member"
+end
+```
+
+```ruby
+class User < OptStruct.new
+  options email: nil, role: "member"
+end
+```
 
-Both `build` and `new` accept a block.
+Passing a Hash to `.new` or `.build` is equivalent to passing the same hash to `options`
 
 ```ruby
-PersonClass = OptStruct.new do
-  required :first_name
-  option :last_name
+User = OptStruct.new(email: nil, role: "member")
+```
 
-  def name
-    [first_name, last_name].compact.join(" ")
-  end
+Default blocks can also be used and are late evaluated on the each struct instance.
+
+```ruby
+class User < OptStruct.new
+  option :email, default: -> { nil }
+  option :role, -> { "member" }
 end
+```
 
-t = PersonClass.new(first_name: "Trish")
-# => #<PersonClass>
-t.name
-# => "Trish"
-t.last_name = "Smith"
-t.name
-# => "Trish Smith"
+```ruby
+class User < OptStruct.new
+  options :email, role: -> { "member" }
+end
+```
 
-CarModule = OptStruct.build do
-  required :make, :model
-  options year: -> { Date.today.year }, transmission: :default_transmission
+```ruby
+class User < OptStruct.new
+  option :email, nil
+  option :role, -> { default_role }
+  
+  private
+  
+  def default_role
+    "member"
+  end
+end
+```
 
-  def default_transmission
-    "Automatic"
+Default symbols are treated as method calls if the struct `#respond_to?` the method.
+
+```ruby
+class User < OptStruct.new
+  options :email, :role => :default_role
+  
+  def default_role
+    "member"
   end
+end
+```
+
+## Required Arguments
+
+Required arguments are just like optional arguments, except they are also added to the `.required_keys` collection, which is checked when an OptStruct is initialized. If the `#options` Hash does not contain all `.required_keys` then an `ArgumentError` is raised.
+
+The following examples are functionally equivalent.
+
+```ruby
+class Student < OptStruct.new
+  required :name
+end
+```
+
+```ruby
+class Student < OptStruct.new
+  option :name, required: true
+end
+```
+
+```ruby
+class Student < OptStruct.new
+  option :name
+  required_keys << :name
+end
+```
+
+### Expected Arguments
+
+OptStructs can accept non-keyword arguments if the struct knows to expect them.
+
+For code like this to work...
+
+```ruby
+user = User.new("admin@user.com", "admin")
+user.email # => "admin@user.com"
+user.role  # => "admin"
+```
+
+... the OptStruct needs to have some `.expected_arguments`.
+
+The following `User` class examples are functionally equivalent and allow the code above to function.
+
+```ruby
+User = OptStruct.new(:email, :role)
+```
+
+```ruby
+class User < OptStruct.new(:email)
+  expect_argument :role
+end
+```
+
+```ruby
+class User
+  include OptStruct.build(:email, :role)
+end
+```
+
+```ruby
+class User
+  include OptStruct.build
+  expect_arguments :email, :role
+end
+```
 
+```ruby
+class User < OptStruct.new(:email)
+  expected_arguments << :role
+end
+```
+
+Expected arguments are similar to required arguments, except they are in `.expected_arguments` collection, which is checked when an OptStruct is initialized.
+
+Expected arguments can also be supplied using keywords. An `ArgumentError` is only raised if the expected argument is not in the list of arguments passed to `OptStruct#new` **and** the argument is not present in the `#options` Hash.
+
+The following examples will initialize any of the `User` class examples above without error.
+
+```ruby
+User.new(email: "example@user.com", role: "member")
+User.new("example@user.com", role: "member")
+User.new(role: "member", email: "example@user.com")
+```
+
+## The `#options` Hash
+
+All OptStruct arguments are read from and stored in a single `Hash` instance. This Hash can be accessed directly using the `options` method.
+
+```ruby
+Person = OptStruct.new(:name)
+Person.new(name: "John", age: 32).options
+# => {:name=>"John", :age=>32}
+```
+
+Feel free to write your own accessor methods for things like dependent options or other complex/private behavior.
+
+```ruby
+class Person < OptStruct.new
+  option :given_name
+  option :family_name
+  
   def name
-    [year, make, model].compact.join(" ")
+    options.fetch(:name) { "#{given_name} #{family_name}" }
   end
 end
+```
+
+## On Initialization
 
-class CarClass
-  include CarModule
+All of the following examples are functionally equivalent.
+
+OptStruct classes are initialized in an `initialize` method (in `OptStruct::InstanceMethods`) like most classes. Also, like most classes, you can override `initialize` as long as you remember to call `super` properly to retain `OptStruct` functionality.
+
+```ruby
+class UserReportBuilder < OptStruct.new(:user)
+  attr_reader :report
+  
+  def initialize(*)
+    super
+    @report = []
+  end
 end
+```
 
-c = CarClass.new(make: "Infiniti", model: "G37", year: 2012)
-c.name
-# => "2012 Infinit G37"
+`OptStruct` also provides initialization callbacks to make hooking into and customizing the initialization of OptStruct classes easier and require less code.
 
-c = CarClass.new(model: "WRX", make: "Subaru", year: nil)
-c.name
-# => "Subaru WRX"
+```ruby
+class UserReportBuilder < OptStruct.new(:user)
+  attr_reader :report
+  init { @report = [] }
+end
+```
 
-c = CarClass.new(model: "BRZ", make: "Subaru")
-c.name
-# => "2017 Subaru BRZ"
+```ruby
+class UserReportBuilder < OptStruct.new(:user)
+  attr_reader :report
+  
+  around_init do |instance|
+    instance.call
+    @report = []
+  end
+end
 ```
+
+Available callbacks
+
+* `around_init`
+* `before_init`
+* `init`
+* `after_init`
+
+## Inheritance, Expanded
+
+See `spec/inheritance_spec.rb` for examples of just how crazy you can get.

data/lib/opt_struct.rb

@@ -3,10 +3,11 @@ require "opt_struct/module_methods"
 require "opt_struct/instance_methods"
 
 module OptStruct
+  RESERVED_WORDS = %i(class defaults options fetch check_required_args check_required_keys).freeze
 
-  def self._inject_struct(target, source, args = [], defaults = {}, &callback)
+  def self._inject_struct(target, source, args = [], **defaults, &callback)
     structs = Array(source.instance_variable_get(:@_opt_structs)).dup
-    if args.any? || defaults.any? || callback
+    if args.any? || defaults.any? || block_given?
       structs << [args, defaults, callback]
     end
     target.instance_variable_set(:@_opt_structs, structs)
@@ -18,7 +19,7 @@ module OptStruct
       end
       structs.each do |s_args, s_defaults, s_callback|
         target.expect_arguments *s_args if s_args.any?
-        target.options s_defaults       if s_defaults.any?
+        target.options **s_defaults     if s_defaults.any?
         target.class_exec(&s_callback)  if s_callback
       end
     else
@@ -38,10 +39,10 @@ module OptStruct
   end
 
   def self.new(*args, **defaults, &callback)
-    _inject_struct(Class.new, self, args.map(&:to_sym), defaults, &callback)
+    _inject_struct(Class.new, self, args.map(&:to_sym), **defaults, &callback)
   end
 
   def self.build(*args, **defaults, &callback)
-    _inject_struct(Module.new, self, args.map(&:to_sym), defaults, &callback)
+    _inject_struct(Module.new, self, args.map(&:to_sym), **defaults, &callback)
   end
 end

data/lib/opt_struct/class_methods.rb

@@ -1,75 +1,81 @@
 module OptStruct
   module ClassMethods
     def inherited(subclass)
-      instance_variables.each do |v|
-        ivar = instance_variable_get(v)
-        subclass.send(:instance_variable_set, v, ivar.dup) if ivar
+      opt_struct_class_constants.each do |c|
+        subclass.const_set(c, const_get(c)) if const_defined?(c)
       end
     end
 
+    # overwritten if `required` is called
     def required_keys
-      @required_keys ||= []
+      [].freeze
     end
 
-    def required(*keys)
-      required_keys.concat keys
-      option_accessor *keys
+    def required(*keys, **options)
+      add_required_keys *keys
+      option_accessor *keys, **options
     end
 
-    def option_reader(*keys)
-      check_reserved_words(keys)
-
+    def option_reader(*keys, **options)
       keys.each do |key|
-        define_method(key) do
-          if options.key?(key)
-            options[key]
-          elsif defaults.key?(key)
-            options[key] = read_default_value(key)
+        class_eval <<~RUBY
+          #{options[:private] ? "private" : ""} def #{key}
+            options[:#{key}]
           end
-        end
+        RUBY
       end
     end
 
-    def option_writer(*keys)
-      check_reserved_words(keys)
-
+    def option_writer(*keys, **options)
       keys.each do |key|
-        define_method("#{key}=") { |value| options[key] = value }
+        class_eval <<~RUBY
+          #{options[:private] ? "private" : ""} def #{key}=(value)
+            options[:#{key}] = value
+          end
+        RUBY
       end
     end
 
-    def option_accessor(*keys)
-      option_reader *keys
-      option_writer *keys
+    def option_accessor(*keys, **options)
+      check_reserved_words(keys)
+      option_reader *keys, **options
+      option_writer *keys, **options
     end
 
-    def option(key, default = nil, **options)
+    def option(key, default = nil, required: false, **options)
       default = options[:default] if options.key?(:default)
-      defaults[key] = default
-      required_keys << key if options[:required]
-      option_accessor key
+      add_defaults key => default
+      add_required_keys key if required
+      option_accessor key, **options
     end
 
     def options(*keys, **keys_defaults)
       option_accessor *keys if keys.any?
       if keys_defaults.any?
-        defaults.merge!(keys_defaults)
+        add_defaults keys_defaults
         option_accessor *(keys_defaults.keys - expected_arguments)
       end
     end
 
     def defaults
-      @defaults ||= {}
+      const_defined?(:OPT_DEFAULTS) ? const_get(:OPT_DEFAULTS) : {}
     end
 
-    def expect_arguments(*arguments)
-      required(*arguments)
-      expected_arguments.concat(arguments)
+    # overwritten if `expect_arguments` is called
+    def expected_arguments
+      [].freeze
     end
 
-    def expected_arguments
-      @expected_arguments ||= []
+    def expect_arguments(*arguments)
+      required(*arguments)
+      combined = expected_arguments + arguments
+      class_eval <<~EVAL
+        def self.expected_arguments
+          #{combined.inspect}.freeze
+        end
+      EVAL
     end
+    alias_method :expect_argument, :expect_arguments
 
     def init(meth = nil, &blk)
       add_callback(:init, meth || blk)
@@ -84,23 +90,60 @@ module OptStruct
       add_callback(:around_init, meth || blk)
     end
 
-    def add_callback(name, callback)
-      @_callbacks ||= {}
-      @_callbacks[name] ||= []
-      @_callbacks[name] << callback
+    def all_callbacks
+      const_defined?(:OPT_CALLBACKS) ? const_get(:OPT_CALLBACKS) : {}.freeze
     end
 
-    def all_callbacks
-      @_callbacks
+    def shareable?
+      const_defined?(:SHAREABLE) && const_get(:SHAREABLE)
+    end
+
+    def shareable!
+      return if shareable?
+      const_set(:SHAREABLE, true)
     end
 
     private
 
-    RESERVED_WORDS = %i(class defaults options fetch check_required_args check_required_keys)
+    def share(value)
+      return value unless shareable?
+      defined?(Ractor) ? Ractor.make_shareable(value) : value
+    end
+
+    def add_required_keys(*keys)
+      combined = required_keys + keys
+      class_eval <<~RUBY
+        def self.required_keys
+          #{combined.inspect}.freeze
+        end
+      RUBY
+    end
+
+    def add_defaults(defaults_to_add)
+      freezer = defaults.dup
+      defaults_to_add.each { |k, v| freezer[k] = share(v) }
+      remove_const(:OPT_DEFAULTS) if const_defined?(:OPT_DEFAULTS)
+      const_set(:OPT_DEFAULTS, freezer.freeze)
+    end
+
+    def add_callback(name, callback)
+      if const_defined?(:OPT_CALLBACKS)
+        callbacks_for_name = (all_callbacks[name] || []) + [callback]
+        callbacks_hash = all_callbacks.merge(name => callbacks_for_name).freeze
+        remove_const(:OPT_CALLBACKS)
+        const_set(:OPT_CALLBACKS, callbacks_hash)
+      else
+        const_set(:OPT_CALLBACKS, { name => [ callback ] })
+      end
+    end
+
+    def opt_struct_class_constants
+      [:OPT_DEFAULTS, :OPT_CALLBACKS]
+    end
 
     def check_reserved_words(words)
       Array(words).each do |word|
-        if RESERVED_WORDS.member?(word)
+        if OptStruct::RESERVED_WORDS.member?(word)
           raise ArgumentError, "Use of reserved word is not permitted: #{word.inspect}"
         end
       end

data/lib/opt_struct/instance_methods.rb

@@ -4,6 +4,7 @@ module OptStruct
       with_init_callbacks do
         @options = options
         assign_arguments(arguments)
+        assign_defaults
         check_required_keys
       end
     end
@@ -24,23 +25,21 @@ module OptStruct
         raise ArgumentError, "missing required keywords: #{missing.inspect}"
       end
     end
-    
+
+    def assign_defaults
+      defaults.each do |key, default_value|
+        next if options.key?(key) # || default_value.nil?
+        options[key] = read_default_value(default_value)
+      end
+    end
+
     def assign_arguments(args)
       self.class.expected_arguments.map.with_index do |key, i|
-        if args.length > i
-          options[key] = args[i]
-        elsif !options.key?(key)
-          if defaults.key?(key)
-            options[key] = read_default_value(key)
-          else
-            raise ArgumentError, "missing required argument: #{key}"
-          end
-        end
+        options[key] = args[i] if args.length > i
       end
     end
-    
-    def read_default_value(key)
-      default = defaults[key]
+
+    def read_default_value(default)
       case default
       when Proc
         instance_exec(&default)

data/lib/opt_struct/module_methods.rb

@@ -22,8 +22,8 @@ module OptStruct
       options
       expect_arguments
     ).each do |class_method|
-      define_method(class_method) do |*args|
-        @_opt_structs << [[], {}, -> { send(class_method, *args) }]
+      define_method(class_method) do |*args, **options|
+        @_opt_structs << [[], {}, -> { send(class_method, *args, **options) }]
       end
     end
   end

data/lib/opt_struct/version.rb

@@ -1,3 +1,3 @@
 module OptStruct
-  VERSION = "0.9.0"
+  VERSION = "1.2.0"
 end

data/opt_struct.gemspec

@@ -16,8 +16,4 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split("\n").grep(/^lib/)
   spec.files        += %w(README.md opt_struct.gemspec)
   spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 1.14"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,57 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: opt_struct
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Carl Zulauf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-05 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
+date: 2021-03-30 00:00:00.000000000 Z
+dependencies: []
 description: Struct with support for keyword params and mixin support
 email:
 - carl@linkleaf.com
@@ -85,7 +43,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: The Option Struct