dry-plugins 0.1.0

data/lib/dry/plugins/host/dsl.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+
+module Dry
+  module Plugins
+    module Host
+      # Mixin used as the DSL of the host class or module
+      module DSL
+        # (Auto)load the plugin called `name` and apply it to `host`
+        #
+        # In case plugin `name` is not registered yet,
+        # registry will try to {Resolver#call resolve that plugin} by `name`
+        #
+        # @param name [Symbol]
+        # @param configuration [Proc] optional configuration block
+        #
+        # @return [<Symbol>] names of the currently used plugins
+        #
+        # @example
+        #   class Resource
+        #     extend Dry::Plugins
+        #
+        #     module Plugins
+        #       module Persistence
+        #         def persist(something)
+        #           STDOUT.puts "#{something} persisted!"
+        #         end
+        #       end
+        #
+        #       register :persistence, Persistence
+        #     end
+        #   end
+        #
+        #   class ArticleResource < Resource
+        #     use :persistence #=> %i[persistence]
+        #   end
+        #
+        #   article = ArticleResource.new
+        #   article.persist(:something) # prints `something persisted!`
+        #
+        def use(*names, &configuration)
+          names.map do |name|
+            plugin = plugins.plugins_registry.resolve(name)
+            plugin.call(self, &configuration)
+          end
+        end
+
+        # @return [<Symbol>]
+        #
+        # @example
+        #   class Resource
+        #     extend Dry::Plugins
+        #
+        #     module Plugins
+        #       module Persistence
+        #         def persist(something)
+        #           STDOUT.puts "#{something} persisted!"
+        #         end
+        #       end
+        #
+        #       register :persistence, Persistence
+        #     end
+        #   end
+        #
+        #   class ArticleResource < Resource
+        #     use :persistence #=> %i[persistence]
+        #     used_plugins #=> %i[persistence]
+        #   end
+        def used_plugins
+          @used_plugins ||= Set.new
+        end
+
+        # @return [Module, DSL]
+        def plugins(&block)
+          plugins = const_get(Plugins.config.plugins_module_name)
+          return plugins.module_eval(&block) if block_given?
+          plugins
+        end
+
+        def inherited(child)
+          super(child)
+          child.instance_variable_set :@used_plugins, used_plugins.dup
+        end
+
+        # @!method plugins_registry
+        #
+        # @return [Registry]
+        #
+        # @see Config#registry_method
+      end
+    end
+  end
+end

data/lib/dry/plugins/module_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'dry/plugins/dsl'
+
+module Dry
+  module Plugins
+    # Builds a `Module` containing all plug-ins for `host`
+    class ModuleBuilder
+      def initialize(plugins_module_name: Plugins.config.plugins_module_name)
+        @plugins_module_name = plugins_module_name
+      end
+
+      # @return [Symbol]
+      attr_reader :plugins_module_name
+
+      # @param host [Module]
+      #
+      # @return [Module]
+      #
+      # @example
+      #   require 'dry/plugins/module_builder'
+      #
+      #   class Host
+      #   end
+      #
+      #   module_builder = Dry::Plugins::ModuleBuilder.new
+      #   module_builder.call(Host) #=> Host::Plugins
+      def call(host)
+        plugins = if host.const_defined?(plugins_module_name)
+                    host.const_get(plugins_module_name)
+                  else
+                    host.const_set(plugins_module_name, Module.new)
+                  end
+        plugins
+      end
+    end
+  end
+end

data/lib/dry/plugins/plugin.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'delegate'
+require 'forwardable'
+
+# noinspection YARDTagsInspection
+
+module Dry
+  module Plugins
+    # @abstract A delegator providing Plugin DSL
+    class Plugin < SimpleDelegator
+      extend Forwardable
+
+      # @overload initialize(registry, name, plugin)
+      #   @param registry [Registry]
+      #   @param name [#to_s]
+      # @overload initialize(registry, plugin)
+      #   @param registry [Registry]
+      #   @param plugin [Module]
+      def initialize(registry, name, plugin = nil)
+        @__registry__ = registry
+
+        plugin = name if name.is_a?(Module)
+        self.name = name
+        self.plugin = plugin if plugin
+      end
+
+      # @!method config
+      #   @return [Config]
+      def_delegators :@__registry__, :config
+
+      # Module with actual plugin data
+      # @return [Module]
+      def __getobj__
+        super do
+          __setobj__ load
+        end
+      end
+
+      alias plugin __getobj__
+
+      # @param plugin [Module]
+      def __setobj__(plugin)
+        self.name = plugin if plugin
+        super(plugin)
+      end
+
+      alias plugin= __setobj__
+
+      # @return [Symbol]
+      attr_reader :name
+
+      # @param name [#to_s]
+      # @return [Symbol]
+      def name=(name)
+        name = name.to_s
+        @name = Inflecto.underscore(Inflecto.demodulize(name)).to_sym unless name.empty?
+      end
+
+      # @param host [Module]
+      # @param configuration [Proc]
+      #
+      # @return [<Symbol>]
+      def call(host, &configuration)
+        load_dependencies(host)
+        host.send(:include, plugin)
+        if plugin.const_defined?(Plugins.config.class_interface_name)
+          host.extend(plugin.const_get(Plugins.config.class_interface_name))
+        end
+        configure(host, &configuration) if configuration
+        host.used_plugins << name
+        host
+      end
+
+      alias plug call
+
+      # Resolves the plug-in `Module` from the {Registry}
+      # @return [Module]
+      def load
+        @__registry__.resolve(name)
+      end
+
+      # Load plugin and plugin dependencies (if declared)
+      #
+      # @param host [Module]
+      def load_dependencies(host)
+        return unless plugin.respond_to?(Plugins.config.load_dependencies_method)
+        plugin.public_send(Plugins.config.load_dependencies_method, host)
+      end
+
+      # Configure the `host` using `configuration`
+      # @param host [Module]
+      # @param configuration [Proc]
+      def configure(host, &configuration)
+        if plugin.respond_to?(Plugins.config.configure_method)
+          return plugin.public_send(Plugins.config.configure_method, host, &configuration)
+        end
+        host.module_eval(&configuration)
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry/builder.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'dry/plugins/dsl'
+
+module Dry
+  module Plugins
+    class Registry
+      # Build a plug-in registry for given `host`
+      #
+      # @see Builder#call
+      class Builder
+        def initialize(registry_method: Plugins.config.registry_method, **kwargs)
+          @registry_method = registry_method
+          super(**kwargs)
+        end
+
+        # @return [Symbol]
+        attr_reader :registry_method
+
+        # @param plugins [Module]
+        #
+        # @return [Registry]
+        def call(host,
+                 plugins: module_builder.call(host),
+                 registry_class: class_builder.call(plugins))
+          unless plugins.respond_to? registry_method
+            registry_variable = :"@#{registry_method}"
+            plugins.define_singleton_method registry_method do
+              if instance_variable_defined? registry_variable
+                instance_variable_get registry_variable
+              else
+                instance_variable_set registry_variable, registry_class.new(plugins)
+              end
+            end
+          end
+
+          unless plugins.singleton_class.included_modules.include? DSL
+            plugins.extend DSL
+          end
+
+          plugins.public_send registry_method
+        end
+
+        private
+
+        # @!method module_builder
+        #   @return [ModuleBuilder]
+        #
+        # @!method class_builder
+        #   @return [ClassBuilder]
+        include Import[:module_builder, class_builder: :registry_class_builder]
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry/class_builder.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'dry/plugins/registry'
+
+module Dry
+  module Plugins
+    class Registry
+      # Builds a {Registry} child class specific to `plugins` module
+      # @see ClassBuilder#call
+      class ClassBuilder
+        # @param class_name [Symbol]
+        def initialize(class_name: Plugins.config.registry_class_name)
+          @class_name = class_name
+        end
+
+        # @return [Symbol]
+        attr_reader :class_name
+
+        # @param plugins [Module]
+        #
+        # @return [Class(Registry)]
+        def call(plugins)
+          unless plugins.const_defined? class_name
+            plugins.const_set class_name, Class.new(Registry)
+          end
+          plugins.const_get class_name
+        end
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry/key_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/error'
+
+module Dry
+  module Plugins
+    class Registry
+      # Plug-in registration error
+      class KeyError < Error
+        def initialize(registry, key, plugin)
+          super <<~ERROR
+            Cannot register #{key.inspect} in #{registry.inspect}
+              as
+                #{indent plugin.inspect}
+              since previously registered
+                #{indent registry[key].inspect}
+          ERROR
+        end
+
+        private
+
+        def indent(lines, indentation: ' ' * 4, glue: "\n")
+          indentation + lines.to_s.split(/\n/).join("#{indentation}#{glue}") + glue
+        end
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry/load_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/error'
+
+module Dry
+  module Plugins
+    class Registry
+      # Plug-in load error
+      class LoadError < Error
+        def initialize(name, registry)
+          super "Plugin #{name} did not register itself correctly in #{registry}"
+        end
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry/resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'dry/plugins/registry/load_error'
+require 'dry/container/resolver'
+require 'inflecto'
+
+module Dry
+  module Plugins
+    class Registry
+      # Default resolver for resolving plugins from registry
+      class Resolver < Dry::Container::Resolver
+        # Resolve a plugin from the registry
+        #
+        # @param container [Concurrent::Hash]
+        #   The container
+        # @param name [Mixed]
+        #   The name for the plugin you wish to resolve
+        #
+        # @raise [LoadError]
+        #   If the given plugin is not registered in the registry
+        #
+        # @return [Mixed]
+        #
+        # @api public
+        # If the registered plugin already exists, use it.
+        # Otherwise, require it and return it.
+        # This raises a LoadError if such a plugin doesn't exist, or a LoadError if it exists but it does
+        # not register itself correctly.
+        def call(container, name, require_path)
+          name = name.to_s
+          unless container.key?(name)
+            path = Inflecto.underscore(name).tr('.', '/')
+            require "#{require_path}/#{path}"
+            raise LoadError, name, container unless container.key?(name)
+          end
+
+          super(container, name)
+        end
+      end
+    end
+  end
+end

data/lib/dry/plugins/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'dry/plugins/config'
+require 'dry/plugins/registry/key_error'
+require 'dry/plugins/registry/resolver'
+require 'dry/plugins/plugin'
+require 'dry-container'
+require 'dry-equalizer'
+
+module Dry
+  module Plugins
+    # Plug-in Registry
+    class Registry
+      include Dry::Container::Mixin
+      include Dry::Equalizer(:_container, :config, :plugins)
+
+      configure do |config|
+        config.resolver = Resolver.new
+      end
+
+      # @param plugins [Module]
+      def initialize(plugins)
+        @require_path = Inflecto.underscore(plugins.to_s)
+        @plugins = plugins
+        super()
+      end
+
+      # @return [Module]
+      attr_reader :plugins
+
+      # @param key [#to_sym]
+      # @param plugin [Module, Plugin]
+      #
+      # @return [Plugin]
+      def register(key, plugin)
+        key = key.to_s
+        plugin = plugin.plugin if plugin.is_a? Plugin
+        if key?(key) && resolve(key) != plugin
+          raise Registry::KeyError.new(self, key, plugin)
+        end
+        super key, plugin
+      end
+
+      # @param plugin [Module]
+      # @param name [Symbol]
+      #
+      # @return [Plugin]
+      def proxy(plugin, name: nil)
+        Plugin.new(self, name, plugin)
+      end
+
+      # Resolve an item from the container
+      #
+      # @param name [Mixed]
+      #   The key for the item you wish to resolve
+      #
+      # @return [Plugin]
+      #
+      # @api public
+      def resolve(name)
+        registry = self
+        plugin = config.resolver.call(_container, name, @require_path)
+        Plugin.new(registry, name, plugin)
+      end
+
+      # @!parse alias [] resolve
+    end
+  end
+end

data/lib/dry/plugins/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Dry
+  module Plugins
+    VERSION = '0.1.0'
+  end
+end

data/lib/dry/plugins.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Dry
+  # @abstract DSL for plugins manipulation
+  module Plugins
+    # @param host [Module]
+    #
+    # @api private
+    def self.extended(host)
+      require 'dry/plugins/config'
+
+      super(host)
+      Plugins[:builder].call(host)
+    end
+  end
+end

data/lib/dry-plugins.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'dry/plugins'

data/lib/rspec/dry-plugins.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require 'rspec/its'
+require 'dry-plugins'
+require 'dry/core/class_builder'
+
+RSpec.shared_context 'a plug-ins host' do
+  subject(:host) { described_class }
+
+  it { is_expected.to respond_to :use }
+  it { is_expected.to respond_to :used_plugins }
+  it { is_expected.to respond_to :plugins }
+  it { is_expected.to respond_to Dry::Plugins.config.registry_method }
+
+  describe ".const_get #{Dry::Plugins.config.plugins_module_name.inspect}" do
+    subject(:plugins) { host.const_get(Dry::Plugins.config.plugins_module_name) }
+
+    it { is_expected.to be_a Module }
+    it { is_expected.to respond_to Dry::Plugins.config.registry_method }
+  end
+end
+
+module Dry
+  module Plugins
+    # RSpec helpers for plug-ins
+    module RSpec
+      def a_plugins_host(name: :Host, parent: nil, &block)
+        class_builder = Dry::Core::ClassBuilder.new(
+          name: name,
+          namespace: ::Object,
+          parent: parent
+        )
+        host = class_builder.call
+        host.module_eval(&block) if block_given?
+        host
+      end
+    end
+  end
+end
+RSpec.configure do |config|
+  config.include Dry::Plugins::RSpec
+end

data/system/boot.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'pathname'
+$LOAD_PATH << Pathname(__dir__).join('../lib').to_path
+require 'dry-plugins'