strategic 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d5c5c2a7b15c1c3e826a37c64b0b4b90f8b4a1dd8d93aaeb5f6c81c796faa93
-  data.tar.gz: ef054a37db19f752d92e2344f7da9f6269732bcf897babcce4c756e426ca90e2
+  metadata.gz: f8ddc7e63dc608ac0a7e97ebb9110431c9a490e7ec07abed6936bb347b6105e8
+  data.tar.gz: 4ca98f38d3933fc5f33ac460dc2767a2769cfbe0a870c9f48bfb427ca2a4c1c4
 SHA512:
-  metadata.gz: 18fe37a88abab52119d44e03402ea2c005c3235d8709b3802dca8cebaf863af712bbc62c68bed47940ca7846d310135a685e416bc94c4c4f7d6984094ab5071b
-  data.tar.gz: 959739994722aa145afa46180cad9ef556fe27e57f39e9b49b631074dd788b2cfcc60dda26f564f8d09a2ce94c1100dc6d5994718d3b1421599dbc0665c1bbee
+  metadata.gz: '067224647109cf8198006ddce287755a1ec9997ff67fc8a3099d4f172ba6549a8e9ef4f8bf285d44996aa3a5d6ef4949892dffab5a1d26918d17cdc27cbd6e0b'
+  data.tar.gz: 1046857c6fd46e0615ab559bbb4e84bc8ba70f7d7995bd621e7d182316d603d22e4d99e2fefc1adce3d2682769519e0cc9189bef7ce614d0aca8354271994e05

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 1.0.0
+
+- Improve design to better match the authentic Gang of Four Strategy Pattern with `Strategic::Strategy` module, removing the need for inheritance.
+- `#strategy=`/`#strategy` enable setting/getting strategy on model
+- `#context` enables getting strategic model instance on strategy just as per the GOF Design Pattern
+- `default_strategy` class body method to set default strategy
+- Filter strategies by ones ending with `Strategy` in class name
+
 ## 0.9.1
 
 - `strategy_name` returns parsed strategy name of current strategy class

data/README.md

@@ -1,4 +1,4 @@
-# Strategic 0.9.1
+# Strategic 1.0.0
 ## Painless Strategy Pattern in Ruby and Rails
 [![Gem Version](https://badge.fury.io/rb/strategic.svg)](http://badge.fury.io/rb/strategic)
 [![rspec](https://github.com/AndyObtiva/strategic/actions/workflows/ruby.yml/badge.svg)](https://github.com/AndyObtiva/strategic/actions/workflows/ruby.yml)
@@ -7,9 +7,8 @@
 
 `if`/`case` conditionals can get really hairy in highly sophisticated business domains.
 Object-oriented inheritance helps remedy the problem, but dumping all
-logic variations in subclasses can cause a maintenance nightmare.
-Thankfully, the Strategy Pattern as per the [Gang of Four book](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612) solves the problem by externalizing logic to
-separate classes outside the domain models.
+logic variations in domain model subclasses can cause a maintenance nightmare.
+Thankfully, the Strategy Pattern as per the [Gang of Four book](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612) solves the problem by externalizing logic via composition to separate classes outside the domain models.
 
 Still, there are a number of challenges with "repeated implementation" of the Strategy Pattern:
 - Making domain models aware of newly added strategies without touching their
@@ -27,7 +26,9 @@ code (Open/Closed Principle).
 
 `Strategic` enables you to make any existing domain model "strategic",
 externalizing all logic concerning algorithmic variations into separate strategy
-classes that are easy to find, maintain and extend while honoring the Open/Closed Principle.
+classes that are easy to find, maintain and extend while honoring the Open/Closed Principle and avoiding conditionals.
+
+In summary, if you make a class called `TaxCalculator` strategic by including the `Strategic` mixin module, now you are able to drop strategies under the `tax_calculator` directory sitting next to the class (e.g. `tax_calculator/us_strategy.rb`, `tax_calculator/canada_strategy.rb`) while gaining extra [API](#api) methods to grab strategy names to present in a user interface (`.strategy_names`), set a strategy (`#strategy=(strategy_name)`), and/or instantiate `TaxCalculator` directly with a strategy from the get-go (`.new_with_strategy(strategy_name, *initialize_args)`). Finally, you can simply invoke strategy methods on the main strategic model (e.g. `tax_calculator.tax_for(39.78)`).
 
 ### Example
 
@@ -40,71 +41,74 @@ alt="Strategic Example" />
 class TaxCalculator
   include Strategic
 
-  def tax_for(amount)
-    amount * 0.09
-  end
+  # strategies may implement a tax_for(amount) method
 end
 ```
 
 2. Now, you can add strategies under this directory without having to modify the original class: `tax_calculator`
 
-3. Add strategy classes under the namespace matching the original class name (`TaxCalculator`) and extending the original class (`TaxCalculator`) just to take advantage of default logic in it:
+3. Add strategy classes having names ending with `Strategy` by convention (e.g. `UsStrategy`) under the namespace matching the original class name (`TaxCalculator::` as in `tax_calculator/us_strategy.rb` representing `TaxCalculator::UsStrategy`) and including the module (`Strategic::Strategy`):
+
+All strategies get access to their context (strategic model instance), which they can use in their logic.
 
 ```ruby
-class TaxCalculator::UsStrategy < TaxCalculator
-  def initialize(state)
-    @state = state
-  end
+class TaxCalculator::UsStrategy
+  include Strategic::Strategy
+  
   def tax_for(amount)
-    amount * state_rate
+    amount * state_rate(context.state)
   end
-  # ... more code follows
+  # ... other strategy methods follow
 end
 
-class TaxCalculator::CanadaStrategy < TaxCalculator
-  def initialize(province)
-    @province = province
-  end
+class TaxCalculator::CanadaStrategy
+  include Strategic::Strategy
+
   def tax_for(amount)
-    amount * (gst + qst)
+    amount * (gst(context.province) + qst(context.province))
   end
-  # ... more code follows
+  # ... other strategy methods follow
 end
 ```
 
-4. In client code, obtain the needed strategy by underscored string reference minus the word strategy (e.g. UsStrategy becomes simply 'us'):
+(note: if you use strategy inheritance hierarchies, make sure to have strategy base classes end with `StrategyBase` to avoid getting picked up as strategies)
 
-```ruby
-tax_calculator_strategy_class = TaxCalculator.strategy_class_for('us')
-```
-
-5. Instantiate the strategy object:
+4. In client code, set the strategy by underscored string reference minus the word strategy (e.g. UsStrategy becomes simply 'us'):
 
 ```ruby
-tax_calculator_strategy = strategy_class.new('IL')
+tax_calculator = TaxCalculator.new(args)
+tax_calculator.strategy = 'us'
 ```
 
-6. Invoke the strategy overridden method:
+4a. Alternatively, instantiate the strategic model with a strategy to begin with:
 
 ```ruby
-tax = tax_calculator_strategy.tax_for(39.78)
+tax_calculator = TaxCalculator.new_with_strategy('us', args)
 ```
 
-**Alternative approach using `new_strategy(strategy_name, *initializer_args)`:**
+5. Invoke the strategy implemented method:
 
 ```ruby
-tax_calculator_strategy = TaxCalculator.new_strategy('US', 'IL')
-tax = tax_calculator_strategy.tax_for(39.78)
+tax = tax_calculator.tax_for(39.78)
 ```
 
 **Default strategy for a strategy name that has no strategy class is the superclass: `TaxCalculator`**
 
+You may set a default strategy on a strategic model via class method `default_strategy`
+
 ```ruby
-tax_calculator_strategy_class = TaxCalculator.strategy_class_for('France')
-tax_calculator_strategy = tax_calculator_strategy_class.new
-tax = tax_calculator_strategy.tax_for(100.0) # returns 9.0 from TaxCalculator
+class TaxCalculator
+  include Strategic
+  
+  default_strategy 'canada'
+end
+
+tax_calculator = TaxCalculator.new(args)
+tax = tax_calculator.tax_for(39.78)
 ```
 
+If no strategy is selected and you try to invoke a method that belongs to strategies, Ruby raises an amended method missing error informing you that no strategy is set to handle the method (in case it was a strategy method).
+
 ## Setup
 
 ### Option 1: Bundler
@@ -112,7 +116,7 @@ tax = tax_calculator_strategy.tax_for(100.0) # returns 9.0 from TaxCalculator
 Add the following to bundler's `Gemfile`.
 
 ```ruby
-gem 'strategic', '~> 0.9.1'
+gem 'strategic', '~> 1.0.0'
 ```
 
 ### Option 2: Manual
@@ -120,7 +124,7 @@ gem 'strategic', '~> 0.9.1'
 Or manually install and require library.
 
 ```bash
-gem install strategic -v0.9.1
+gem install strategic -v1.0.0
 ```
 
 ```ruby
@@ -130,34 +134,63 @@ require 'strategic'
 ### Usage
 
 Steps:
-1. Have the original class you'd like to strategize include Strategic
-2. Create a directory matching the class underscored file name minus the '.rb' extension
-3. Create a strategy class under that directory, which:
+1. Have the original class you'd like to strategize include `Strategic` (e.g. `def TaxCalculator; include Strategic; end`
+2. Create a directory matching the class underscored file name minus the '.rb' extension (e.g. `tax_calculator/`)
+3. Create a strategy class under that directory (e.g. `tax_calculator/us_strategy.rb`), which:
  - Lives under the original class namespace
- - Extends the original class to strategize
+ - Includes the `Strategic::Strategy` module
  - Has a class name that ends with `Strategy` suffix (e.g. `NewCustomerStrategy`)
-4. Get needed strategy class using `strategy_class_for` class method taking strategy name (any case) or related object/type (can call `strategy_names` class method to obtain strategy names)
-5. Instantiate strategy with needed constructor parameters
+4. Set strategy on strategic model using `strategy=` attribute writer method or instantiate with `new_with_strategy` class method, which takes a strategy name string (any case), strategy class, or mirror object (having a class matching strategy name minus the word `Strategy`) (note: you can call `::strategy_names` class method to obtain available strategy names or `::stratgies` to obtain available strategy classes)
 6. Invoke strategy method needed
 
-Alternative approach:
+## API
+
+- `StrategicClass::strategy_names`: returns list of strategy names (strings) discovered by convention (nested under a namespace matching the superclass name)
+- `StrategicClass::strategies`: returns list of strategies discovered by convention (nested under a namespace matching the superclass name)
+- `StrategicClass::new_with_strategy(string_or_class_or_object, *args, &block)`: instantiates a strategy based on a string/class/object and strategy constructor args
+- `StrategicClass::strategy_class_for(string_or_class_or_object)`: selects a strategy class based on a string (e.g. 'us' selects UsStrategy) or alternatively a class/object if you have a mirror hierarchy for the strategy hierarchy
+- `StrategicClass::default_strategy`: (used in model class body) sets default strategy as a strategy name string (e.g. 'us' selects UsStrategy) or alternatively a class/object if you have a mirror hierarchy for the strategy hierarchy
+- `StrategicClass::strategy_matcher`: (used in model class body) custom matcher for all strategies (e.g. `strategy_matcher {|string| string.start_with?('C') && string.end_with?('o')}`)
+- `StrategicClass#strategy=`: sets strategy
+- `StrategicClass#strategy`: returns current strategy
+- `StrategyClass::strategy_name`: returns parsed strategy name of current strategy class
+- `StrategyClass::strategy_matcher`: (used in model class body) custom matcher for a specific strategy (e.g. `strategy_matcher {|string| string.start_with?('C') && string.end_with?('o')}`)
+- `StrategyClass::strategy_exclusion`: (used in model class body) exclusion from custom matcher (e.g. `strategy_exclusion 'Cio'`)
+- `StrategyClass::strategy_alias`: (used in model class body) alias for strategy in addition to strategy's name derived from class name by convention (e.g. `strategy_alias 'USA'` for `UsStrategy`)
+- `StrategyClass#context`: returns strategy context (the strategic model instance)
+
+Example with customizations via class body methods:
 
-Combine steps 4 and 5 using `new_strategy` method, which takes both strategy name
-and constructor parameters
+```ruby
+class TaxCalculator
+  default_strategy 'us'
+
+  # fuzz matcher
+  strategy_matcher do |string_or_class_or_object|
+    class_name = self.name # current strategy class name being tested for matching
+    strategy_name = class_name.split('::').last.sub(/Strategy$/, '').gsub(/([A-Z])/) {|letter| "_#{letter.downcase}"}[1..-1]
+    strategy_name_length = strategy_name.length
+    possible_keywords = strategy_name_length.times.map {|n| strategy_name.chars.combination(strategy_name_length - n).to_a}.reduce(:+).map(&:join)
+    possible_keywords.include?(string_or_class_or_object)
+  end
+  # ... more code follows
+end
 
-Passing an invalid strategy name to `strategy_class_for` returns original class as the default
-strategy.
+class TaxCalculator::UsStrategy
+  include Strategic::Strategy
 
-## API
+  strategy_alias 'USA'
+  strategy_exclusion 'U'
+  
+  # ... strategy methods follow
+end
 
-- `StrategicClass::strategy_class_for(string_or_class_or_object)`: selects a strategy class based on a string (e.g. 'us' selects USStrategy) or alternatively a class/object if you have a mirror hierarchy for the strategy hierarchy
-- `StrategicClass::new_strategy(string_or_class_or_object, *args, &block)`: instantiates a strategy based on a string/class/object and strategy constructor args
-- `StrategicClass::strategies`: returns list of strategies discovered by convention (nested under a namespace matching the superclass name)
-- `StrategicClass::strategy_names`: returns list of strategy names (strings) discovered by convention (nested under a namespace matching the superclass name)
-- `StrategicClass::strategy_name`: returns parsed strategy name of current strategy class
-- `StrategicClass::strategy_matcher`: custom match (e.g. `strategy_matcher {|string| string.start_with?('C') && string.end_with?('o')}`)
-- `StrategicClass::strategy_exclusion`: exclusion from custom matcher (e.g. `strategy_exclusion 'Cio'`)
-- `StrategicClass::strategy_alias`: alias for strategy in addition to strategy's name derived from class name by convention (e.g. `strategy_alias 'USA'` for `UsStrategy`)
+class TaxCalculator::CanadaStrategy
+  include Strategic::Strategy
+  
+  # ... strategy methods follow
+end
+```
 
 ## TODO
 

data/lib/strategic.rb

@@ -18,7 +18,7 @@
 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
+  
 module Strategic
   def self.included(klass)
     klass.extend(ClassMethods)
@@ -26,27 +26,19 @@ module Strategic
   end
 
   module ClassMethods
-    def strategy_alias(alias_string_or_class_or_object)
-      strategy_aliases << alias_string_or_class_or_object
-    end
-    
-    def strategy_aliases
-      @strategy_aliases ||= []
-    end
-  
-    def strategy_exclusion(exclusion_string_or_class_or_object)
-      strategy_exclusions << exclusion_string_or_class_or_object
-    end
-    
-    def strategy_exclusions
-      @strategy_exclusions ||= []
-    end
-    
     def strategy_matcher(&matcher_block)
-      if block_given?
+      if matcher_block.nil?
+        @strategy_matcher
+      else
         @strategy_matcher = matcher_block
+      end
+    end
+    
+    def default_strategy(string_or_class_or_object = nil)
+      if string_or_class_or_object.nil?
+        @default_strategy
       else
-        @strategy_matcher
+        @default_strategy = strategy_class_for(string_or_class_or_object)
       end
     end
     
@@ -65,7 +57,7 @@ module Strategic
     def strategy_class_for(string_or_class_or_object)
       strategy_class = strategy_matcher_for_any_strategy? ? strategy_class_with_strategy_matcher(string_or_class_or_object) : strategy_class_without_strategy_matcher(string_or_class_or_object)
       strategy_class ||= strategies.detect { |strategy| strategy.strategy_aliases.include?(string_or_class_or_object) }
-      strategy_class ||= self
+      strategy_class ||= default_strategy
     end
     
     def strategy_class_with_strategy_matcher(string_or_class_or_object)
@@ -93,26 +85,49 @@ module Strategic
       end
     end
 
-    def new_strategy(string_or_class_or_object, *args, &block)
-      strategy_class_for(string_or_class_or_object).new(*args, &block)
+    def new_with_strategy(string_or_class_or_object, *args, &block)
+      new(*args, &block).tap do |model|
+        model.strategy = string_or_class_or_object
+      end
     end
 
     def strategies
       constants.map do |constant_symbol|
         const_get(constant_symbol)
       end.select do |constant|
-        constant.respond_to?(:ancestors) && constant.ancestors.include?(self)
-      end
+        constant.ancestors.include?(Strategic::Strategy) && constant.name.split('::').last.end_with?('Strategy') && constant.name.split('::').last != 'Strategy' # has to be something like PrefixStrategy
+      end.sort_by(&:strategy_name)
     end
 
     def strategy_names
       strategies.map(&:strategy_name)
     end
     
-    def strategy_name
-      Strategic.underscore(name.split(':').last).sub(/_strategy$/, '')
+  end
+  
+  def strategy=(string_or_class_or_object)
+    @strategy = self.class.strategy_class_for(string_or_class_or_object)&.new(self)
+  end
+      
+  def strategy
+    @strategy
+  end
+
+  def method_missing(method_name, *args, &block)
+    if strategy&.respond_to?(method_name, *args, &block)
+      strategy.send(method_name, *args, &block)
+    else
+      begin
+        super
+      rescue => e
+        raise "No strategy is set to handle the method #{method_name} with args #{args.inspect} and block #{block.inspect} / " + e.message
+      end
     end
   end
+    
+  def respond_to?(method_name, *args, &block)
+    strategy&.respond_to?(method_name, *args, &block) || super
+  end
 
   private
 
@@ -124,3 +139,5 @@ module Strategic
     text.chars.reduce('') {|output,c| !output.empty? && c.match(/[A-Z]/) ? output + '_' + c : output + c}.downcase
   end
 end
+
+require_relative 'strategic/strategy'

data/lib/strategic/strategy.rb

@@ -0,0 +1,65 @@
+# Copyright (c) 2020-2021 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Strategic
+  module Strategy
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+  
+    module ClassMethods
+      def strategy_alias(alias_string_or_class_or_object)
+        strategy_aliases << alias_string_or_class_or_object
+      end
+      
+      def strategy_aliases
+        @strategy_aliases ||= []
+      end
+    
+      def strategy_exclusion(exclusion_string_or_class_or_object)
+        strategy_exclusions << exclusion_string_or_class_or_object
+      end
+      
+      def strategy_exclusions
+        @strategy_exclusions ||= []
+      end
+      
+      def strategy_matcher(&matcher_block)
+        if block_given?
+          @strategy_matcher = matcher_block
+        else
+          @strategy_matcher
+        end
+      end
+      
+      def strategy_name
+        Strategic.underscore(name.split(':').last).sub(/_strategy$/, '')
+      end
+    end
+    
+    attr_reader :context
+    
+    def initialize(context)
+      @context = context
+    end
+    
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strategic
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Andy Maleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-17 00:00:00.000000000 Z
+date: 2021-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -147,6 +147,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/strategic.rb
+- lib/strategic/strategy.rb
 homepage: http://github.com/AndyObtiva/strategic
 licenses:
 - MIT