simple_command_dispatcher 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 978601fab3ba1ceb4f717b3b4d1d6fb13ea649f0
-  data.tar.gz: ceae85997bb18d8479845f89bf324c4d15fd4eb6
+  metadata.gz: 86113bb49021916a8a1352875961117ee7323c31
+  data.tar.gz: b3341892eaeba98ec82a42795ac9b30e2dd2cb5d
 SHA512:
-  metadata.gz: 7df1d6310235fbe4ea04e82f95f7a00d40e5790ddaf8f6a4a1722cb59b642b2ba6b209231b4497ed81edfc0da9d214bb62e6bbf307b9ff415f2bfea53f7e01b6
-  data.tar.gz: 4272706508300aa3a2e7d0760c717e5621d4db0c73cab6736eb0a5f197c192c0b4696371bc307e8882ee52d6645691036c848a8ae761c52691bb2e9004ad8b97
+  metadata.gz: 2a147390f419be6ae76819fc5b781d05ff330fe60ab8ae6104251de6e4abb5c05c8603e3a5bbc6fbbb5aa092c15abe42deb147d20a7c3c2ad575c46d9c111c08
+  data.tar.gz: cf4ca4296568d38f35959730967c6030dd511b9099f14dc8682d356bf9cf7e26df138d7ed7d3b38b58d810d9b3b05822ba1dfaaaf4e90aedc9ef33fd6d3c5690

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+### Version 1.2.1
+* Configuration class
+  * Added the new Configuration class that exposes the #allow_custom_classes property which takes a Boolean allowing/disallowing the use of custom commands to be used. See the documentation for details and usage.
+* Custom commands
+  * Allow ability for users to use custom commands (i.e. classes that do not prepend the SimpleCommand module) as long as the command class respond_to? the ::call public class method. Note: Configuration#allow_custom_commands must be set to true to use custom commands.
+* Documentation updates
+  * Add documentation for new Configuration class and miscellaneous other code additions/changes.
+
+### Version 1.1.1
+* Documentation updates
+  * Add example code in README.md to include clarification on command namespacing, and how to autoload command classes to avoid NameError exceptions when SimpleCommand::Dispatcher.call(...) is call due to uninitialized command constants.
+
+## Version 1.1.0 - 2016-11-01 [YANKED]
+## Version 1.0.0 - 2016-11-01 [YANKED]
+## Version 0.2.0 - 2016-11-01 [YANKED]
+## Version 0.1.3 - 2016-11-01 [YANKED]
+## Version 0.1.2 - 2016-10-29 [YANKED]
+## Version 0.1.1 - 2016-10-29 [YANKED]
+## Version 0.1.0 - 2016-10-29 [YANKED]

data/README.md

@@ -1,11 +1,22 @@
 [![GitHub version](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher.svg)](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
 [![Gem Version](https://badge.fury.io/rb/simple_command_dispatcher.svg)](https://badge.fury.io/rb/simple_command_dispatcher)
 
+![](http://ruby-gem-downloads-badge.herokuapp.com/simple_command_dispatcher?type=total)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/simple_command_dispatcher/)
+
+[![Report Issues](https://img.shields.io/badge/report-issues-red.svg)](https://github.com/gangelo/simple_command_dispatcher/issues)
+
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+
 # Q. simple_command_dispatcher - what is it?
 # A. It's a Ruby gem!
 
 ## Overview
-__simple_command_dispatcher__ (SCD) allows you to execute __simple_command__ commands in a more dynamic way. If you are not familiar with the _simple_command_ gem, check it out [here][simple-command]. SCD was written specifically with the [rails-api][rails-api] in mind; however, you can use SDC wherever you use simple_command commands. 
+__simple_command_dispatcher__ (SCD) allows you to execute __simple_command__ commands (and now _custom commands_ as of version 1.2.1) in a more dynamic way. If you are not familiar with the _simple_command_ gem, check it out [here][simple-command]. SCD was written specifically with the [rails-api][rails-api] in mind; however, you can use SDC wherever you would use simple_command commands. 
+
+## Update as of Version 1.2.1
+### Custom Commands
+SCD now allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true` (see the __Custom Commands__ section below for details).
 
 ## Example
 The below example is from a `rails-api` API that uses token-based authentication and services two mobile applications, identified as *__my_app1__* and *__my_app2__*, in this example.
@@ -124,6 +135,12 @@ Rails.application.config.to_prepare do
    ActionDispatch::Reloader.to_prepare { reloader.execute_if_updated }
    reloader.execute
 end
+
+# Optionally set our configuration setting to allow
+# for custom command execution.
+SimpleCommand::Dispatcher.configure do |config|
+   config.allow_custom_commands = true
+end 
 ```
 
 ```ruby 
@@ -169,6 +186,90 @@ class ApplicationController < ActionController::API
 end
 ```
 
+## Custom Commands
+
+As of __Version 1.2.1__ simple_command_dispatcher (SCD) allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true`.
+
+In order to execute _custom commands_, there are three (3) requirements:
+   1. Create a _custom command_. Your _custom command_ class must expose a public `::call` class method.
+   2. Set the `Configuration#allow_custom_commands` property to `true`.
+   3. Execute your _custom command_ by calling the `::call` class method. 
+
+### Custom Command Example
+
+#### 1. Create a Custom Command
+```ruby
+# /api/my_app/v1/custom_command.rb
+
+module Api
+   module MyApp
+         module V1
+
+            # This is a custom command that does not prepend SimpleCommand.
+            class CustomCommand
+               
+               def self.call(*args)
+                  command = self.new(*args)
+                  if command
+                     command.send(:execute)
+                  else
+                     false
+                  end
+               end
+               
+               private
+
+               def initialize(params = {})
+                  @param1 = params[:param1]
+               end
+
+               private
+
+               attr_accessor :param1
+
+               def execute
+                  if (param1 == :param1)
+                     return true
+                  end
+
+                  return false
+               end
+            end
+
+      end
+   end
+end
+```
+#### 2. Set the `Configuration#allow_custom_commands` property to `true`
+```ruby
+# In your rails, rails-api app, etc...
+# /config/initializers/simple_command_dispatcher.rb
+
+SimpleCommand::Dispatcher.configure do |config|
+    config.allow_custom_commands = true
+end 
+```
+
+#### 3. Execute your _Custom Command_
+Executing your _custom command_ is no different than executing a __SimpleCommand__ command with the exception that you must properly handle the return object that results from calling your _custom command_; being a _custom command_, there is no guarantee that the return object will be the command object as is the case when calling a SimpleCommand command.
+```ruby
+# /app/controllers/some_controller.rb
+
+require 'simple_command_dispatcher'
+
+class SomeController < ApplicationController::API
+   public
+   
+   def some_api
+      success = SimpleCommand::Dispatcher.call(:CustomCommand, get_command_path, { camelize: true}, request.headers)
+      if success
+         # Do something...
+      else
+         # Do something else...
+      end
+    end
+end
+```
 
 ## Installation
 

data/lib/core_extensions/string.rb

@@ -1,4 +1,7 @@
 class String
+	# Returns a copy of string with all spaces removed.
+	#   
+	# @return [String] with all spaces trimmed which includes all leading, trailing and embedded spaces.
    def trim_all
       self.gsub(/\s+/, "")
    end

data/lib/simple_command_dispatcher.rb

@@ -13,9 +13,9 @@ end
 
 module SimpleCommand
    
-   # Provides a way to call SimpleCommand commands in a more dymanic manner.
+   # Provides a way to call SimpleCommands or your own custom commands in a more dymanic manner.
    #
-   # For information about the simple_command gem, visit https://rubygems.org/gems/simple_command
+   # For information about the simple_command gem, visit {https://rubygems.org/gems/simple_command}
    #
    module Dispatcher
       
@@ -24,9 +24,9 @@ module SimpleCommand
 
          public
 
-         # Calls a *SimpleCommand* given the command name, the modules the command belongs to and the parameters to pass to the command.
+         # Calls a *SimpleCommand* or *Command* given the command name, the modules the command belongs to and the parameters to pass to the command.
          #
-         # @param command [Symbol, String] the name of the SimpleCommand to call.
+         # @param command [Symbol, String] the name of the SimpleCommand or Command to call.
          #
          # @param command_modules [Hash, Array] the ruby modules that qualify the SimpleCommand to call. When passing a Hash, the Hash 
          #    keys serve as documentation only. For example, ['Api', 'AppName', 'V1'] and { :api :Api, app_name: :AppName, api_version: :V1 }
@@ -41,10 +41,10 @@ module SimpleCommand
          # @option options [Boolean] :module_titleize (false) determines whether or not module names should be titleized.
          # @option options [Boolean] :module_camelized (false) determines whether or not module names should be camelized.
          #
-         # @param command_parameters [*] the parameters to pass to the call method of the SimpleCommand. This parameter is simply
-         #    passed through to the call method of the SimpleCommand.
+         # @param command_parameters [Array<Symbol>] the parameters to pass to the call method of the SimpleCommand . This parameter is simply
+         #    passed through to the call method of the SimpleCommand/Command.
          #
-         # @return [SimpleCommand] the SimpleCommand returned as a result from calling the SimpleCommand#call method.
+         # @return [SimpleCommand, Object] the SimpleCommand or Object returned as a result of calling the SimpleCommand#call method or the Command#call method respectfully.
          #
          # @example
          #     
@@ -61,33 +61,67 @@ module SimpleCommand
          def call(command = "", command_modules = {}, options = {}, *command_parameters)
 
             # Create a constantized class from our command and command_modules...
-            simple_command_class_constant = to_constantized_class(command, command_modules, options)
+            command_class_constant = to_constantized_class(command, command_modules, options)
 
-            # Calling is_simple_command? returns true if the class pointed to by
-            # simple_command_class_constant is a valid SimpleCommand class; that is, 
-            # if it prepends module SimpleCommand::ClassMethods.
-            if !is_simple_command?(simple_command_class_constant) 
-               raise ArgumentError.new('Class does not prepend module SimpleCommand.')
+            # If we're NOT allowing custom commands, make sure we're dealing with a a command class
+            # that prepends the SimpleCommand module.
+            if !SimpleCommand::Dispatcher.configuration.allow_custom_commands  
+               # Calling is_simple_command? returns true if the class pointed to by
+               # command_class_constant is a valid SimpleCommand class; that is, 
+               # if it prepends module SimpleCommand::ClassMethods.
+               if !is_simple_command?(command_class_constant) 
+                  raise ArgumentError.new("Class \"#{command_class_constant}\" must prepend module SimpleCommand if Configuration#allow_custom_commands is true.")
+               end
             end
 
-            # We know we have a valid SimpleCommand; all we need to do is call #call,
-            # pass the command_parameter variable arguments to the call, and return the results.
-            simple_command_class_constant.call(*command_parameters)
+            if is_valid_command(command_class_constant)
+               # We know we have a valid SimpleCommand; all we need to do is call #call,
+               # pass the command_parameter variable arguments to the call, and return the results.
+               run_command(command_class_constant, command_parameters)
+            else
+               raise NameError.new("Class \"#{command_class_constant}\" does not respond_to? method ::call.")
+            end
          end
 
          private
 
-         # @!visibility public
+         # Returns true or false depending on whether or not the class constant has a public 
+         # class method named ::call defined. Commands that do not have a public class method
+         # named ::call, are considered invalid.
+         #
+         # @param klass_constant [String] a class constant that will be validated to see whether or not the class is a valid command.
+         #
+         # @return [Boolean] true if klass_constant has a public class method named ::call defined, false otherwise.
          #
+         # @!visibility public
+         def is_valid_command(klass_constant)
+            klass_constant.eigenclass.public_method_defined?(:call)
+         end
+
          # Returns true or false depending on whether or not the class constant prepends module SimpleCommand::ClassMethods.
          #
          # @param klass_constant [String] a class constant that will be validated to see whether or not the class prepends module SimpleCommand::ClassMethods.
          #
          # @return [Boolean] true if klass_constant prepends Module SimpleCommand::ClassMethods, false otherwise.
          #
+         # @!visibility public
          def is_simple_command?(klass_constant)
             klass_constant.eigenclass.included_modules.include? SimpleCommand::ClassMethods
          end
+
+         # Runs the command given the parameters and returns the result.
+         #
+         # @param klass_constant [String] a class constant that will be called.
+         # @param parameters [Array] an array of parameters to pass to the command that will be called.
+         #
+         # @return [Object] returns the object (if any) that results from calling the command.
+         #
+         # @!visibility public
+         def run_command(klass_constant, parameters)
+            klass_constant.call(*parameters)
+         #rescue NameError
+         #   raise NameError.new("Class \"#{klass_constant}\" does not respond_to? method ::call.")
+         end
       end
    end
 end

data/lib/simple_command_dispatcher/configuration.rb

@@ -0,0 +1,45 @@
+module SimpleCommand
+	module Dispatcher
+
+      # Gem configuration settings class. Use this class to configure this gem.
+      #
+      # To configure this gem in your application, simply add the following code in your application and set the
+      # appropriate configuration settings.
+      #
+      # @example
+      #
+      #    SimpleCommand::Dispatcher.configure do |config|
+      #       config.allow_custom_commands = true
+      #    end 
+      #
+  		class Configuration
+         # Gets/sets the *allow_custom_commands* configuration setting (defaults to false). 
+         # If this setting is set to *false*, only command classes that prepend the *SimpleCommand* module
+         # will be considered acceptable to run, all other command classes will fail to run. If this
+         # setting is set to *true*, any command class will be considered acceptable to run, regardless of
+         # whether or not the class prepends the *SimpleCommand* module.
+         #
+         # For information about the simple_command gem, visit {https://rubygems.org/gems/simple_command}
+         #
+         # @return [Boolean] the value.
+         #
+  			attr_accessor :allow_custom_commands
+
+  			def initialize
+  				# The default is to use any command that exposes a ::call class method.
+      		reset
+    		end
+
+         public
+
+         # Resets the configuration to use the default values.
+         #
+         # @return [nil] returns nil.
+         #
+    		def reset
+    			@allow_custom_commands = false
+            nil
+    		end
+  		end
+	end
+end

data/lib/simple_command_dispatcher/configure.rb

@@ -0,0 +1,18 @@
+module SimpleCommand
+	module Dispatcher
+		class << self
+    		attr_writer :configuration
+  		end
+
+  		# Returns the application configuration object.
+  		#
+  		# @return [Configuration] the application Configuration object.
+  		def self.configuration
+    		@configuration ||= Configuration.new
+  		end
+
+		def self.configure
+			yield(configuration)
+		end
+	end
+end

data/lib/simple_command_dispatcher/klass_transform.rb

@@ -199,7 +199,7 @@ module SimpleCommand
       #
       def validate_klass(klass, options)
          if !(klass.is_a?(Symbol) || klass.is_a?(String))
-            raise ArgumentError.new('Class is not a String or Symbol. Class must equal the name of the SimpleCommand to call in the form of a String or Symbol.')
+            raise ArgumentError.new('Class is not a String or Symbol. Class must equal the class name of the SimpleCommand or Command to call in the form of a String or Symbol.')
          end
 
          klass = klass.to_s.strip

data/lib/simple_command_dispatcher/version.rb

@@ -1,5 +1,5 @@
 module SimpleCommand
 	module Dispatcher
-  		VERSION = "1.1.1"
+  		VERSION = "1.2.1"
   	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_command_dispatcher
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-02 00:00:00.000000000 Z
+date: 2017-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -144,7 +144,7 @@ files:
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
-- CHANGELOG.mb
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -154,6 +154,8 @@ files:
 - bin/setup
 - lib/core_extensions/string.rb
 - lib/simple_command_dispatcher.rb
+- lib/simple_command_dispatcher/configuration.rb
+- lib/simple_command_dispatcher/configure.rb
 - lib/simple_command_dispatcher/klass_transform.rb
 - lib/simple_command_dispatcher/version.rb
 - lib/tasks/simple_command_dispatcher_sandbox.rake

data/CHANGELOG.mb

@@ -1,32 +0,0 @@
-### Unreleased
-* Upcoming features
-  * whitelist for allowable namespaces
-
-### 1.1.1
-* Documentation updates
-  * Add example code in README.md to include clarification on command namespacing, and how to autoload command classes to avoid NameError exceptions when SimpleCommand::Dispatcher.call(...) is call due to uninitialized command constants.
-
-### 1.1.0
-* Bug fix lib/core_extensions/string.rb not included in SimpleCommand::Dispatcher, causing exception.
-
-### 1.0.0
-* Limit support to ruby >= 2.2.2
-
-### 0.2.0
-* Yanked
-
-### 0.1.3
-* Documentation updates
-* Add `SimpleCommand::KlassTransform` rake task sandbox to test the below listed `SimpleCommand::KlassTransform` members; run the rake tasks for usage; these rake tasks are simply a playground to see how simple_command_dispatcher transforms parameters into output when calling SimpleCommand::Dispatcher.call(...):
-  * `SimpleCommand::KlassTransform#to_class_string`
-    * $ rake to_class_string 
-  * `SimpleCommand::KlassTransform#to_modules_string`
-    * $ rake to_modules_string 
-  * `SimpleCommand::KlassTransform#to_constantized_class_string`
-    * $ rake to_constantized_class_string 
-
-### 0.1.2
-* Documentation updates
-
-### 0.1.1
-* Documentation updates