opt_struct 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54518e9eca18b69463f611c221bd896a94cbd5293bd804a23319b0dd7441573d
-  data.tar.gz: 36584d846f30ebf6517d541a31668678a1a8dbd9025a4d9bef032eea2372c50f
+  metadata.gz: 3a55fe71d013b67b97989363367748f78f0cf50ba890aeafdd69183b11c9bcac
+  data.tar.gz: ee9465e01cac7b9978a3860cbabf0e26322246b7eda546b01a23ff6afb9715bf
 SHA512:
-  metadata.gz: ff0a53a81253354676e0578028d775785eda00d30c7201b3f36414009b26ad551893f789dc9aabf82ec212b7abd5544432a045cfe4f973e59136ffeec1258867
-  data.tar.gz: fbbd6f407b889e2cca7b6b9d5ce891cdad58bb73db10a1e437515d74d1221af442da0cbb7715f8f20db05ea0799035951e094d9ad5bece86775f7c05fdd17c1e
+  metadata.gz: d688e9d507c70fcc588aff5a6b9c7109eff834a7f121f0508796758b29e4c86d93c134c6e43396eca023fadc05113ca79ddae40087f20e049445c4d4343a7335
+  data.tar.gz: 21a4f2a0a46034a18c9973596ff0f4f569d853e02f4c4b98bb3331368baee5af2b4a8718ace0a42b21c6375168cb1b6f9eabd2dff045f09f5aeed681600c69f5

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 example results 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/class_methods.rb

@@ -17,8 +17,6 @@ module OptStruct
     end
 
     def option_reader(*keys)
-      check_reserved_words(keys)
-
       keys.each do |key|
         define_method(key) do
           if options.key?(key)
@@ -31,14 +29,13 @@ module OptStruct
     end
 
     def option_writer(*keys)
-      check_reserved_words(keys)
-
       keys.each do |key|
         define_method("#{key}=") { |value| options[key] = value }
       end
     end
 
     def option_accessor(*keys)
+      check_reserved_words(keys)
       option_reader *keys
       option_writer *keys
     end
@@ -66,6 +63,7 @@ module OptStruct
       required(*arguments)
       expected_arguments.concat(arguments)
     end
+    alias_method :expect_argument, :expect_arguments
 
     def expected_arguments
       @expected_arguments ||= []

data/lib/opt_struct/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opt_struct
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Carl Zulauf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-05 00:00:00.000000000 Z
+date: 2019-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler