ddplugin 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0de5a9e0217483b21eacdc6668deb299a6dd3e06
+  data.tar.gz: 2e1afa6aed108a66552d3b2e65ecde95cddd838f
+SHA512:
+  metadata.gz: 68d16f23635d03879c49c1322c006a023157292ea6f1844bae05c2bba59f7d6c3e315a54799668c5ba43b98f3ec087f51d57cd27c3f5f366a973a6ad24078626
+  data.tar.gz: fa3a128aac7969bced4dbaf7248871d604fb2e15b97c205a014be6c3d0dc61e62a53026c41c6467ad05fa4a2216de0fc2f3dd1fb988f2c642ce0d82631745295

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest'
+gem 'rake'
+gem 'coveralls', require: false

data/Gemfile.lock

@@ -0,0 +1,40 @@
+PATH
+  remote: .
+  specs:
+    ddplugin (0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    docile (1.1.1)
+    mime-types (2.0)
+    minitest (5.0.8)
+    multi_json (1.8.2)
+    rake (10.1.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    tins (0.13.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  coveralls
+  ddplugin!
+  minitest
+  rake

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Denis Defreyne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+[![Build Status](https://travis-ci.org/ddfreyne/ddplugin.png)](https://travis-ci.org/ddfreyne/ddplugin)
+[![Code Climate](https://codeclimate.com/github/ddfreyne/ddplugin.png)](https://codeclimate.com/github/ddfreyne/ddplugin)
+[![Coverage Status](https://coveralls.io/repos/ddfreyne/ddplugin/badge.png?branch=master)](https://coveralls.io/r/ddfreyne/ddplugin)
+
+# ddplugin
+
+*ddplugin* is a library for managing plugins.
+
+Designing a library so that third parties can easily extend it greatly improves its usefulness. *ddplugin* helps solve this problem using *plugins*, which are classes of a certain type and with a given identifier (Ruby symbol).
+
+This code was extracted from nanoc, where it has been in production for years.
+
+## Use case
+
+Many projects can make use of plugins. Here are a few examples:
+
+* a **text processing library** with *filters* such as `colorize-syntax`, `markdown` and `smartify-quotes`.
+
+* an **image processing library** with *filters* such as `resize`, `desaturate` and `rotate`.
+
+* a **database driver abstraction** with *connectors* such as `postgres`, `sqlite3` and `mysql`.
+
+* a **document management system** with *data sources* such as `filesystem` and `database`.
+
+In *ddplugin*, the filters, connectors and data sources would be *plugin types*, while the actual plugins, such as `markdown`, `rotate`, `postgres` and `database` would be *plugins*.
+
+A typical way to use plugins would be to store the plugin names in a configuration file, so that the actual plugin implementations can be discovered at runtime.
+
+## Dependencies
+
+*ddplugin* requires Ruby 1.9.3 or higher.
+
+## Versioning
+
+*ddplugin* adheres to [Semantic Versioning 2.0.0](http://semver.org).
+
+## Installation
+
+**NOTE:** *ddplugin* has not been released as a gem yet, so these installation instructions are not usable yet.
+
+If your library where you want to use *ddplugin* has a gemspec, add *ddplugin* as a runtime dependency to the gemspec:
+
+```ruby
+spec.add_runtime_dependency 'ddplugin' '~> 1.0'
+```
+
+If you use Bundler instead, add it to the `Gemfile`:
+
+```ruby
+gem 'ddplugin', '~> 1.0'
+```
+
+## Usage
+
+Plugin type are classes that extend `DDPlugin::Plugin`:
+
+```ruby
+class Filter
+  extend DDPlugin::Plugin
+end
+
+class DataSource
+  extend DDPlugin::Plugin
+end
+```
+
+To define a plugin, create a class that inherits from the plugin type and sets the identifier:
+
+```ruby
+class ERBFilter < Filter
+  identifier :erb
+end
+
+class HamlFilter < Filter
+  identifier :haml
+end
+
+class FilesystemDataSource < DataSource
+  identifier :filesystem
+end
+
+class PostgresDataSource < DataSource
+  identifier :postgres
+end
+```
+
+To find a plugin of a given type and with a given identifier, call `.named` on the plugin type, passing an identifier:
+
+```ruby
+Filter.named(:erb)
+# => ERBFilter
+
+Filter.named(:haml)
+# => HamlFilter
+
+DataSource.named(:filesystem)
+# => FilesystemDataSource
+
+DataSource.named(:postgres)
+# => PostgresDataSource
+```
+
+To get all plugins of a given type, call `.all` on the plugin type:
+
+```ruby
+Filter.all
+# => [ ERBFilter, HamlFilter ]
+
+DataSource.all
+# => [ FilesystemDataSource, PostgresDataSource ]
+```
+
+To get the identifier of a plugin, call `.identifier`:
+
+```ruby
+Filter.named(:erb).identifier
+# => :erb
+
+PostgresDataSource.identifier
+# => :postgres
+```
+
+## Development
+
+Pull requests and issues are greatly appreciated.
+
+When you submit a pull request, make sure that your change is covered by tests, and that the `README` and [YARD](http://yardoc.org/) source code documentation are still up-to-date.
+
+To run the tests, execute `rake`:
+
+```
+% rake
+```
+
+## Contact
+
+*ddplugin* is written by Denis Defreyne <denis.defreyne@stoneship.org>

data/Rakefile

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs = %w( lib test )
+  t.test_files = FileList['test/**/test_*.rb', 'test/**/*_spec.rb']
+end
+
+task :default => :test

data/ddplugin.gemspec

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift(File.expand_path('../lib/', __FILE__))
+require 'ddplugin/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'ddplugin'
+  s.version     = DDPlugin::VERSION
+  s.homepage    = 'http://github.com/ddfreyne/ddplugin/'
+  s.summary     = 'Plugins for Ruby apps'
+  s.description = 'Provides plugin management for Ruby projects'
+
+  s.author  = 'Denis Defreyne'
+  s.email   = 'denis.defreyne@stoneship.org'
+  s.license = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.files              = Dir['[A-Z]*'] +
+                         Dir['{lib,test}/**/*'] +
+                         [ 'ddplugin.gemspec' ]
+  s.require_paths      = [ 'lib' ]
+
+  s.rdoc_options     = [ '--main', 'README.md' ]
+  s.extra_rdoc_files = [ 'LICENSE', 'README.md', 'NEWS.md' ]
+
+  s.add_development_dependency('bundler')
+end

data/lib/ddplugin.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+require 'ddplugin/version'
+require 'ddplugin/plugin'
+require 'ddplugin/registry'

data/lib/ddplugin/plugin.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+
+module DDPlugin
+
+  # A module that contains class methods for plugins. It provides functions
+  # for setting identifiers and finding plugins. Plugin classes should extend
+  # this module.
+  module Plugin
+
+    # @overload identifiers(*identifiers)
+    #
+    #   Sets the identifiers for this class.
+    #
+    #   @param [Array<Symbol>] identifiers A list of identifiers to assign to
+    #     this class.
+    #
+    #   @return [void]
+    #
+    # @overload identifiers
+    #
+    #   @return [Array<Symbol>] The identifiers for this class
+    def identifiers(*identifiers)
+      if identifiers.empty?
+        DDPlugin::Registry.instance.identifiers_of(root_class, self)
+      else
+        DDPlugin::Registry.instance.register(root_class, self, *identifiers)
+      end
+    end
+
+    # @return [Class] The root class for this class
+    def root_class
+      klass = self
+      klass = klass.superclass while klass.superclass.respond_to?(:identifiers)
+      klass
+    end
+
+    # @overload identifier(identifier)
+    #
+    #   Sets the identifier for this class.
+    #
+    #   @param [Symbol] identifier The identifier to assign to this class.
+    #
+    #   @return [void]
+    #
+    # @overload identifier
+    #
+    #   @return [Symbol] The first identifier for this class
+    def identifier(identifier=nil)
+      if identifier
+        self.identifiers(identifier)
+      else
+        self.identifiers.first
+      end
+    end
+
+    # @return [Enumerable<Class>] All classes of this type
+    def all
+      DDPlugin::Registry.instance.find_all(self)
+    end
+
+    # @param [Symbol] identifier The identifier of the class to find
+    #
+    # @return [Class] The class with the given identifier
+    def named(identifier)
+      DDPlugin::Registry.instance.find(self, identifier)
+    end
+
+  end
+
+end

data/lib/ddplugin/registry.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+module DDPlugin
+
+  # The registry is responsible for keeping track of all loaded plugins.
+  class Registry
+
+    # Returns the shared {DDPlugin::Registry} instance, creating it if none
+    # exists yet.
+    #
+    # @return [DDPlugin::Registry] The shared plugin registry
+    def self.instance
+      @instance ||= self.new
+    end
+
+    # @api private
+    def initialize
+      @identifiers_to_classes = Hash.new { |h,k| h[k] = {}.dup }
+      @classes_to_identifiers = Hash.new { |h,k| h[k] = {}.dup }
+    end
+
+    # Registers the given class as a plugin.
+    #
+    # @param [Class] root_class The root class of the class to register
+    #
+    # @param [Class] klass The class to register
+    #
+    # @param [Symbol] identifiers One or more symbols identifying the class
+    #
+    # @return [void]
+    def register(root_class, klass, *identifiers)
+      identifiers.each do |identifier|
+        @classes_to_identifiers[root_class][klass] ||= []
+
+        @identifiers_to_classes[root_class][identifier] = klass
+        @classes_to_identifiers[root_class][klass] << identifier
+      end
+    end
+
+    # @param [Class] root_class The root class of the class to find the
+    #   identifiers for
+    #
+    # @param [Class] klass The class to get the identifiers for
+    #
+    # @return [Array<Symbol>] The identifiers for the given class
+    def identifiers_of(root_class, klass)
+      @classes_to_identifiers[root_class] ||= {}
+      @classes_to_identifiers[root_class].fetch(klass, [])
+    end
+
+    # Finds the class that is a descendant of the given class and has the given
+    # identifier.
+    #
+    # @param [Class] root_class The root class of the class to return
+    #
+    # @param [Symbol] identifier The identifier of the class to return
+    #
+    # @return [Class, nil] The class with the given identifier
+    def find(root_class, identifier)
+      @identifiers_to_classes[root_class] ||= {}
+      @identifiers_to_classes[root_class][identifier]
+    end
+
+    # Returns all classes that are registered descendants of the given class.
+    #
+    # @param [Class] root_class The root class of the class to return
+    #
+    # @return [Enumerable<Class>] A collection of registered classes
+    def find_all(root_class)
+      @identifiers_to_classes[root_class] ||= {}
+      @identifiers_to_classes[root_class].values
+    end
+
+  end
+
+end

data/lib/ddplugin/version.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+module DDPlugin
+
+  VERSION = '0.1'
+
+end

data/test/helper.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+require 'coveralls'
+Coveralls.wear!
+
+require 'minitest'
+require 'minitest/autorun'
+
+require 'ddplugin'

data/test/test_plugin.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+
+require 'helper'
+
+class DDPlugin::PluginTest < Minitest::Test
+
+  class IdentifierSample
+    extend DDPlugin::Plugin
+  end
+
+  class NamedSample
+    extend DDPlugin::Plugin
+  end
+
+  class AllSample
+    extend DDPlugin::Plugin
+  end
+
+  class InheritanceSample
+    extend DDPlugin::Plugin
+  end
+
+  def test_identifier
+    klass = Class.new(IdentifierSample)
+    assert_nil klass.identifier
+
+    klass.identifier :foo
+    assert_equal :foo, klass.identifier
+
+    klass.identifier :bar
+    assert_equal :foo, klass.identifier
+  end
+
+  def test_identifiers
+    klass = Class.new(IdentifierSample)
+    assert_empty klass.identifiers
+
+    klass.identifiers :foo1, :foo2
+    assert_equal [ :foo1, :foo2 ], klass.identifiers
+
+    klass.identifiers :bar1, :bar2
+    assert_equal [ :foo1, :foo2, :bar1, :bar2 ], klass.identifiers
+  end
+
+  def test_root
+    superklass = Class.new(InheritanceSample)
+    superklass.identifier :super
+
+    subklass = Class.new(superklass)
+    subklass.identifiers :sub, :also_sub
+
+    assert_equal superklass, InheritanceSample.named(:super)
+    assert_equal subklass, InheritanceSample.named(:sub)
+
+    assert_equal :sub, subklass.identifier
+    assert_equal [ :sub, :also_sub ], subklass.identifiers
+
+    assert_equal InheritanceSample, superklass.root_class
+    assert_equal InheritanceSample, subklass.root_class
+  end
+
+  def test_named
+    klass = Class.new(NamedSample)
+    klass.identifier :named_test
+
+    assert_nil NamedSample.named(:unknown)
+    assert_equal klass, NamedSample.named(:named_test)
+  end
+
+  def test_all
+    klass1 = Class.new(AllSample)
+    klass1.identifier :one
+
+    klass2 = Class.new(AllSample)
+    klass2.identifier :two
+
+    assert_equal [ klass1, klass2 ], AllSample.all
+  end
+
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: ddplugin
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Denis Defreyne
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides plugin management for Ruby projects
+email: denis.defreyne@stoneship.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+- NEWS.md
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- NEWS.md
+- Rakefile
+- README.md
+- lib/ddplugin/plugin.rb
+- lib/ddplugin/registry.rb
+- lib/ddplugin/version.rb
+- lib/ddplugin.rb
+- test/helper.rb
+- test/test_plugin.rb
+- ddplugin.gemspec
+homepage: http://github.com/ddfreyne/ddplugin/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Plugins for Ruby apps
+test_files: []
+has_rdoc: