pakyow-support 0.11.3 → 1.0.0.rc1

data/lib/pakyow/support/hookable.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "pakyow/support/class_state"
+
+module Pakyow
+  module Support
+    # Makes it possible to define and call hooks on an object.
+    #
+    # Hooks can be defined at the class or instance level. When calling hooks
+    # on an instance, hooks defined on the class will be called first.
+    #
+    # By default, hooks are called in the order they are defined. Each hook
+    # can be assigned a relative priority to influence when it is to be called
+    # (relative to other hooks of the same type). Default hook priority is `0`,
+    # and can instead be set to `1` (high) or `-1` (low).
+    #
+    # @example
+    #   class Fish
+    #     include Pakyow::Support::Hookable
+    #     events :swim
+    #
+    #     def swim
+    #       performing "swim" do
+    #         puts "swimming"
+    #       end
+    #     end
+    #   end
+    #
+    #   Fish.before "swim" do
+    #     puts "prepping"
+    #   end
+    #
+    #   fish = Fish.new
+    #
+    #   fish.after "swim" do
+    #     puts "resting"
+    #   end
+    #
+    #   fish.swim
+    #   => prepping
+    #      swimming
+    #      resting
+    #
+    module Hookable
+      # Known hook priorities.
+      #
+      PRIORITIES = { default: 0, high: 1, low: -1 }.freeze
+
+      def self.included(base)
+        base.include CommonMethods
+        base.include InstanceMethods
+
+        base.extend ClassMethods
+
+        base.extend ClassState
+        base.class_state :__events, default: [], inheritable: true, getter: false
+        base.class_state :__hooks, default: [], inheritable: true, getter: false
+        base.class_state :__hook_hash, default: { after: {}, before: {} }, inheritable: true
+        base.class_state :__hook_pipeline, default: { after: {}, before: {} }, inheritable: true
+      end
+
+      # @api private
+      def known_event?(event)
+        self.class.known_event?(event.to_sym)
+      end
+
+      # Class-level api methods.
+      #
+      module ClassMethods
+        attr_reader :__hook_pipeline
+
+        def self.extended(base)
+          base.extend(CommonMethods)
+        end
+
+        # Sets the known events for the hookable object. Hooks registered for
+        # an event that doesn't exist will raise an ArgumentError.
+        #
+        # @param events [Array<Symbol>] The list of known events.
+        #
+        def events(*events)
+          @__events.concat(events.map(&:to_sym)).uniq!; @__events
+        end
+
+        # Defines a hook to call before event occurs.
+        #
+        # @param event [Symbol] The name of the event.
+        # @param priority [Symbol, Integer] The priority of the hook.
+        #   Other priorities include:
+        #     high (1)
+        #     low (-1)
+        #
+        def before(event, name = nil, priority: PRIORITIES[:default], exec: true, &block)
+          add_hook(:before, event, name, priority, exec, block)
+        end
+        alias on before
+
+        # Defines a hook to call after event occurs.
+        #
+        # @see #before
+        #
+        def after(event, name = nil, priority: PRIORITIES[:default], exec: true, &block)
+          add_hook(:after, event, name, priority, exec, block)
+        end
+
+        # Defines a hook to call before and after event occurs.
+        #
+        # @see #before
+        #
+        def around(event, name = nil, priority: PRIORITIES[:default], exec: true, &block)
+          add_hook(:before, event, name, priority, exec, block)
+          add_hook(:after, event, name, priority, exec, block)
+        end
+
+        # @api private
+        def known_event?(event)
+          @__events.include?(event.to_sym)
+        end
+
+        def known_hook?(event)
+          @__hooks.any? { |hook|
+            hook[:name] == event.to_sym
+          }
+        end
+      end
+
+      # Methods included at the class and instance level.
+      #
+      module CommonMethods
+        # Calls all registered hooks for `event`, yielding between them.
+        #
+        # @param event [Symbol] The name of the event.
+        #
+        def performing(event, *args)
+          call_hooks(:before, event, *args)
+          value = yield
+          call_hooks(:after, event, *args)
+          value
+        end
+
+        # Calls all registered hooks of type, for event.
+        #
+        # @param type [Symbol] The type of event (e.g. before / after).
+        # @param event [Symbol] The name of the event.
+        #
+        def call_hooks(type, event, *args)
+          hooks(type, event).each do |hook|
+            if hook[:exec]
+              instance_exec(*args, &hook[:block])
+            else
+              hook[:block].call(*args)
+            end
+          end
+        end
+
+        # @api private
+        def hooks(type, event)
+          __hook_pipeline[type][event] || []
+        end
+
+        # @api private
+        def add_hook(type, event, name, priority, exec, hook)
+          if priority.is_a?(Symbol)
+            priority = PRIORITIES[priority]
+          end
+
+          if known_event?(event) || known_hook?(event)
+            hook = {
+              type: type,
+              event: event.to_sym,
+              name: name ? name.to_sym : nil,
+              priority: priority,
+              block: hook,
+              exec: exec
+            }
+
+            (@__hook_hash[type.to_sym][event.to_sym] ||= []) << hook
+            @__hooks << hook
+          else
+            raise ArgumentError, "#{event} is not a known hook event"
+          end
+
+          reprioritize!(type, event)
+          pipeline!(type, event)
+
+          if known_hook?(event)
+            traverse_events_for_hook(event) do |hook_event|
+              pipeline!(:before, hook_event); pipeline!(:after, hook_event)
+            end
+          end
+        end
+
+        # @api private
+        def traverse_events_for_hook(name, &block)
+          if hook = @__hooks.find { |h| h[:name] == name.to_sym }
+            yield hook[:event]
+            traverse_events_for_hook(hook[:event], &block)
+          end
+        end
+
+        # @api private
+        def reprioritize!(type, event)
+          @__hook_hash[type.to_sym][event.to_sym] = @__hook_hash[type.to_sym][event.to_sym].group_by { |hook|
+            hook[:priority]
+          }.sort { |a, b|
+            b[0] <=> a[0]
+          }.flat_map { |group|
+            group[1]
+          }
+        end
+
+        # @api private
+        def pipeline!(type, event)
+          __hook_pipeline[type.to_sym][event.to_sym] = @__hook_hash.dig(type.to_sym, event.to_sym).to_a.flat_map { |hook|
+            [@__hook_pipeline[:before][hook[:name]].to_a, hook, @__hook_pipeline[:after][hook[:name]].to_a].flatten
+          }
+        end
+      end
+
+      module InstanceMethods
+        def __hook_pipeline
+          self.class.__hook_pipeline
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/indifferentize.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Pakyow
+  module Support
+    # Creates a Hash-like object can access stored data with symbol or
+    #   string keys.
+    #
+    # The original hash is converted to symbol keys, which means
+    #   that a hash that originally contains a symbol and string key
+    #   with the same symbold value will conflict. It is not guaranteed
+    #   which value will be saved.
+    #
+    # IndifferentHash instances have the same api as Hash, but any method
+    #   that would return a Hash, will return an IndifferentHash (with
+    #   the exception of to_h/to_hash).
+    #
+    # NOTE: Please lookup Ruby's documentation for Hash to learn what
+    #   methods are available.
+    #
+    # @example
+    #   { test: "test1", "test" => "test2" } => { test: "test2" }
+    #
+    class IndifferentHash < SimpleDelegator
+      class << self
+        def deep(object)
+          hash = object.to_h
+          unless hash.empty?
+            hash = hash.each_with_object({}) { |(key, value), new_hash|
+              new_hash[key] = case value
+              when Hash
+                deep(value)
+              when Array
+                value.map { |value_item|
+                  case value_item
+                  when Hash
+                    deep(value_item)
+                  else
+                    value_item
+                  end
+                }
+              else
+                value
+              end
+            }
+          end
+
+          self.new(hash)
+        end
+
+        private
+
+        def indifferent_key_method(*methods)
+          methods.each do |name|
+            define_method(name) do |key = nil, *args, &block|
+              key = convert_key(key)
+              internal_hash.public_send(name, key, *args, &block)
+            end
+          end
+        end
+
+        def indifferent_multi_key_method(*methods)
+          methods.each do |name|
+            define_method(name) do |*keys, &block|
+              keys = keys.map { |key|
+                convert_key(key)
+              }
+              internal_hash.public_send(name, *keys, &block)
+            end
+          end
+        end
+
+        def indifferentize_return_method(*methods)
+          methods.each do |name|
+            define_method(name) do |*args, &block|
+              hash = internal_hash.public_send(name, *args, &block)
+              self.class.new(hash) if hash
+            end
+          end
+        end
+
+        def indifferentize_update_method(*methods)
+          methods.each do |name|
+            define_method(name) do |*args, &block|
+              args = args.map { |arg| stringify_keys(arg) }
+              hash = internal_hash.public_send(name, *args, &block)
+              self if hash
+            end
+          end
+        end
+
+        def indifferentize_argument_method(*methods)
+          methods.each do |name|
+            define_method(name) do |*args, &block|
+              args = args.map { |arg| stringify_keys(arg) }
+              internal_hash.public_send(name, *args, &block)
+            end
+          end
+        end
+      end
+
+      def initialize(hash = {})
+        self.internal_hash = hash
+      end
+
+      indifferent_key_method :[], :[]=, :default, :delete, :fetch, :has_key?, :key?, :include?, :member?, :store
+      indifferent_multi_key_method :fetch_values, :values_at, :dig
+      indifferentize_return_method :merge, :invert, :compact, :reject, :select, :transform_values
+      indifferentize_update_method :merge!, :update, :replace, :clear, :keep_if, :delete_if, :compact!, :reject!, :select!
+      indifferentize_argument_method :>, :>=, :<=>, :<, :<=, :==
+
+      def internal_hash
+        __getobj__
+      end
+
+      def to_h
+        internal_hash.each_with_object({}) { |(key, value), new_hash|
+          key = case key
+          when String
+            key.to_sym
+          else
+            key
+          end
+
+          value = case value
+          when IndifferentHash
+            value.to_h
+          else
+            value
+          end
+
+          new_hash[key] = value
+        }
+      end
+      alias to_hash to_h
+
+      # Fixes an issue using pp inside a delegator.
+      #
+      def pp(*args)
+        Kernel.pp(*args)
+      end
+
+      private
+
+      def internal_hash=(other)
+        __setobj__(stringify_keys(other))
+      end
+
+      def stringify_keys(object)
+        return object unless object.respond_to?(:to_h)
+
+        converted = {}
+        object.to_h.each do |key, value|
+          converted[convert_key(key)] = value
+        end
+
+        converted
+      end
+
+      def convert_key(key)
+        case key
+        when Symbol
+          key.to_s
+        else
+          key
+        end
+      end
+    end
+
+    module Indifferentize
+      refine Hash do
+        def indifferentize
+          Pakyow::Support::IndifferentHash.new(self)
+        end
+
+        def deep_indifferentize
+          Pakyow::Support::IndifferentHash.deep(self)
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/inflector.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "dry/inflector"
+
+module Pakyow
+  module Support
+    def self.inflector
+      @inflector ||= Dry::Inflector.new do |inflections|
+        inflections.uncountable "children"
+      end
+    end
+  end
+end

data/lib/pakyow/support/inspectable.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "pakyow/support/class_state"
+
+module Pakyow
+  module Support
+    # Customized inspectors for your objects.
+    #
+    # @example
+    #   class FooBar
+    #     include Pakyow::Support::Inspectable
+    #     inspectable :@foo, :baz
+    #
+    #     def initialize
+    #       @foo = :foo
+    #       @bar = :bar
+    #     end
+    #
+    #     def baz
+    #       :baz
+    #     end
+    #   end
+    #
+    #   FooBar.instance.inspect
+    #   => #<FooBar:0x007fd3330248c0 @foo=:foo baz=:baz>
+    #
+    module Inspectable
+      def self.included(base)
+        base.extend ClassMethods
+        base.extend ClassState unless base.ancestors.include?(ClassState)
+        base.class_state :__inspectables, inheritable: true, default: []
+      end
+
+      module ClassMethods
+        # Sets the instance vars and public methods that should be part of the inspection.
+        #
+        # @param inspectables [Array<Symbol>] The list of instance variables and public methods.
+        #
+        def inspectable(*inspectables)
+          @__inspectables = inspectables.map(&:to_sym)
+        end
+      end
+
+      # Recursion protection based on:
+      #   https://stackoverflow.com/a/5772445
+      #
+      def inspect
+        inspection = String.new("#<#{self.class}:#{self.object_id}")
+
+        if recursive_inspect?
+          "#{inspection} ...>"
+        else
+          prevent_inspect_recursion do
+            if self.class.__inspectables.any?
+              inspection << " " + self.class.__inspectables.map { |inspectable|
+                value = if inspectable.to_s.start_with?("@")
+                  instance_variable_get(inspectable)
+                else
+                  send(inspectable)
+                end
+
+                "#{inspectable}=#{value.inspect}"
+              }.join(", ")
+            end
+
+            inspection.strip << ">"
+          end
+        end
+      end
+
+      private
+
+      def inspected_objects
+        Thread.current[:inspected_objects] ||= {}
+      end
+
+      def prevent_inspect_recursion
+        inspected_objects[object_id] = true; yield
+      ensure
+        inspected_objects.delete(object_id)
+      end
+
+      def recursive_inspect?
+        inspected_objects[object_id]
+      end
+    end
+  end
+end

data/lib/pakyow/support/logging.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Pakyow
+  module Support
+    module Logging
+      # Yields Pakyow.logger if defined, otherwise raises `error`.
+      #
+      def self.yield_or_raise(error)
+        if defined?(Pakyow.logger)
+          yield(Pakyow.logger)
+        else
+          raise error
+        end
+      end
+
+      # Yields Pakyow.logger if defined, or a default logger.
+      #
+      def self.safe
+        logger = if defined?(Pakyow.logger) && Pakyow.logger
+          Pakyow.logger
+        else
+          ::Logger.new($stdout)
+        end
+
+        yield logger
+      end
+    end
+  end
+end

data/lib/pakyow/support/makeable/object_maker.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "pakyow/support/inflector"
+
+module Pakyow
+  module Support
+    # @api private
+    module ObjectMaker
+      def self.define_const_for_object_with_name(object_to_define, object_name)
+        return if object_name.nil?
+
+        target = object_name.namespace.parts.inject(Object) { |target_for_part, object_name_part|
+          ObjectMaker.define_object_on_target_with_constant_name(Module.new, target_for_part, object_name_part)
+        }
+
+        ObjectMaker.define_object_on_target_with_constant_name(object_to_define, target, object_name.name)
+      end
+
+      def self.define_object_on_target_with_constant_name(object, target, constant_name)
+        constant_name = Support.inflector.camelize(constant_name)
+
+        unless target.const_defined?(constant_name, false)
+          target.const_set(constant_name, object)
+        end
+
+        target.const_get(constant_name)
+      end
+    end
+  end
+end

data/lib/pakyow/support/makeable/object_name.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "pakyow/support/inflector"
+require "pakyow/support/makeable/object_namespace"
+
+module Pakyow
+  module Support
+    # @api private
+    class ObjectName
+      class << self
+        def namespace(*namespaces, object_name)
+          ObjectName.new(
+            ObjectNamespace.new(*namespaces),
+            object_name
+          )
+        end
+      end
+
+      attr_reader :namespace, :name
+
+      def initialize(namespace, name)
+        @namespace, @name = namespace, name.to_sym
+      end
+
+      def isolated(subobject_name)
+        ObjectName.new(
+          ObjectNamespace.new(*parts),
+          subobject_name
+        )
+      end
+
+      def parts
+        namespace.parts + [@name]
+      end
+
+      def to_s
+        [@namespace, @name].join("/")
+      end
+
+      def constant
+        [@namespace.constant, Support.inflector.camelize(@name)].join("::")
+      end
+    end
+  end
+end

data/lib/pakyow/support/makeable/object_namespace.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "pakyow/support/inflector"
+
+module Pakyow
+  module Support
+    # @api private
+    class ObjectNamespace
+      def initialize(*namespaces)
+        @namespaces = namespaces.map(&:to_sym)
+      end
+
+      def parts
+        @namespaces
+      end
+
+      def to_s
+        @namespaces.join("/")
+      end
+
+      def constant
+        @namespaces.map { |namespace|
+          Support.inflector.camelize(namespace)
+        }.join("::")
+      end
+    end
+  end
+end