pakyow-support 0.11.3 → 1.0.0.rc1

data/lib/pakyow/support/deep_dup.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Pakyow
+  module Support
+    # Refines Object, Array, and Hash with support for deep_dup.
+    #
+    # @example
+    #   using DeepDup
+    #   state = { "foo" => ["bar"] }
+    #   duped = state.deep_dup
+    #
+    #   state.keys[0] === duped.keys[0]
+    #   => false
+    #
+    #   state.values[0][0] === duped.values[0][0]
+    #   => false
+    #
+    module DeepDup
+      # Objects that can't be copied.
+      UNDUPABLE = [Symbol, Integer, NilClass, TrueClass, FalseClass, Class, Module].freeze
+
+      [Object, Delegator].each do |klass|
+        refine klass do
+          # Returns a copy of the object.
+          #
+          def deep_dup
+            if UNDUPABLE.include?(self.class)
+              self
+            else
+              dup
+            end
+          end
+        end
+      end
+
+      refine Array do
+        # Returns a deep copy of the array.
+        #
+        def deep_dup
+          map(&:deep_dup)
+        end
+      end
+
+      refine Hash do
+        # Returns a deep copy of the hash.
+        #
+        def deep_dup
+          hash = dup
+          each_pair do |key, value|
+            hash.delete(key)
+            hash[key.deep_dup] = value.deep_dup
+          end
+
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/deep_freeze.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Pakyow
+  module Support
+    module DeepFreeze
+      def self.extended(subclass)
+        subclass.instance_variable_set(:@unfreezable_variables, [])
+
+        super
+      end
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@unfreezable_variables, @unfreezable_variables)
+
+        super
+      end
+
+      def unfreezable(*ivars)
+        @unfreezable_variables.concat(ivars.map { |ivar| :"@#{ivar}" })
+        @unfreezable_variables.uniq!
+      end
+
+      [Object, Delegator].each do |klass|
+        refine klass do
+          def deep_freeze
+            unless frozen? || !respond_to?(:freeze)
+              self.freeze
+              freezable_variables.each do |name|
+                instance_variable_get(name).deep_freeze
+              end
+            end
+
+            self
+          end
+
+          private def freezable_variables
+            object = if self.is_a?(Class) || self.is_a?(Module)
+              self
+            else
+              self.class
+            end
+
+            if object.instance_variable_defined?(:@unfreezable_variables)
+              instance_variables - object.instance_variable_get(:@unfreezable_variables)
+            else
+              instance_variables
+            end
+          end
+        end
+      end
+
+      refine Array do
+        def deep_freeze
+          unless frozen?
+            self.freeze
+            each(&:deep_freeze)
+          end
+
+          self
+        end
+      end
+
+      refine Hash do
+        def deep_freeze
+          unless frozen?
+            frozen_hash = {}
+            each_pair do |key, value|
+              frozen_hash[key.deep_freeze] = value.deep_freeze
+            end
+
+            self.replace(frozen_hash)
+            self.freeze
+          end
+
+          self
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/definable.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "pakyow/support/deep_dup"
+require "pakyow/support/inflector"
+require "pakyow/support/makeable"
+
+module Pakyow
+  module Support
+    # Provides control over how state is defined on an object, and how state is
+    # shared across object instances and subclasses.
+    #
+    # You define the type of state provided by an object, along with any global
+    # state for that object type. When an instance is created or the definable
+    # object is subclassed, the new object inherits the global state and can be
+    # extended with its own state. Definable objects' `initialize` method should
+    # always call super with the block to ensure that state is inherited correctly.
+    #
+    # Once `defined!` is called on an instance, consider freezing the object so
+    # that it cannot be extended later.
+    #
+    #
+    # @example
+    #   class SomeDefinableObject
+    #     include Support::Definable
+    #
+    #     def initialize(some_arg, &block)
+    #       super()
+
+    #       # Do something with some_arg, etc.
+    #
+    #       defined!(&block)
+    #     end
+    #   end
+    #
+    # @api private
+    #
+    module Definable
+      using DeepDup
+
+      def self.included(base)
+        base.include CommonMethods
+        base.extend ClassMethods, CommonMethods
+        base.prepend Initializer
+        base.extend Support::Makeable
+        base.instance_variable_set(:@__state, {})
+      end
+
+      # @api private
+      def defined!(&block)
+        # set instance level state
+        self.instance_eval(&block) if block_given?
+
+        # merge global state
+        @__state.each do |name, state|
+          state.instances.concat(self.class.__state[name].instances)
+        end
+
+        # merge inherited state
+        if inherited = self.class.__inherited_state
+          @__state.each do |name, state|
+            instances = state.instances
+            instances.concat(inherited[name].instances) if inherited[name]
+          end
+        end
+      end
+
+      module ClassMethods
+        attr_reader :__state, :__inherited_state
+
+        def inherited(subclass)
+          super
+
+          subclass.instance_variable_set(:@__inherited_state, @__state.deep_dup)
+          subclass.instance_variable_set(:@__state, @__state.each_with_object({}) { |(name, state_instance), state|
+            state[name] = State.new(name, state_instance.object)
+          })
+        end
+
+        # Register a type of state that can be defined.
+        #
+        # @param object
+        #   Can be a class or instance, but must respond to :make. The `make`
+        #   method should return the object to be "made" and accept a block
+        #   that should be evaluated in the context of the object.
+        #
+        #     class Person
+        #       # ...
+        #
+        #       def make(name, dob, &block)
+        #         person = self.class.new(name, dob)
+        #
+        #         person.instance_eval(&block)
+        #         person
+        #       end
+        #
+        #       def befriend(person)
+        #         friends << person
+        #       end
+        #     end
+        #
+        #     class App
+        #       include Pakyow::Support::Definable
+        #
+        #       stateful :person, Person
+        #     end
+        #
+        #     john = App.person 'John', Date.new(1988, 8, 13) do
+        #     end
+        #
+        #     App.person 'Sofie', Date.new(2015, 9, 6) do
+        #       befriend(john)
+        #     end
+        #
+        def stateful(name, object, &stateful_block)
+          name = name.to_sym
+          @__state[name] = State.new(name, object)
+          plural_name = Support.inflector.pluralize(name.to_s).to_sym
+
+          within = if __object_name
+            ObjectNamespace.new(*__object_name.namespace.parts.dup.concat([plural_name]))
+          else
+            self
+          end
+
+          method_body = Proc.new do |*args, priority: :default, **opts, &block|
+            return @__state[name] if block.nil?
+
+            stateful_block.call(args, opts) if stateful_block
+            object.make(*args, within: within, **opts, &block).tap do |state|
+              @__state[name].register(state, priority: priority)
+            end
+          end
+
+          define_method name, &method_body
+          define_singleton_method name, &method_body
+        end
+
+        # Define state for the object.
+        #
+        def define(&block)
+          instance_eval(&block)
+        end
+      end
+
+      module CommonMethods
+        # Returns registered state instances. If +type+ is passed, returns state of that type.
+        #
+        def state(type = nil)
+          if instance_variable_defined?(:@__state)
+            return @__state if type.nil?
+
+            if @__state && @__state.key?(type)
+              @__state[type].instances
+            else
+              []
+            end
+          else
+            {}
+          end
+        end
+      end
+
+      module Initializer
+        def initialize(*)
+          # Create mutable state for this instance based on global.
+          #
+          @__state = self.class.__state.each_with_object({}) { |(name, global_state), state|
+            state[name] = State.new(name, global_state.object)
+          }
+
+          super
+        end
+      end
+    end
+
+    # Contains state for a definable class or instance.
+    #
+    # @api private
+    class State
+      using DeepDup
+
+      attr_reader :name, :object, :instances, :priorities
+
+      PRIORITIES = { default: 0, high: 1, low: -1 }.freeze
+
+      def initialize(name, object)
+        @name = name.to_sym
+        @object = object
+        @instances = []
+        @priorities = {}
+      end
+
+      def initialize_copy(original)
+        super
+        @instances = original.instances.deep_dup
+      end
+
+      # TODO: we handle both instances and classes, so reconsider the variable naming
+      def <<(instance)
+        register(instance)
+      end
+
+      # TODO: we handle both instances and classes, so reconsider the variable naming
+      def register(instance, priority: :default)
+        unless priority.is_a?(Integer)
+          priority = PRIORITIES.fetch(priority) {
+            raise ArgumentError, "unknown priority `#{priority}'"
+          }
+        end
+
+        unless instance.is_a?(Module)
+          enforce_registration!(instance)
+        end
+
+        unless instances.include?(instance)
+          instances << instance
+        end
+
+        priorities[instance] = priority
+        reprioritize!
+      end
+
+      def enforce_registration!(instance)
+        ancestors = if instance.respond_to?(:new)
+          instance.ancestors
+        else
+          instance.class.ancestors
+        end
+
+        unless ancestors.include?(@object)
+          raise ArgumentError, "expected instance of '#{@object}'"
+        end
+      end
+
+      def reprioritize!
+        @instances.sort! { |a, b|
+          (@priorities[b] || 0) <=> (@priorities[a] || 0)
+        }
+      end
+    end
+  end
+end

data/lib/pakyow/support/dependencies.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    # @api private
+    module Dependencies
+      extend self
+
+      LOCAL_FRAMEWORK_PATH = File.expand_path("../../../../../", __FILE__)
+
+      def strip_path_prefix(line)
+        if line.start_with?(Pakyow.config.root)
+          line.gsub(/^#{Pakyow.config.root}\//, "")
+        elsif line.start_with?(Pakyow.config.lib)
+          line.gsub(/^#{Pakyow.config.lib}\//, "")
+        elsif line.start_with?(Gem.default_dir)
+          line.gsub(/^#{Gem.default_dir}\/gems\//, "")
+        elsif line.start_with?(Bundler.bundle_path.to_s)
+          line.gsub(/^#{Bundler.bundle_path.to_s}\/gems\//, "")
+        elsif line.start_with?(RbConfig::CONFIG["libdir"])
+          line.gsub(/^#{RbConfig::CONFIG["libdir"]}\//, "")
+        elsif line.start_with?(LOCAL_FRAMEWORK_PATH)
+          line.gsub(/^#{LOCAL_FRAMEWORK_PATH}\//, "")
+        else
+          line
+        end
+      end
+
+      def library_name(line)
+        case library_type(line)
+        when :gem, :bundler
+          strip_path_prefix(line).split("/")[0].split("-")[0..-2].join("-")
+        when :ruby
+          "ruby"
+        when :pakyow
+          strip_path_prefix(line).split("/")[0]
+        when :lib
+          strip_path_prefix(line).split("/")[1]
+        else
+          nil
+        end
+      end
+
+      def library_type(line)
+        if line.start_with?(Gem.default_dir)
+          :gem
+        elsif line.start_with?(Bundler.bundle_path.to_s)
+          :bundler
+        elsif line.start_with?(RbConfig::CONFIG["libdir"])
+          :ruby
+        elsif line.start_with?(LOCAL_FRAMEWORK_PATH)
+          :pakyow
+        elsif line.start_with?(Pakyow.config.lib)
+          :lib
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/extension.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    # Makes it easier to define extensions.
+    #
+    # @example
+    #
+    #   module SomeExtension
+    #     extend Pakyow::Support::Extension
+    #
+    #     # only allows the extension to be used on descendants of `SomeBaseClass`
+    #     restrict_extension SomeBaseClass
+    #
+    #     apply_extension do
+    #       # anything here is evaluated on the object including the extension
+    #     end
+    #
+    #     class_methods do
+    #       # class methods can be defined here
+    #     end
+    #
+    #     prepend_methods do
+    #       # instance methods you wish to prepend can be defined here
+    #     end
+    #
+    #     # define instance-level methods as usual
+    #   end
+    #
+    #   class SomeClass < SomeBaseClass
+    #     include SomeExtension
+    #   end
+    #
+    module Extension
+      def restrict_extension(type)
+        @__extension_restriction = type
+      end
+
+      def apply_extension(&block)
+        @__extension_block = block
+      end
+
+      def class_methods(&block)
+        @__extension_extend_module = Module.new(&block)
+      end
+
+      def prepend_methods(&block)
+        @__extension_prepend_module = Module.new(&block)
+      end
+
+      def included(base)
+        enforce_restrictions(base)
+        mixin_extension_modules(base)
+        include_extensions(base)
+      end
+
+      private
+
+      def enforce_restrictions(base)
+        if instance_variable_defined?(:@__extension_restriction) && !base.ancestors.include?(@__extension_restriction)
+          raise StandardError, "expected `#{base}' to be `#{@__extension_restriction}'"
+        end
+      end
+
+      def mixin_extension_modules(base)
+        if instance_variable_defined?(:@__extension_extend_module)
+          base.extend @__extension_extend_module
+        end
+
+        if instance_variable_defined?(:@__extension_prepend_module)
+          base.prepend @__extension_prepend_module
+        end
+      end
+
+      def include_extensions(base)
+        if instance_variable_defined?(:@__extension_block)
+          base.instance_exec(&@__extension_block)
+        end
+      end
+    end
+  end
+end