industrialist 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d4306467a233c5874542880e1f7e2f30300be18d28dad188e8c02c6fb9212e5
-  data.tar.gz: 7c88ab7b91c2363c35474711b6017b4b77be3266b31a53dae9be9dca6ee3a429
+  metadata.gz: 858f0f4e068299c8eab65bf53cc4b78b5d582ad1a36a81bd85c41654c21e9855
+  data.tar.gz: ed03501fc2ab8f74f5ac29d1e47675ac77977e5c859a5a9ddd9701b28afdbc70
 SHA512:
-  metadata.gz: a18c367c3960e114cdc7b202ceecdb9ce8c3897f836e87cfadc08b8e0a432277a4b8d6b0f7ea39163a231addbd7cbea76dfa9f6c9a8a38d780dd9fff4e7c5795
-  data.tar.gz: 9ea2a2c21b12b3bb8a8d15b411f629c320de13e546304aa3244bd0a45250890cca27470dfc09a64de0109ab012f0df0590bfa2e7e2a458e969077b6df3715faf
+  metadata.gz: 751a1bbef0a2f80b1936d0b23608880fd5a3cec7a4dcdeea0d8f705c96a4c86d37c5576364cf484159054be6845deadb3bb038fb298daa959d96fe7add723877
+  data.tar.gz: 8ec6e11e6851d7f17a0f7e92e3ebb6e246daab3b747534cf365ea623a1d4ff3390a202cdb92d7e815320b3062439fe82a0981a06837e19c0f93d98822f35e170

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    industrialist (0.3.0)
+    industrialist (0.4.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -36,7 +36,7 @@ end
 AutomobileFactory.build(:sedan)
 ```
 
-The Ruby way to do this is with a Hash:
+Another way to do this is with a hash:
 
 ```ruby
 class Sedan; end
@@ -60,9 +60,23 @@ AutomobileFactory.build(:coupe)
 
 But, both of these approaches require you to maintain your factory by hand. In order to extend these factories, you must modify them, which violates the Open/Closed Principle.
 
+The Ruby way to do this is with conventions and metaprogramming:
+
+```ruby
+class AutomobileFactory
+  def self.build(automobile_type, *args)
+    Object.get_const("#{automobile_type.capitalize}").new(*args)
+  end
+end
+```
+
+But, factories of this type also have issues. If your keys are not easily mapped to a convention, you won't be able to use this type of factory. For example, the `Cabriolet` class above corresponds to the key `:convertible`.
+
+You can find a deeper dive into the motivations behind Industrialst [here](https://engineering.entelo.com/extension-without-modification-cb0f9cfb64a3).
+
 ## Usage
 
-Industrialist creates factories for you. Just include the Manufacturable module in a base class and give the factory a name. Industrialist also allows children of the base class to register themselves with the factory by specifying their corresponding key. Like this:
+Industrialist creates factories for you. Just include the Manufacturable module in a base class and call `create_factory` with a name. Industrialist also allows children of the base class to register themselves with the factory by specifying their corresponding key.
 
 ```ruby
 class Automobile
@@ -78,11 +92,71 @@ class Coupe < Automobile
   corresponds_to :coupe
 end
 
+AutomobileFactory.build(:sedan)  # => #<Sedan:0x00007ff64d88ce58>
+```
+
+Manufacturable classes may also correspond to multiple keys:
+
+```ruby
 class Cabriolet < Automobile
+  corresponds_to :cabriolet
   corresponds_to :convertible
 end
+```
+
+By default, Industrialist factories will return `nil` when built with an unregistered key. If you would instead prefer a default object, you can designate a `manufacturable_default`.
+
+```ruby
+class Airplane
+  include Industrialist::Manufacturable
+  create_factory :AirplaneFactory
+end
+
+class Biplane < Airplane
+  manufacturable_default
+  corresponds_to :biplane
+end
+
+class FighterJet < Airplane
+  corresponds_to :fighter
+end
 
-AutomobileFactory.build(:convertible)
+AirplaneFactory.build(:plane)  # => #<Biplane:0x00007ffcd4165610>
+```
+
+Finally, Industrialist will accept any Ruby object as a key, which is handy when you need to define more complex keys. For example, you could use a hash:
+
+```ruby
+class Train
+  include Industrialist::Manufacturable
+  create_factory :TrainFactory
+end
+
+class SteamEngine < Train
+  corresponds_to engine: :steam
+end
+
+class Diesel < Train
+  corresponds_to engine: :diesel
+end
+
+class Boxcar < Train
+  corresponds_to cargo: :boxcar
+end
+
+class Carriage < Train
+  corresponds_to passenger: :carriage
+end
+
+class Sleeper < Train
+  corresponds_to passenger: :sleeper
+end
+
+def train_car(role, type)
+  TrainFactory.build(role => type)
+end
+
+train_car(:engine, :diesel)  # => #<Diesel:0x00007ff64f846640>
 ```
 
 ## Installation
@@ -101,15 +175,22 @@ Or install it yourself as:
 
     $ gem install industrialist
 
-## Development
+If you are using Industrialist with Rails, you'll need to preload your manufacturable objects in the development and test environments in an intializer, like this:
 
-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.
+```ruby
+def require_factory(class_type)
+  Dir[Rails.root.join('app', "#{class_type}", '**', '*.rb').to_s].each { |file| require file }
+end
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+if %w(development test).include?(Rails.env)
+  require_factory('automobiles')
+  require_factory('books')
+end
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/entelo/industrialist. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/entelo/industrialist.
 
 ## License
 

data/lib/industrialist/factory.rb

@@ -1,5 +1,7 @@
 module Industrialist
   class Factory
+    DEFAULT_KEY = :__manufacturable_default__
+
     attr_reader :registry
 
     def initialize
@@ -11,10 +13,12 @@ module Industrialist
     end
 
     def build(key, *args)
-      klass = registry[factory_key(key)]
+      klass = registry[factory_key(key)] || registry[DEFAULT_KEY]
       klass&.new(*args)
     end
 
+    private
+
     def factory_key(key)
       (key.respond_to?(:to_sym) && key.to_sym) || key
     end

data/lib/industrialist/manufacturable.rb

@@ -3,12 +3,11 @@ require 'industrialist/warning_helper'
 
 module Industrialist
   module Manufacturable
-    extend WarningHelper
-
-    ALREADY_INCLUDED_WARNING_MESSAGE = 'warning: a factory is already defined on this class hierarchy'.freeze
+    ALREADY_INCLUDED_WARNING_MESSAGE = 'warning: overriding previously defined factory on this class hierarchy'.freeze
+    MULTIPLE_DEFAULT_WARNING_MESSAGE = 'warning: overriding a previously registered default class'.freeze
 
     def self.included(base)
-      warning(ALREADY_INCLUDED_WARNING_MESSAGE) if base.class_variable_defined?(:@@factory)
+      WarningHelper.warning(ALREADY_INCLUDED_WARNING_MESSAGE) if base.class_variable_defined?(:@@factory)
 
       base.extend ClassMethods
       base.class_variable_set(:@@factory, Industrialist::Factory.new)
@@ -23,6 +22,12 @@ module Industrialist
         factory.register(key, self)
       end
 
+      def manufacturable_default
+        WarningHelper.warning(MULTIPLE_DEFAULT_WARNING_MESSAGE) if factory.registry[Industrialist::Factory::DEFAULT_KEY]
+
+        factory.register(Industrialist::Factory::DEFAULT_KEY, self)
+      end
+
       def factory
         class_variable_get(:@@factory)
       end

data/lib/industrialist/version.rb

@@ -1,3 +1,3 @@
 module Industrialist
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/lib/industrialist/warning_helper.rb

@@ -1,6 +1,6 @@
 module Industrialist
-  module WarningHelper
-    def warning(message)
+  class WarningHelper
+    def self.warning(message)
       most_recent_caller = caller(2..2).first.split(':')
       file_name = most_recent_caller[0]
       line_number = most_recent_caller[1]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: industrialist
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-23 00:00:00.000000000 Z
+date: 2019-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler