toritori 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47da200bc6b1c00517984ac052c3f3c1f3eab8dcfb9444158a893fb3e254bef4
-  data.tar.gz: 11da3242909586815d5c564c9ab80b04ccdd66b0cc02b96f61d416758c265c3f
+  metadata.gz: 025e6e1599389ad3a3a99e88695e7c02ed188d39238fe1abb5e9b54ca8e5fba0
+  data.tar.gz: a9dbf6f15624dd24fed3862e8fc81180aa59fa19c115382611d76e176dc59d3a
 SHA512:
-  metadata.gz: 4887c90e93f2a13c8942b6b7028f957dead740214ebdadc4717f71ef5005a7dd672c3559b9523bc52e4e741c94cfba637ec4b27215eb31c1bf003a6a027130fd
-  data.tar.gz: cf38a85c4d6efd4989f49740dfeb373780325b88007d34bbb18841b7efb6987c924d80516229cf6c17a389471ca772b1eafe26fad792c752b31eda65e68a41bc
+  metadata.gz: 91905f1f599cd3a3383491dbb810c6c0d96580b67c8b552ed56b1acf29bda2bd88a83e1694197b1c31431bb267a2d04a7cad657e4ca7dc00f370f6073f4e5465
+  data.tar.gz: f202f003ffef55921d92bfd04d90fda51c63e90ff959d0b38c365a1c761e3f4c2ddf99e17aa89abce0ec8ca5a01b69d050bf90715bf53f7278f2ecf3470e90b6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    toritori (0.2.0)
+    toritori (0.2.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -2,6 +2,7 @@
 
 [![Maintainability](https://api.codeclimate.com/v1/badges/4e5138d5018b81671692/maintainability)](https://codeclimate.com/github/andriy-baran/toritori/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/4e5138d5018b81671692/test_coverage)](https://codeclimate.com/github/andriy-baran/toritori/test_coverage)
+[![Gem Version](https://badge.fury.io/rb/toritori.svg)](https://badge.fury.io/rb/toritori)
 
 Simple tool to work with Abstract Factories.
 It provides the DSL for defining a set factories and produce objects.
@@ -22,118 +23,162 @@ Or install it yourself as:
 
     $ gem install toritori
 
-## Usage
-
-### Basics
-Add the module to the class
+## Basic usage
+First, add module to target class and define factory method
 ```ruby
 require 'toritori'
 
 class MyAbstractFactory
   include Toritori
+
+  factory :chair
 end
 ```
-It will provide an ablility to declare and refer individual factories
+You'll get a few methods:
 ```ruby
-# Declaration
-MyAbstractFactory.factory(:chair)
-MyAbstractFactory.factory(:table)
-# Access all factories
-MyAbstractFactory.factories # => { chair: #<Toritori::Factory @name: :chair>, table: #<Toritori::Factory @name: :table> }
-# Access individual factory
-MyAbstractFactory.chair_factory # => #<Toritori::Factory @name: :chair>
-MyAbstractFactory.table_factory # => #<Toritori::Factory @name: :table>
+# top level method similar to FactoryBot
+MyAbstractFactory.create(:chair)
+
+# a way for inspecting definitions of factory methods
+MyAbstractFactory.factories         # => { chair: #<Toritori::Factory @name: :chair> }
+MyAbstractFactory.factories[:chair] # => chair: #<Toritori::Factory @name: :chair>
+# an alias methods that reads from factories hash
+factory = MyAbstractFactory.chair_factory     # => chair: #<Toritori::Factory @name: :chair>
+
+# Specific factory actually creates new objects
+# top level method just calls it
+MyAbstractFactory.factories[:chair].create
+
+factory.base_class      #=> #<Class>
+factory.creation_method #=> :new
 ```
-Creating objects is also easy
+This example above shows a rare case when we just create instances of anonymous class.
+## Setup options
+In most cases we want to specify a class of objects we are aiming to produce. Or define a few methods ourself.
+Assume we have some class
 ```ruby
-MyAbstractFactory.table_factory.create(<attrs>) # => #<Class>
+class Table < Struct(:width, :height, :depth)
+  # ...omitted...
+end
 ```
-To provide a specific class for factory to create instances
+To specify that we want to produce instances of `Table` class
 ```ruby
-Sofa = Struct.new(:width)
-
 class MyAbstractFactory
-  include Toritori
-
-  factory :sofa, produces: Sofa
+  factory :table, produces: Table
 end
 
-MyAbstractFactory.sofa_factory # =>
-MyAbstractFactory.sofa_factory.create(2300) # => #<Sofa @width=2300>
+factory = MyAbstractFactory.table_factory
+factory.base_class      #=> #<Table>
+factory.creation_method #=> :new
+
+MyAbstractFactory.create(:table, 80, 80, 120) #=> #<Table @width=80 @height=80 @depth=180>
 ```
-The library defaults is to use `new` method for instantiation and bypass parameters from `create` method. But if you need to customize this behaviour
+By default, we just call `new` method to instantiate an object. Some times it's not possible
 ```ruby
 class MyAbstractFactory
-  include Toritori
-
   factory :file, produces: File, creation_method: :open
 end
 
+factory = MyAbstractFactory.file_factory
+factory.base_class      #=> #<File>
+factory.creation_method #=> :open
+
 MyAbstractFactory.file_factory.create('/dev/null') # => #<File @path='/dev/null'>
 ```
-### Subclassing
-For example:
+Or you need to use another `factory method`
 ```ruby
-class ModernFactory < MyAbstractFactory
-  factories # => { chair: #<Toritori::Factory @name: :chair>,
-            #      table: #<Toritori::Factory @name: :table>,
-            #      sofa: #<Toritori::Factory @name: :sofa, @base_class=Sofa> }
+class MyAbstractFactory
+  factory :user, produces: User do |**kw|
+    FactoryBot.create(:user, **kw)
+  end
 end
+
+factory = MyAbstractFactory.user_factory
+factory.base_class      #=> #<User>
+factory.creation_method #=> #<Proc>
 ```
-If we need to add a wifi option to sofa
+## Sub-classes
+But the main feature of the library is a possibility to change or extend the produced object. It is achieved by defining a sub-class of the target class. That is why `produces` option is required in most cases
 ```ruby
-class ModernFactory < MyAbstractFactory
-  sofa_factory.subclass do
-    def add_wifi
-      @wifi = true
-    end
+class MyAbstractFactory
+  table_factory.subclass do
+    attr_reader :shape
 
-    attr_reader :wifi
+    def initialize(width, height, depth, shape)
+      super(width, height, depth)
+      @shape = shape
+    end
   end
 end
 
-modern_sofa = ModernFactory.sofa_factory.create(2500)
-modern_sofa.wifi # => nil
-modern_sofa.add_wifi
-modern_sofa.wifi # => true
+MyAbstractFactory.create(:table, 80, 80, 80, :round)
+#=> #<Table @width=80 @height=80 @depth=180 @shape=:round>
 ```
-If we need to add wifi option to initializer
+However this operation alters a definition of factory
 ```ruby
-class ModernFactory < MyAbstractFactory
-  # Update initialize method
-  chair_factory.subclass do
-    def initialize(width, wifi)
-      super(width)
-      @wifi = wifi
-    end
+MyAbstractFactory.table_factory.base_class            #=> #<Class>
+MyAbstractFactory.table_factory.base_class.superclass #=> #<Table>
+MyAbstractFactory.table_factory.creation_method       #=> :new
+```
+Sometimes when sub-class definition is big it is better to put it into a separate file.
+```ruby
+class ModernTable < Table
+  # ... omitted ...
+end
 
-    attr_reader :wifi
-  end
+# Alternatively more generic code
+class ModernTable < MyAbstractFactory.table_factory.base_class; end
+
+class MyAbstractFactory
+  table_factory.subclass produces: ModernTable
 end
 
-modern_chair = ModernFactory.chair_factory.create(2500, wifi: false)
-modern_chair.wifi # => false
+MyAbstractFactory.table_factory.base_class            #=> #<ModernTable>
+MyAbstractFactory.table_factory.base_class.superclass #=> #<Table>
+MyAbstractFactory.table_factory.creation_method       #=> :new
 ```
-The subclass (`ModernFactory`) will gen a copy of `factories` so you can customize sublasses without side effects on a base class (`MyAbstractFactory`).
-
-Sometimes when subclass definition is big it is better to put it into a separate file. To make the library to use that sub-class:
+Note, that you should provide a child class otherwise you'll get exception `Toritori::SubclassError`
+It is possible to change creation method of a sub-class
 ```ruby
-class ModernTable < MyAbstractFactory.table_factory.base_class
-  # ... omitted ...
-  end
-
-class ModernFactory < MyAbstractFactory
-  # Update initialize method
-  table_factory.subclass(produces: ModernTable, creation_method: :produce) do
-    def self.produce(...)
+class MyAbstractFactory
+  table_factory.subclass creation_method: :create do
+    def self.create(...)
       new(...)
     end
   end
+end
+
+MyAbstractFactory.table_factory.base_class            #=> #<Class>
+MyAbstractFactory.table_factory.base_class.superclass #=> #<Table>
+MyAbstractFactory.table_factory.creation_method       #=> :create
+```
+Following calls of `subclass` method will create new sub-class based on sub-class generated by previous invocation.
+## Inheritance
+Let's imagine you need to the following setup
+```ruby
+class MyAbstractFactory
+  factory :chair
+  factory :table
+end
 
-  table_factory.create # => #<ModernTable>
+class ModernFactory < MyAbstractFactory
+  chair.subclass do
+    include ModernStyle
+  end
+end
+class VictorianFactory < MyAbstractFactory
+  chair.subclass do
+    include VictorianStyle
+  end
 end
 ```
-The sub-class should be a child of a base class we specified in factory of the parent abstract factory, otherwise you'll get `Toritori::SubclassError`. We recommend to have base classes (`produces:` option) for parent abstract factory defined explicitly to have an ability to refer them in sub-class files.
+During inheritance child classes should get the same factories as parent class. Definition of factories is copied from parent to child class
+```ruby
+copy = MyAbstractFactory.chair_factory.copy
+copy.base_class == MyAbstractFactory.chair_factory.base_class
+copy.creation_method #=> :new
+```
+It means that after the inheritance `factories` of child and parent are disconnected. Changes in factory definition in parent factory won't affect child classes and vice versa.
 
 ## Development
 

data/lib/toritori/factory.rb

@@ -3,14 +3,16 @@
 module Toritori
   # Generates module that adds support for objects creation
   class Factory
+    attr_reader :base_class, :creation_method
+
     def copy
       self.class.new(@name, base_class: @base_class, creation_method: @creation_method)
     end
 
-    def initialize(name, base_class: nil, creation_method: :new)
+    def initialize(name, base_class: nil, creation_method: :new, &block)
       @name = name
       @base_class = base_class
-      @creation_method = creation_method
+      @creation_method = block || creation_method
     end
 
     def subclass(produces: nil, creation_method: @creation_method, &block)
@@ -20,6 +22,7 @@ module Toritori
     end
 
     def create(*args, **kwargs, &block)
+      return @creation_method.call(*args, **kwargs, &block) if defined? @creation_method.call
       return @base_class.new(*args, **kwargs, &block) if @creation_method == :new
 
       @base_class.public_send(@creation_method, *args, **kwargs, &block)

data/lib/toritori/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toritori
-  VERSION = '0.2.0'
+  VERSION = '0.2.2'
 end

data/lib/toritori.rb

@@ -28,6 +28,10 @@ module Toritori
       super
       subclass.factories = factories.transform_values(&:copy)
     end
+
+    def create(name, *args, **kwargs, &block)
+      factories[name].create(*args, **kwargs, &block)
+    end
   end
 
   def self.included(receiver)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toritori
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Andrii Baran
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-21 00:00:00.000000000 Z
+date: 2024-04-17 00:00:00.000000000 Z
 dependencies: []
 description: Create factories with DSL
 email: