strategic 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5b79636eeccc8c6b813d95c05e0aba4e864d8cbc
-  data.tar.gz: 4fb40967c29ffa5c788db5432c0a80444ab5c3db
+SHA256:
+  metadata.gz: d4031c3d360c08e12ac58e42d6e56b97c177c342e64a1680275f50ad0add7e08
+  data.tar.gz: 5b4b783eca5301aa05f6043729531c7458b40806ed3b768c7b341b283d77ccda
 SHA512:
-  metadata.gz: 654d0e603dbe10f748ba3025664bf0480a4833d62be091ffb3f6b807754487a8284f2687f7f9c40658d499e99342f408c2c282c8590962664c16cf6504453aa9
-  data.tar.gz: 74f1272d40abb8e22520914614bf99a80455f99480007f4b7bc54b0b785065afcf8762822cf34bae977108e42895971c4bf9ac822d18f81620f9914925f461bd
+  metadata.gz: b5edee9e7e0f491e5ecda04465372bb9e45274ecc906d07798e627a4485f8776f1625c8175ff403b3f8a25a8e16781f20dd6d02c76b0600cc41b7a9c4354b920
+  data.tar.gz: 1c7ebfb4ce224c80d3181b55e4c9137ac7d1015733211592ec95218a581cedafd56abe235fab07de92c2cdf2343873eb2ad5a7789ebc18d97f05f84b88528c13

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+## 0.9.0
+
+- `strategy_matcher` block support that enables any strategy to specify a custom matcher (or the superclass of all strategies instead)
+- `strategy_exclusion` class method support that enables any strategy to specify exclusions from the custom `strategy_matcher`
+- `strategy_alias` class method support that enables any strategy to specify extra aliases (used by superclass's `strategy_class_for` method)
+
+## 0.8.0
+
+- Initial version with `strategy_class_for`, `new_strategy`, `strategies`, and `strategy_names`

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017 Andy Maleh
+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

data/README.md

@@ -1,18 +1,23 @@
-# Strategic (Painless Strategy Pattern in Ruby and Rails)
+# Strategic 0.9.0
+## Painless Strategy Pattern in Ruby and Rails
 [![Gem Version](https://badge.fury.io/rb/strategic.svg)](http://badge.fury.io/rb/strategic)
+[![Build Status](https://travis-ci.com/AndyObtiva/strategic.svg?branch=master)](https://travis-ci.com/AndyObtiva/strategic?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/strategic/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/strategic?branch=master)
 
-if/case conditionals can get really hairy in highly sophisticated business domains.
-Domain model inheritance can help remedy the problem, but dumping all
-logic variations in the same domain models can cause a maintenance nightmare.
-Thankfully, Strategy Pattern as per the Gang of Four solves the problem by externalizing logic variations to
+(Note: this gem is a very early alpha work in progress and may change API in the future)
+
+`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.
 
-Still, there are a number of challenges with repeated implementation of Strategy Pattern:
+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
 code (Open/Closed Principle).
-- Fetching the right strategy without use of conditionals.
+- Fetching the right strategy without the use of conditionals.
 - Avoiding duplication of strategy dispatch code for multiple domain models
-- Have different strategies mirror an existing domain model hierarchy
+- Have strategies mirror an existing domain model inheritance hierarchy
 
 `strategic` solves these problems by offering:
 - Strategy Pattern support through a Ruby mixin and strategy path/name convention
@@ -21,56 +26,16 @@ code (Open/Closed Principle).
 - Ability to fetch a strategy by name or by object type to mirror
 - Plain Ruby and Ruby on Rails support
 
-`strategic` enables you to make any existing domain model "strategic",
+`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.
-
-## Instructions
-
-### Option 1: Bundler
-
-Add the following to bundler's `Gemfile`.
-
-```ruby
-gem 'strategic', '~> 0.8.0'
-```
-
-### Option 2: Manual
-
-Or manually install and require library.
-
-```bash
-gem install strategic -v0.8.0
-```
-
-```ruby
-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:
- - Lives under the original class namespace
- - Extends the original class to strategize
- - 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
-6. Invoke strategy method needed
-
-Alternative approach:
-
-Combine steps 4 and 5 using `new_strategy` method, which takes both strategy name
-and constructor parameters
-
-Passing an invalid strategy name to `strategy_class_for` returns original class as the default
-strategy.
+classes that are easy to find, maintain and extend while honoring the Open/Closed Principle.
 
 ### Example
 
-1. Class to strategize is: `TaxCalculator`
+<img src="strategic-example.png"
+alt="Strategic Example" />
+
+1. Include `Strategic` module in the Class to strategize: `TaxCalculator`
 
 ```ruby
 class TaxCalculator
@@ -82,9 +47,9 @@ class TaxCalculator
 end
 ```
 
-2. Directory to create strategies under: `tax_calculator`
+2. Now, you can add strategies under this directory without having to modify the original class: `tax_calculator`
 
-3. Strategy class:
+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:
 
 ```ruby
 class TaxCalculator::UsStrategy < TaxCalculator
@@ -108,32 +73,32 @@ class TaxCalculator::CanadaStrategy < TaxCalculator
 end
 ```
 
-4. Get needed strategy:
+4. In client code, obtain the needed strategy by underscored string reference minus the word strategy (e.g. UsStrategy becomes simply 'us'):
 
 ```ruby
 tax_calculator_strategy_class = TaxCalculator.strategy_class_for('us')
 ```
 
-5. Instantiate strategy:
+5. Instantiate the strategy object:
 
 ```ruby
 tax_calculator_strategy = strategy_class.new('IL')
 ```
 
-6. Invoke strategy method:
+6. Invoke the strategy overridden method:
 
 ```ruby
 tax = tax_calculator_strategy.tax_for(39.78)
 ```
 
-**Alternative approach using `new_strategy`:**
+**Alternative approach using `new_strategy(strategy_name, *initializer_args)`:**
 
 ```ruby
 tax_calculator_strategy = TaxCalculator.new_strategy('US', 'IL')
 tax = tax_calculator_strategy.tax_for(39.78)
 ```
 
-**Default strategy for a strategy name that has no strategy class is TaxCalculator**
+**Default strategy for a strategy name that has no strategy class is the superclass: `TaxCalculator`**
 
 ```ruby
 tax_calculator_strategy_class = TaxCalculator.strategy_class_for('France')
@@ -141,13 +106,66 @@ tax_calculator_strategy = tax_calculator_strategy_class.new
 tax = tax_calculator_strategy.tax_for(100.0) # returns 9.0 from TaxCalculator
 ```
 
-## Release Notes
+## Setup
 
-**0.8.0:** Initial version with `strategy_class_for`, `new_strategy`, `strategies`, and `strategy_names`
+### Option 1: Bundler
+
+Add the following to bundler's `Gemfile`.
+
+```ruby
+gem 'strategic', '~> 0.9.0'
+```
+
+### Option 2: Manual
+
+Or manually install and require library.
+
+```bash
+gem install strategic -v0.9.0
+```
+
+```ruby
+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:
+ - Lives under the original class namespace
+ - Extends the original class to strategize
+ - 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
+6. Invoke strategy method needed
+
+Alternative approach:
+
+Combine steps 4 and 5 using `new_strategy` method, which takes both strategy name
+and constructor parameters
+
+Passing an invalid strategy name to `strategy_class_for` returns original class as the default
+strategy.
+
+## API
+
+- `StrategicSuperClass::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
+- `StrategicSuperClass::new_strategy(string_or_class_or_object, *args, &block)`: instantiates a strategy based on a string/class/object and strategy constructor args
+- `StrategicSuperClass::strategies`: returns list of strategies discovered by convention (nested under a namespace matching the superclass name)
+- `StrategicSuperClass::strategy_names`: returns list of strategy names (strings) discovered by convention (nested under a namespace matching the superclass name)
+- `StrategicSuperClass::strategy_matcher`: custom match (e.g. `strategy_matcher {|string| string.start_with?('C') && string.end_with?('o')}`)
+- `StrategicSuperClass::strategy_exclusion`: exclusion from custom matcher (e.g. `strategy_exclusion 'Cio'`)
+- `StrategicSuperClass::strategy_alias`: alias for strategy in addition to strategy's name derived from class name by convention (e.g. `strategy_alias 'USA'` for `UsStrategy`)
 
 ## TODO
 
-None
+[TODO.md](TODO.md)
+
+## Change Log
+
+[CHANGELOG.md](CHANGELOG.md)
 
 ## Contributing
 
@@ -161,7 +179,8 @@ None
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-## Copyright
+## License
+
+[MIT](LICENSE.txt)
 
-Copyright (c) 2020 Andy Maleh. See LICENSE.txt for
-further details.
+Copyright (c) 2020-2021 Andy Maleh.

data/lib/strategic.rb

@@ -1,3 +1,24 @@
+# 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
   def self.included(klass)
     klass.extend(ClassMethods)
@@ -5,6 +26,30 @@ 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?
+        @strategy_matcher = matcher_block
+      else
+        @strategy_matcher
+      end
+    end
+  
     def require_strategies
       klass_path = caller[1].split(':').first
       strategy_path = File.expand_path(File.join(klass_path, '..', Strategic.underscore(self.name), '**', '*.rb'))
@@ -14,17 +59,30 @@ module Strategic
     end
 
     def strategy_class_for(string_or_class_or_object)
-      if string_or_class_or_object.is_a?(String)
-        strategy_class_name = string_or_class_or_object.downcase
-      elsif string_or_class_or_object.is_a?(Class)
-        strategy_class_name = string_or_class_or_object.name
+      strategy_class = nil
+      if strategy_matcher
+        strategy_class = strategies.detect do |strategy|
+          match = strategy&.strategy_matcher&.call(string_or_class_or_object)
+          match ||= strategy.instance_exec(string_or_class_or_object, &strategy_matcher)
+          match unless strategy.strategy_exclusions.include?(string_or_class_or_object)
+        end
       else
-        strategy_class_name = string_or_class_or_object.class.name
+        if string_or_class_or_object.is_a?(String)
+          strategy_class_name = string_or_class_or_object.downcase
+        elsif string_or_class_or_object.is_a?(Class)
+          strategy_class_name = string_or_class_or_object.name
+        else
+          strategy_class_name = string_or_class_or_object.class.name
+        end
+        begin
+          class_name = "::#{self.name}::#{Strategic.classify(strategy_class_name)}Strategy"
+          strategy_class = class_eval(class_name)
+        rescue NameError
+          # No Op
+        end
       end
-      class_name ||= "::#{self.name}::#{Strategic.classify(strategy_class_name)}Strategy"
-      class_eval(class_name)
-    rescue NameError
-      self
+      strategy_class ||= strategies.detect { |strategy| strategy.strategy_aliases.include?(string_or_class_or_object) }
+      strategy_class ||= self
     end
 
     def new_strategy(string_or_class_or_object, *args, &block)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strategic
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Andy Maleh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-01-27 00:00:00.000000000 Z
+date: 2021-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -56,14 +56,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
@@ -86,42 +86,56 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.16.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.16.1
 - !ruby/object:Gem::Dependency
-  name: puts_debuggerer
+  name: simplecov-lcov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.7.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: puts_debuggerer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.1
 description: |
   if/case conditionals can get really hairy in highly sophisticated business domains.
   Domain model inheritance can help remedy the problem, but you don't want to dump all
@@ -139,9 +153,11 @@ email: andy.am@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/strategic.rb
@@ -149,7 +165,7 @@ homepage: http://github.com/AndyObtiva/strategic
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -164,9 +180,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.10
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Painless Strategy Pattern for Ruby and Rails
 test_files: []