SoundSoftware Code Site

module CodeRay

# = PluginHost

#

# A simple subclass plugin system.

#

#  Example:

#    class Generators < PluginHost

#      plugin_path 'app/generators'

#    end

#    

#    class Generator

#      extend Plugin

#      PLUGIN_HOST = Generators

#    end

#    

#    class FancyGenerator < Generator

#      register_for :fancy

#    end

#

#    Generators[:fancy]  #-> FancyGenerator

#    # or

#    CodeRay.require_plugin 'Generators/fancy'

module PluginHost

  # Raised if Encoders::[] fails because:

  # * a file could not be found

  # * the requested Encoder is not registered

  PluginNotFound = Class.new Exception

  HostNotFound = Class.new Exception

  PLUGIN_HOSTS = []

  PLUGIN_HOSTS_BY_ID = {}  # dummy hash

  # Loads all plugins using list and load.

  def load_all

    for plugin in list

      load plugin

    end

  end

  # Returns the Plugin for +id+.

  #

  # Example:

  #  yaml_plugin = MyPluginHost[:yaml]

  def [] id, *args, &blk

    plugin = validate_id(id)

    begin

      plugin = plugin_hash.[] plugin, *args, &blk

    end while plugin.is_a? Symbol

    plugin

  end

  # Alias for +[]+.

  alias load []

  def require_helper plugin_id, helper_name

    path = path_to File.join(plugin_id, helper_name)

    require path

  end

  class << self

    # Adds the module/class to the PLUGIN_HOSTS list.

    def extended mod

      PLUGIN_HOSTS << mod

    end

    # Warns you that you should not #include this module.

    def included mod

      warn "#{name} should not be included. Use extend."

    end

    # Find the PluginHost for host_id.

    def host_by_id host_id

      unless PLUGIN_HOSTS_BY_ID.default_proc

        ph = Hash.new do |h, a_host_id|

          for host in PLUGIN_HOSTS

            h[host.host_id] = host

          end

          h.fetch a_host_id, nil

        end

        PLUGIN_HOSTS_BY_ID.replace ph

      end

      PLUGIN_HOSTS_BY_ID[host_id]

    end

  end

  # The path where the plugins can be found.

  def plugin_path *args

    unless args.empty?

      @plugin_path = File.expand_path File.join(*args)

      load_map

    end

    @plugin_path

  end

  # The host's ID.

  #

  # If PLUGIN_HOST_ID is not set, it is simply the class name.

  def host_id

    if self.const_defined? :PLUGIN_HOST_ID

      self::PLUGIN_HOST_ID

    else

      name

    end

  end

  # Map a plugin_id to another.

  #

  # Usage: Put this in a file plugin_path/_map.rb.

  #

  #  class MyColorHost < PluginHost

  #    map :navy => :dark_blue,

  #      :maroon => :brown,

  #      :luna => :moon

  #  end

  def map hash

    for from, to in hash

      from = validate_id from

      to = validate_id to

      plugin_hash[from] = to unless plugin_hash.has_key? from

    end

  end

  # Define the default plugin to use when no plugin is found

  # for a given id.

  #

  # See also map.

  #

  #  class MyColorHost < PluginHost

  #    map :navy => :dark_blue

  #    default :gray

  #  end

  def default id = nil

    if id

      id = validate_id id

      plugin_hash[nil] = id

    else

      plugin_hash[nil]

    end

  end

  # Every plugin must register itself for one or more

  # +ids+ by calling register_for, which calls this method.

  #

  # See Plugin#register_for.

  def register plugin, *ids

    for id in ids

      unless id.is_a? Symbol

        raise ArgumentError,

          "id must be a Symbol, but it was a #{id.class}"

      end

      plugin_hash[validate_id(id)] = plugin

    end

  end

  # A Hash of plugion_id => Plugin pairs.

  def plugin_hash

    @plugin_hash ||= create_plugin_hash

  end

  # Returns an array of all .rb files in the plugin path.

  #

  # The extension .rb is not included.

  def list

    Dir[path_to('*')].select do |file|

      File.basename(file)[/^(?!_)\w+\.rb$/]

    end.map do |file|

      File.basename file, '.rb'

    end

  end

  # Makes a map of all loaded plugins.

  def inspect

    map = plugin_hash.dup

    map.each do |id, plugin|

      map[id] = plugin.to_s[/(?>\w+)$/]

    end

    "#{name}[#{host_id}]#{map.inspect}"

  end

protected

  # Created a new plugin list and stores it to @plugin_hash.

  def create_plugin_hash

    @plugin_hash =

      Hash.new do |h, plugin_id|

        id = validate_id(plugin_id)

        path = path_to id

        begin

          require path

        rescue LoadError => boom

          if h.has_key? nil  # default plugin

            h[id] = h[nil]

          else

            raise PluginNotFound, 'Could not load plugin %p: %s' % [id, boom]

          end

        else

          # Plugin should have registered by now

          unless h.has_key? id

            raise PluginNotFound,

              "No #{self.name} plugin for #{id.inspect} found in #{path}."

          end

        end

        h[id]

      end

  end

  # Loads the map file (see map).

  #

  # This is done automatically when plugin_path is called.

  def load_map

    mapfile = path_to '_map'

    if File.exist? mapfile

      require mapfile

    elsif $VERBOSE

      warn 'no _map.rb found for %s' % name

    end

  end

  # Returns the Plugin for +id+.

  # Use it like Hash#fetch.

  #

  # Example:

  #  yaml_plugin = MyPluginHost[:yaml, :default]

  def fetch id, *args, &blk

    plugin_hash.fetch validate_id(id), *args, &blk

  end

  # Returns the expected path to the plugin file for the given id.

  def path_to plugin_id

    File.join plugin_path, "#{plugin_id}.rb"

  end

  # Converts +id+ to a Symbol if it is a String,

  # or returns +id+ if it already is a Symbol.

  #

  # Raises +ArgumentError+ for all other objects, or if the

  # given String includes non-alphanumeric characters (\W).

  def validate_id id

    if id.is_a? Symbol or id.nil?

      id

    elsif id.is_a? String

      if id[/\w+/] == id

        id.downcase.to_sym

      else

        raise ArgumentError, "Invalid id: '#{id}' given."

      end

    else

      raise ArgumentError,

        "String or Symbol expected, but #{id.class} given."

    end

  end

end

# = Plugin

#

#  Plugins have to include this module.

#

#  IMPORTANT: use extend for this module.

#

#  Example: see PluginHost.

module Plugin

  def included mod

    warn "#{name} should not be included. Use extend."

  end

  # Register this class for the given langs.

  # Example:

  #   class MyPlugin < PluginHost::BaseClass

  #     register_for :my_id

  #     ...

  #   end

  #

  # See PluginHost.register.

  def register_for *ids

    plugin_host.register self, *ids

  end

  # Returns the title of the plugin, or sets it to the

  # optional argument +title+.

  def title title = nil

    if title

      @title = title.to_s

    else

      @title ||= name[/([^:]+)$/, 1]

    end

  end

  # The host for this Plugin class.

  def plugin_host host = nil

    if host and not host.is_a? PluginHost

      raise ArgumentError,

        "PluginHost expected, but #{host.class} given."

    end

    self.const_set :PLUGIN_HOST, host if host

    self::PLUGIN_HOST

  end

  # Require some helper files.

  #

  # Example:

  #

  #  class MyPlugin < PluginHost::BaseClass

  #     register_for :my_id

  #     helper :my_helper

  #

  # The above example loads the file myplugin/my_helper.rb relative to the

  # file in which MyPlugin was defined.

  # 

  # You can also load a helper from a different plugin:

  # 

  #  helper 'other_plugin/helper_name'

  def helper *helpers

    for helper in helpers

      if helper.is_a?(String) && helper[/\//]

        self::PLUGIN_HOST.require_helper $`, $'

      else

        self::PLUGIN_HOST.require_helper plugin_id, helper.to_s

      end

    end

  end

  # Returns the pulgin id used by the engine.

  def plugin_id

    name[/\w+$/].downcase

  end

end

# Convenience method for plugin loading.

# The syntax used is:

#

#  CodeRay.require_plugin '<Host ID>/<Plugin ID>'

#

# Returns the loaded plugin.

def self.require_plugin path

  host_id, plugin_id = path.split '/', 2

  host = PluginHost.host_by_id(host_id)

  raise PluginHost::HostNotFound,

    "No host for #{host_id.inspect} found." unless host

  host.load plugin_id

end

end