aye_commander 1.0.0

data/lib/aye_commander/limitable.rb

@@ -0,0 +1,83 @@
+module AyeCommander
+  # This module takes care of command arguments being limited by the user
+  # specifics.
+  module Limitable
+    # Limitable is a module which functionality is completely defined at class
+    # level.
+    module ClassMethods
+      LIMITERS = %i(receives requires returns).freeze
+
+      # Contains all the limiters
+      def limiters
+        @limiters ||= Hash.new([])
+      end
+
+      # Helps the command define methods to not use method missing on every
+      # instance.
+      #
+      # The original idea was to encourage to use uses for a small performance
+      # boost when running their commands since the methods would be created at
+      # load time.
+      # This idea has been since scrapped since it would make the commands look
+      # very convoluted and the performance hit is probably neglegible since
+      # the methods themselves are defined after the first method missing.
+      #
+      # The functionality however still remains as limited call this method
+      # internally
+      def uses(*args)
+        uses = limiters[:uses]
+        return uses if args.empty?
+
+        missing = args - uses
+        attr_accessor(*missing) if missing.any?
+
+        limiters[:uses] |= args
+      end
+
+      # Defines .receives .requires and .returns
+      # .receives Tells the command which arguments are expected to be received
+      # .requires Tells the command which arguments are actually required
+      # .returns  Tells the command which arguments to return in the result
+      LIMITERS.each do |limiter|
+        define_method(limiter) do |*args|
+          return limiters[__method__] if args.empty?
+          uses(*args)
+          limiters[__method__] |= args
+        end
+      end
+
+      # Helper method that tells the result class which methods to create as
+      # readers the first time it is created.
+      def readers
+        [:status] | uses
+      end
+
+      # Validates the limiter arguments
+      def validate_arguments(args, skip_validations: false)
+        unless [true, :requires].include?(skip_validations) || requires.empty?
+          validate_required_arguments(args)
+        end
+
+        unless [true, :receives].include?(skip_validations) || receives.empty?
+          validate_received_arguments(args)
+        end
+      end
+
+      # Validates the required arguments
+      # Required arguments are ones that your commander absolutely needs to be
+      # able to run properly.
+      def validate_required_arguments(args)
+        missing = requires - args.keys
+        raise MissingRequiredArgumentError, missing if missing.any?
+      end
+
+      # Validates the received arguments
+      # Received arguments are the ones that your command is able to receive.
+      # Any other argument not defined by this would be considered an error.
+      def validate_received_arguments(args)
+        extras = args.keys - (receives | requires)
+        raise UnexpectedReceivedArgumentError, extras if extras.any?
+      end
+    end
+  end
+end

data/lib/aye_commander/resultable.rb

@@ -0,0 +1,58 @@
+module AyeCommander
+  # This module helps the command return a special class, the Result which is
+  # typically what the command responds with.
+  module Resultable
+    # Most of the functionality is at class level since it receives several
+    # class instance variables.
+    module ClassMethods
+      # Returns a result based on the skip_cleanup option
+      # skip_cleanup
+      #   false    (Default) Returns a result taking returns in account
+      #   true     Returns the result skipping the cleanup.
+      #   :command Using this option asks to get the command instance rather
+      #            than a result. This of course means the command is not clean.
+      def result(command, skip_cleanup = false)
+        case skip_cleanup
+        when :command
+          command
+        when true
+          new_result(command.to_hash)
+        else
+          new_result(command.to_result_hash)
+        end
+      end
+
+      # Creates a new instance of a Command::Result with the received values
+      # and returns it.
+      def new_result(values)
+        result_class.new(values)
+      end
+
+      # Returns and/or defines the Result class to be returned by the current
+      # command.
+      # This class is created under the namespace of the command so the end
+      # result looks pretty damn cool in my opinion.
+      # Eg: Command::Result
+      def result_class
+        const_defined?('Result') ? const_get('Result') : define_result_class
+      end
+
+      private
+
+      # Defines the result class with the necessary modules so it can behave
+      # like a result
+      def define_result_class
+        readers = self.readers
+        result = Class.new do
+          include Initializable
+          include Inspectable
+          include Status::Readable
+          include Ivar::Readable
+          extend  Ivar::ClassMethods
+          attr_reader(*readers)
+        end
+        const_set 'Result', result
+      end
+    end
+  end
+end

data/lib/aye_commander/shareable.rb

@@ -0,0 +1,32 @@
+module AyeCommander
+  module Shareable
+    # This module serves to make sure that when included or inherited everything
+    # related to the command is preserved
+    # Prepend is not really supported, but you really shouldnt be prepending a
+    # command so... meh
+    module ClassMethods
+      # This ensures that class methods are extended when Command is included
+      def included(includer)
+        super
+        includer.extend AyeCommander::Command::ClassMethods
+        %i(@limiters @succeeds @hooks).each do |var|
+          if instance_variable_defined? var
+            includer.instance_variable_set var, instance_variable_get(var)
+          end
+        end
+      end
+
+      # Rubys object model already links the ancestry path of singleton classes
+      # when using classic inheritance so no need to extend. Just need to add
+      # the variables to the inheriter.
+      def inherited(inheriter)
+        super
+        %i(@limiters @succeeds @hooks).each do |var|
+          if instance_variable_defined? var
+            inheriter.instance_variable_set var, instance_variable_get(var)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aye_commander/status.rb

@@ -0,0 +1,48 @@
+module AyeCommander
+  # This module helps Command and Result to be able to respond to various
+  # status and status responses.
+  module Status
+    DEFAULT = :success
+
+    # Status related class Methods to be included
+    module ClassMethods
+      # Returns and/or initializes the :@succeeds class instance variable
+      def succeeds
+        @succeeds ||= [DEFAULT]
+      end
+
+      # Adds extra succeeds status other than success.
+      # Use exclude_success: true if for whathever reason you don't want
+      # :success to be a successful status.
+      def succeeds_with(*args, exclude_success: false)
+        @succeeds = succeeds | args
+        @succeeds.delete(DEFAULT) if exclude_success
+      end
+    end
+
+    # This module defines methods that allow to read and know about the status
+    module Readable
+      attr_reader :status
+
+      # Whether or not the command is succesful
+      def success?
+        self.class.succeeds.include?(status)
+      end
+
+      # Boolean opposite of success
+      def failure?
+        !success?
+      end
+    end
+
+    # This module defines methods that allow to modify the status
+    module Writeable
+      attr_writer :status
+
+      # Fails the status
+      def fail!(status = :failure)
+        @status = status
+      end
+    end
+  end
+end

data/lib/aye_commander/version.rb

@@ -0,0 +1,3 @@
+module AyeCommander
+  VERSION = '1.0.0'.freeze
+end

data/spec/aye_commander/abortable_spec.rb

@@ -0,0 +1,24 @@
+describe AyeCommander::Abortable::ClassMethods do
+  include_context :command
+
+  context '.abortable' do
+    it 'does nothing if nothing happens' do
+      expect { command.abortable { :nothing } }.to_not raise_error
+    end
+
+    it 'is able to catch throw(:abort!)' do
+      expect { command.abortable { throw :abort! } }.to_not raise_error
+    end
+  end
+end
+
+describe AyeCommander::Abortable do
+  include_context :command
+
+  context '#abort' do
+    it 'throws with :abort! symbol' do
+      expect(instance).to receive(:throw).with(:abort!, :aborted)
+      instance.abort!
+    end
+  end
+end

data/spec/aye_commander/callable_spec.rb

@@ -0,0 +1,47 @@
+describe AyeCommander::Callable::ClassMethods do
+  include_context :command
+
+  context '.call' do
+    let(:args) { { some: :other, irrelevant: :args } }
+
+    it 'calls several methods in a specific order' do
+      expect(command).to  receive(:new).with(args).and_return(instance)
+      expect(command).to  receive(:validate_arguments).with(args)
+      expect(command).to  receive(:abortable)
+      expect(command).to  receive(:result).with(instance, false)
+      command.call(args)
+    end
+
+    it 'runs the aborted hooks if command was aborted' do
+      allow(command).to  receive(:call_before_hooks) { throw :abort!, :aborted }
+      expect(command).to receive(:call_aborted_hooks)
+      command.call(args)
+    end
+
+    it 'calls several methods in the abortable block' do
+      allow(command).to   receive(:new).and_return(instance)
+      expect(command).to  receive(:call_before_hooks)
+      expect(instance).to receive(:call)
+      expect(command).to  receive(:call_after_hooks)
+      expect(command).to_not receive(:call_aborted_hooks)
+      command.call(args)
+    end
+
+    it 'calls around hooks only if they exist' do
+      command.around { :something }
+      allow(command).to  receive(:new).and_return(instance)
+      expect(command).to receive(:call_around_hooks)
+      command.call(args)
+    end
+  end
+end
+
+describe AyeCommander::Callable do
+  include_context :command
+
+  context '#call' do
+    it 'exists' do
+      expect(instance).to respond_to :call
+    end
+  end
+end

data/spec/aye_commander/command_spec.rb

@@ -0,0 +1,27 @@
+describe AyeCommander::Command do
+  include_context :command
+
+  context 'a command' do
+    it 'includes the necessary instance modules' do
+      expect(command).to include AyeCommander::Abortable
+      expect(command).to include AyeCommander::Callable
+      expect(command).to include AyeCommander::Initializable
+      expect(command).to include AyeCommander::Inspectable
+      expect(command).to include AyeCommander::Ivar::Readable
+      expect(command).to include AyeCommander::Ivar::Writeable
+      expect(command).to include AyeCommander::Status::Readable
+      expect(command).to include AyeCommander::Status::Writeable
+    end
+
+    it 'includes the necessary class modules' do
+      expect(commandsc).to include AyeCommander::Abortable::ClassMethods
+      expect(commandsc).to include AyeCommander::Callable::ClassMethods
+      expect(commandsc).to include AyeCommander::Hookable::ClassMethods
+      expect(commandsc).to include AyeCommander::Ivar::ClassMethods
+      expect(commandsc).to include AyeCommander::Limitable::ClassMethods
+      expect(commandsc).to include AyeCommander::Resultable::ClassMethods
+      expect(commandsc).to include AyeCommander::Shareable::ClassMethods
+      expect(commandsc).to include AyeCommander::Status::ClassMethods
+    end
+  end
+end

data/spec/aye_commander/commander_spec.rb

@@ -0,0 +1,168 @@
+describe AyeCommander::Commander::ClassMethods do
+  include_context :commander
+
+  context '.included' do
+    it 'includes Commanders Class Methods when included' do
+      expect(commander.singleton_class).to include AyeCommander::Commander::ClassMethods
+    end
+
+    it 'includes the necessary modules even further down the line' do
+      expect(includer2).to include AyeCommander::Commander
+      expect(includer2.singleton_class).to include AyeCommander::Commander::ClassMethods
+    end
+
+    it 'saves the necessary instance variables for the commander' do
+      includer.execute :taco, :burrito
+      expect(includer2.executes).to eq %i(taco burrito)
+    end
+  end
+
+  context '.inherited' do
+    it 'includes the necessary modules even further down the line' do
+      expect(inheriter).to include AyeCommander::Commander
+      expect(inheriter.singleton_class).to include AyeCommander::Commander::ClassMethods
+    end
+
+    it 'saves the necessary instance variables for the commander' do
+      commander.execute :taco, :burrito
+      expect(inheriter.executes).to eq %i(taco burrito)
+    end
+  end
+
+  context '.call' do
+    it 'calls several methods' do
+      expect(commander).to receive(:prepare_commander_result)
+      expect(commander).to receive(:result).twice
+      commander.call
+    end
+  end
+
+  context '.prepare_commander_result' do
+    it 'cleans up the commander after being called' do
+      commander.execute(command)
+      result = commander.call(taco: :bell)
+      expect(result.instance_variables).to include :@status
+      expect(result.instance_variables).to include :@executed
+      expect(result.instance_variables).to include :@taco
+      expect(result.instance_variables).to_not include :@command
+    end
+  end
+
+  context '.command' do
+    it 'gives an anonymous class that includes Command' do
+      expect(commander.command).to be_instance_of Class
+      expect(commander.command).to include AyeCommander::Command
+    end
+
+    it 'always returns the same one per commander' do
+      expect(commander.command.object_id).to eq commander.command.object_id
+    end
+  end
+
+  context '.execute' do
+    it 'adds the received arguments to the executes array' do
+      commander.execute :taco, :burrito
+      expect(commander.executes).to eq %i(taco burrito)
+    end
+  end
+
+  context '.executes' do
+    it 'returns an empty array if it has not been initialized' do
+      expect(commander.executes).to be_empty
+    end
+
+    it 'returns the content of the class instance variable executes' do
+      commander.instance_variable_set :@executes, :random
+      expect(commander.executes).to eq :random
+    end
+  end
+
+  context '.abort_on_failure' do
+    it 'sets the @abort_on_failure to true when called without arguments' do
+      commander.abort_on_failure
+      expect(commander.instance_variable_get(:@abort_on_failure)).to be true
+    end
+
+    it 'sets the @abort_on_failure to the received argument' do
+      commander.abort_on_failure false
+      expect(commander.instance_variable_get(:@abort_on_failure)).to be false
+    end
+  end
+
+  context '.abort_on_failure?' do
+    it 'returns @abort_on_failure' do
+      expect(commander.abort_on_failure?).to be_nil
+      commander.abort_on_failure true
+      expect(commander.abort_on_failure?).to be true
+    end
+  end
+end
+
+describe AyeCommander::Commander do
+  include_context :commander
+
+  context '#initialize' do
+    it 'initializes the commander with the required variables' do
+      ci = commander.new(taco: :potato)
+      expect(ci.command).to be_instance_of commander.command
+      expect(ci.executed).to eq []
+    end
+  end
+
+  context '#call' do
+    it 'executes the comamnds in the order they were received' do
+      commander.execute(1, 1, 1)
+      expect(instance).to receive(:execute).with(1, 1, 1, abort_on_failure: true)
+      instance.call
+    end
+  end
+
+  context '#execute' do
+    before do
+      commander.class_eval { public :execute }
+    end
+
+    it 'calls the command with the result of the previous command' do
+      expect(instance.command).to receive(:to_hash).and_return(hello: :world)
+      instance.execute(command)
+    end
+
+    it 'updates the command variable to the last executed command instance' do
+      allow(command).to receive(:call).and_return(commandi)
+      instance.execute(command)
+      expect(instance.command).to eq commandi
+    end
+
+    it 'pushes the command to the executed array' do
+      allow(command).to receive(:call).and_return(commandi)
+      instance.execute(command)
+      expect(instance.executed).to eq [commandi]
+    end
+
+    it 'calls fail! and abort! if command fails and with abort_on_failure option' do
+      allow(command).to receive(:call).and_return(commandi)
+      commandi.fail!
+
+      expect(instance).to receive(:fail!)
+      expect(instance).to receive(:abort!)
+      instance.execute(command, abort_on_failure: true)
+    end
+
+    it 'doesnt calls fail! and abort! even if command fails and without abort_on_failure option' do
+      allow(command).to receive(:call).and_return(commandi)
+      commandi.fail!
+
+      expect(instance).to_not receive(:fail!)
+      expect(instance).to_not receive(:abort!)
+      instance.execute(command)
+    end
+
+    it 'doesnt calls fail! and abort! if command succeeds even with abort_on_failure option' do
+      allow(command).to receive(:call).and_return(commandi)
+
+      expect(instance).to_not receive(:fail!)
+      expect(instance).to_not receive(:abort!)
+      instance.execute(command, abort_on_failure: true)
+    end
+  end
+end