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
andsmartify-quotes
.an image processing library with filters such as
resize
,desaturate
androtate
.a database driver abstraction with connectors such as
postgres
,sqlite3
andmysql
.a document management system with data sources such as
filesystem
anddatabase
.
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.
Requirements
ddplugin requires Ruby 2.1 or higher.
Versioning
ddplugin adheres to Semantic Versioning 2.0.0.
Installation
If your library where you want to use ddplugin has a gemspec, add ddplugin as a runtime dependency to the gemspec:
spec.add_runtime_dependency 'ddplugin', '~> 1.0'
If you use Bundler instead, add it to the Gemfile
:
gem 'ddplugin', '~> 1.0'
Usage
Plugin type are classes that extend DDPlugin::Plugin
:
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:
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:
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:
Filter.all
# => [ ERBFilter, HamlFilter ]
DataSource.all
# => [ FilesystemDataSource, PostgresDataSource ]
To get the identifier of a plugin, call .identifier
:
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 source code documentation are still up-to-date.
To run the tests, execute rake
:
% rake