Plugins

History / Motivation

bel.rb provides a lightweight plugin mechanism to extend implementations of core APIs. The motivation was to support different evidence document formats without having to maintain each and every one within the bel.rb repository. Now we can leverage this mechanism to extend other parts of the library where it's useful to do so.

Design

bel.rb includes the little-plugger gem, vendored as a single ruby file, to provide the plugin mechanism. Little Plugger will discover a plugin based on the name of its ruby source file and where it is found on ruby's LOAD_PATH. The ruby source file is loaded with ruby's require method.

The ruby source file must define a ruby module under the module that Little Plugger extends. Let's look at an example using evidence translator plugins.

Plugin directory on the LOAD_PATH:

# plugin base path
bel/translator/plugins
# plugin file for BelScript
bel/translator/plugins/bel_script.rb
# plugin file for Xbel
bel/translator/plugins/xbel.rb

Now we need to define a module that extends LittlePlugger. Additional configuration is provided to be explicit about the location of plugins.

module BEL

  # The Translator module defines a plugin that reads a specific document
  # format into BEL evidence and writes BEL evidence back to this document
  # format.
  #
  # - Read
  #   - {#read}:            read the input format and parse to
  #     {::BEL::Model::Evidence} objects
  # - Write
  #   - {#write}:           write {::BEL::Model::Evidence} objects to the
  #     output format
  module Translator

    # The Plugins module provides a namespace for translator plugins.
    # Translator plugins must be defined within {::BEL::Translator::Plugins}
    # in order to be discovered.
    module Plugins; end

    # Set BEL::Translator as a plugin container. All plugins are loaded from
    # +bel/translator/plugins+ on the +LOAD_PATH+. Each plugin must define a
    # module within {::BEL::Translator::Plugins} that corresponds to the file
    # in the plugin path. For example the plugin module
    # +::BEL::Translator::Plugins::Foo+ must be defined within the file
    # +bel/translator/plugins/foo.rb+.
    extend LittlePlugger(
      :path   => 'bel/translator/plugins',
      :module => BEL::Translator::Plugins
    )
  end
end

Now we can define BEL Script and XBEL plugins.

Complete Example

The bel.rb-search-sqlite repository contains a Resource Search plugin for bel.rb. It highlights the minimal files and conventions needed to plug-in to bel.rb.