aye_commander 1.0.0

data/lib/aye_commander.rb

@@ -0,0 +1,19 @@
+require 'aye_commander/abortable'
+require 'aye_commander/callable'
+require 'aye_commander/hookable'
+require 'aye_commander/initializable'
+require 'aye_commander/inspectable'
+require 'aye_commander/ivar'
+require 'aye_commander/limitable'
+require 'aye_commander/shareable'
+require 'aye_commander/status'
+require 'aye_commander/errors'
+
+require 'aye_commander/resultable'
+require 'aye_commander/command'
+require 'aye_commander/commander'
+
+# AyeCommander is a (hopefully) easy to use gem that helps develop classes that
+# follow the command pattern.
+module AyeCommander
+end

data/lib/aye_commander/abortable.rb

@@ -0,0 +1,25 @@
+module AyeCommander
+  # This module helps a command to stop the code flow completely and return the
+  # result immediately.
+  # It is specially useful when your command is running on more deeply nested
+  # code (Eg: private methods called by call)
+  #
+  # It also uses, what is probably one of the most underused features of ruby:
+  # catch and throw.
+  module Abortable
+    # Abortable just comes with a class method that is basically a wrapper for
+    # catch and throw.
+    module ClassMethods
+      # .abortable receives a block and yields it inside a catch so that abort!
+      # can be safely called.
+      def abortable
+        catch(:abort!) { yield }
+      end
+    end
+
+    # #abort! throws an :abort! to stop the current command flow on its tracks
+    def abort!
+      throw :abort!, :aborted
+    end
+  end
+end

data/lib/aye_commander/callable.rb

@@ -0,0 +1,41 @@
+module AyeCommander
+  # This module takes care of both .call and #call, the most important methods
+  # in a command
+  module Callable
+    # Class Methods defined by callable
+    module ClassMethods
+      # .call is what the user calls when he wants to run his commands. It is
+      # able to receive several named arguments, and a couple of options for
+      # specific behavior on how the command must be run.
+      #
+      # Options
+      # skip_validations: (Handled by validate_arguments)
+      #   true      Skips both :receives and :requires argument validations
+      #   :requires Skips :requires argument validation
+      #   :receives Skips :receives argument validation
+      #
+      # skip_cleanup:
+      #   true     Skips the result cleanup so it has all the instance variables
+      #            that were declared
+      #   :command Returns the command instead of an instance of the result
+      #            class
+      def call(skip_cleanup: false, **args)
+        command = new(args)
+        validate_arguments(args)
+        aborted = abortable do
+          call_before_hooks(command)
+          around_hooks.any? ? call_around_hooks(command) : command.call
+          call_after_hooks(command)
+        end
+        abortable { call_aborted_hooks(command) } if aborted == :aborted
+        result(command, skip_cleanup)
+      end
+    end
+
+    # #call is what a user redefines in their own command, and what he
+    # customizes to give a command the behavior he desires.
+    # An empty call is defined in a command so they can be run even without one.
+    def call
+    end
+  end
+end

data/lib/aye_commander/command.rb

@@ -0,0 +1,30 @@
+module AyeCommander
+  # This is the meat of AyeComander, what the user has to include in his own
+  # commands for everything to work.
+  module Command
+    # Class Methods that define the functionality of a command.
+    # The most complex functionality is in fact contained at class level since
+    # I wanted to preserve the commands as clean as possible to avoid name
+    # clashes within the instance.
+    module ClassMethods
+      include Abortable::ClassMethods
+      include Callable::ClassMethods
+      include Hookable::ClassMethods
+      include Ivar::ClassMethods
+      include Limitable::ClassMethods
+      include Resultable::ClassMethods
+      include Shareable::ClassMethods
+      include Status::ClassMethods
+    end
+
+    include Abortable
+    include Callable
+    include Initializable
+    include Inspectable
+    include Ivar::Readable
+    include Ivar::Writeable
+    include Status::Readable
+    include Status::Writeable
+    extend ClassMethods
+  end
+end

data/lib/aye_commander/commander.rb

@@ -0,0 +1,120 @@
+module AyeCommander
+  # Commander is a special command that lets you run several command in a
+  # succession. At the end it returns its own result containing a hash with
+  # the commands run.
+  module Commander
+    # Eventhough the Commander is basically a Command, it does come with some
+    # minor tweaking to keep it simple to understand and consistant
+    module ClassMethods
+      # This ensure that Commander specific class methods and commander specific
+      # class instance variables are included when the Commander is included
+      def included(includer)
+        super
+        includer.extend ClassMethods
+        includer.instance_variable_set :@executes, @executes
+        includer.instance_variable_set :@abort_on_failure, @abort_on_failure
+      end
+
+      # This ensures that Commander specific instance variables become available
+      # for any class inheriting from another that includes the command
+      def inherited(inheriter)
+        super
+        inheriter.instance_variable_set :@executes, @executes
+        inheriter.instance_variable_set :@abort_on_failure, @abort_on_failure
+      end
+
+      # Override of Command.call
+      # It's almost identical to a normal command call, the only difference
+      # being that it has to prepare the commander result before sending it.
+      #
+      # This was previously done through hooks, but the idea was scrapped to
+      # avoid inconsistencies with the command instance variable during after
+      # and aborted hooks
+      def call(skip_cleanup: false, **args)
+        commander = super(skip_cleanup: :command, **args)
+        prepare_commander_result(commander)
+        result(commander, skip_cleanup)
+      end
+
+      # This method is always run before retuning the result of the commander
+      # It basically removes command instance variable since it's only relevant
+      # during the execution of the commander itself.
+      # It also assigns the ivars of the last executed command to itself.
+      def prepare_commander_result(commander)
+        commander.instance_exec do
+          command.to_hash.each do |name, value|
+            instance_variable_set to_ivar(name), value
+          end
+          remove!(:command)
+        end
+      end
+
+      # Returns an anonymous command class to be used to initialize the received
+      # commander args.
+      def command
+        @command ||= Class.new.send(:include, Command)
+      end
+
+      # Adds the received arguments to the executes array
+      def execute(*args)
+        executes.concat(args)
+      end
+
+      # Returns the executes array
+      def executes
+        @executes ||= []
+      end
+
+      # Can be used to set a default behavior of a Commander that overwrites
+      # call.
+      def abort_on_failure(value = true)
+        @abort_on_failure = value
+      end
+
+      # Returns the abort_on_failure
+      def abort_on_failure?
+        @abort_on_failure
+      end
+    end
+
+    include Command
+    extend ClassMethods
+
+    # A commander works with the following instance variables:
+    # command:  The last executed command. Will be an anonymous empty command at
+    #           the beginning
+    # executed: An array containing the executed commands
+    def initialize(**args)
+      super(command: self.class.command.new(args), executed: [])
+    end
+
+    # This is the default call for a commander
+    # It basically just executes the commands saved in the executes array.
+    # This however can be overwritten by the user and define their own logic
+    # to execute different commands
+    def call
+      execute(*self.class.executes, abort_on_failure: true)
+    end
+
+    private
+
+    # Execute will run the commands received, save the last executed command in
+    # @command instance variable and push it to the executed array.
+    #
+    # It also comes with an option to to abort the Commander in case one of the
+    # command run fails.
+    def execute(*commands, abort_on_failure: self.class.abort_on_failure?)
+      commands.each do |command_class|
+        args = command.to_hash
+        options = { skip_cleanup: :command, skip_validations: :receives }
+        @command = command_class.call(**args, **options)
+        executed.push(command)
+
+        if command.failure? && abort_on_failure
+          fail!
+          abort!
+        end
+      end
+    end
+  end
+end

data/lib/aye_commander/errors.rb

@@ -0,0 +1,24 @@
+module AyeCommander
+  # Core AyeCommander Error
+  class Error < RuntimeError
+    def initialize(info = nil)
+      @info = info
+    end
+  end
+
+  # Raised when command specifies 'requires' and one or more required arguments
+  # are missing when called.
+  class MissingRequiredArgumentError < Error
+    def message
+      "Missing required arguments: #{@info}"
+    end
+  end
+
+  # Raised when the command specifies 'receives' and receives one or more
+  # unexpected arguments
+  class UnexpectedReceivedArgumentError < Error
+    def message
+      "Received unexpected arguments: #{@info}"
+    end
+  end
+end

data/lib/aye_commander/hookable.rb

@@ -0,0 +1,82 @@
+module AyeCommander
+  # Hooks are available for all commands.
+  # They allow you to run specific parts of code before, around, after the
+  # command is called or when if the command was aborted
+  module Hookable
+    # All hook functionality is defined at a class level, but runs at instance
+    # level
+    module ClassMethods
+      TYPES = %i(before around after aborted).freeze
+
+      TYPES.each do |kind|
+        # Defines .before .around .after and .aborted
+        # Saves the received argument into their own array
+        #
+        # Options
+        # prepend: Makes it so that the received args are pushed to the front of
+        #          the hook array instead of the end.
+        define_method kind do |*args, prepend: false, &block|
+          args.push block if block
+          if prepend
+            hooks[kind] = args + hooks[kind]
+          else
+            hooks[kind] += args
+          end
+        end
+
+        # Defines .before_hooks .around_hooks .after_hooks and .aborted_hooks
+        # Public interface in case the user wants to see their defined hooks
+        define_method "#{kind}_hooks" do
+          hooks[kind]
+        end
+
+        # Defines .call_before_hooks .call_around_hooks .call_after_hooks and
+        # .call_aborted_hooks
+        # Calls the hooks one by one
+        define_method "call_#{kind}_hooks" do |command|
+          prepare_hooks(kind, command).each(&:call)
+        end
+      end
+
+      private
+
+      # Hash that saves the hooks
+      def hooks
+        @hooks ||= Hash.new([])
+      end
+
+      # Prepares the hooks so they can just be called.
+      # Before after and around hooks are similar in the sense that they just
+      # need to make all the received hooks callable and then they call
+      # themselves.
+      #
+      # Arounds on the other hand... they basically wrap themselves in procs so
+      # that you can call the proc inside the proc that gives the proc.
+      # Quite a headache.
+      # Why would you need multiple around blocks in the first place?
+      def prepare_hooks(kind, command)
+        hooks = callable_hooks(kind, command)
+        return hooks unless kind == :around
+
+        around_proc = hooks.reverse.reduce(command) do |callable, hook|
+          -> { hook.call(callable) }
+        end
+        [around_proc]
+      end
+
+      # Makes all the saved hooks callable in the command context
+      def callable_hooks(kind, command)
+        hooks[kind].map do |hook|
+          case hook
+          when Symbol
+            command.method(hook)
+          when Proc
+            ->(*args) { command.instance_exec(*args, &hook) }
+          when Method
+            hook
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aye_commander/initializable.rb

@@ -0,0 +1,18 @@
+module AyeCommander
+  # This module handles initialization of both a Command and a Result
+  module Initializable
+    # Initializes the command or Result with the correct setup
+    #
+    # When a command, the status is set based on the first succeeds saved in the
+    # class. In most cases this will be :success
+    #
+    # When a result, the status is sent in the initialization so it is in theory
+    # possible to have a result without a status, though not through this gem.
+    def initialize(**args)
+      @status = self.class.succeeds.first if self.class.respond_to?(:succeeds)
+      args.each do |name, value|
+        instance_variable_set to_ivar(name), value
+      end
+    end
+  end
+end

data/lib/aye_commander/inspectable.rb

@@ -0,0 +1,36 @@
+module AyeCommander
+  # This module handles methods that help a command instance represent its
+  # contents in different ways.
+  module Inspectable
+    # This inspect mimics the one ActiveModel uses so hopefully it will also
+    # look pretty during a pry session when the variables become too many.
+    def inspect
+      inspection = to_hash.map do |name, value|
+        "#{name}: #{value}"
+      end.compact.join(', ')
+      "#<#{self.class} #{inspection}>"
+    end
+
+    # Returns a hash of the specified instance_variables
+    # Defaults to returning all the currently existing instance variables
+    def to_hash(limit = instance_variables)
+      limit.each_with_object({}) do |iv, hash|
+        ivn = to_ivar(iv)
+        hash[ivn] = instance_variable_get(ivn)
+      end
+    end
+
+    # Returns a hash of only the instance variables that were specified by the
+    # .returns method.
+    #
+    # If no variables were specified then it becomes functionally identical to
+    # #to_hash
+    def to_result_hash
+      if self.class.respond_to?(:returns) && self.class.returns.any?
+        to_hash([:status] | self.class.returns)
+      else
+        to_hash
+      end
+    end
+  end
+end

data/lib/aye_commander/ivar.rb

@@ -0,0 +1,94 @@
+module AyeCommander
+  # This module contains mostly methods related to method missing and instance
+  # variables
+  module Ivar
+    # Instance variable related class methods
+    module ClassMethods
+      # Adds the received reader to the class.
+      # It prefers using 'uses' it available (command), but will use attr_reader
+      # if it isn't (result).
+      def define_missing_reader(reader)
+        respond_to?(:uses) ? uses(reader) : attr_reader(reader)
+      end
+
+      # Transforms the received name to instance variable form
+      # Eg: command -> @command
+      def to_ivar(name)
+        name[0] == '@' ? name.to_sym : "@#{name}".to_sym
+      end
+
+      # Transforms the received name to normal variable form
+      # Eg: @command -> command
+      def to_nvar(name)
+        name[0] == '@' ? name[1..-1].to_sym : name.to_sym
+      end
+    end
+
+    # Helps a command and result respond to read methods of instance variables
+    # This functionality is divided into two different modules since commander
+    # includes both, but result only includes Readable
+    module Readable
+      # A command will only respond to a read instance variable if it receives
+      # a valid instance variable name that is already defined within the
+      # command or result.
+      def method_missing(name, *args)
+        var_name = to_ivar(name)
+        if instance_variable_defined? var_name
+          self.class.define_missing_reader(name)
+          instance_variable_get var_name
+        else
+          super
+        end
+      rescue NameError
+        super
+      end
+
+      # This helps remove an instance variable name from the current command.
+      # Consider using the .returns method instead.
+      def remove!(name)
+        remove_instance_variable to_ivar(name)
+      end
+
+      # Transforms the received name to instance variable form
+      def to_ivar(name)
+        self.class.to_ivar(name)
+      end
+
+      # Transforms the received name to normal variable form
+      def to_nvar(name)
+        self.class.to_nvar(name)
+      end
+
+      private
+
+      def respond_to_missing?(name, *args)
+        instance_variable_defined?(to_ivar(name)) || super
+      rescue NameError
+        super
+      end
+    end
+
+    # Helps a command respond to methods that would be writers
+    module Writeable
+      # Any method that ends with an equal sign will be able to be handled by
+      # this method missing.
+      def method_missing(name, *args)
+        if name[-1] == '='
+          var_name = to_ivar(name[0...-1])
+          instance_variable_set var_name, args.first
+          self.class.uses name[0...-1]
+        else
+          super
+        end
+      rescue NameError
+        super
+      end
+
+      private
+
+      def respond_to_missing?(name, *args)
+        name[-1] == '=' || super
+      end
+    end
+  end
+end