Module: RUtilAnts::Plugins

Defined in:
lib/rUtilAnts/Plugins.rb

Overview

Module that defines a generic way to handle plugins:

  • No pre-load: plugins files are required when needed only

  • Description files support: plugins files can give a description file, enumerating their dependencies, description…

  • Support for plugins categories

  • [If RDI is present]: Try to install dependencies before loading plugin instances

Here are the following symbols that can be used in plugins’ descriptions and are already interpreted by rUtilAnts:

  • Dependencies (list<RDI::Model::DependencyDescription>): List of dependencies this plugin depends on

  • PluginsDependencies (list[String,String]): List of other plugins ([Category,Plugin]) this plugin depends on

  • Enabled (Boolean): Can this plugin be loaded ?

Here are the symbols that are reserved bu rUtilAnts:

  • PluginInstance (Object): The real plugin instance

  • PluginFileName (String): The plugin’s file name (or nil if none)

  • PluginClassName (String): Name of the plugin’s class to instantiate

  • PluginInitCode (Proc): Code to call when instantiating the plugin (or nil if none)

  • PluginIndex (Integer): Unique incremental ID identifying the plugin in its category

  • PluginName (String): Name of the plugin

  • PluginCategoryName (String): Name of the category of the plugin

Defined Under Namespace

Classes: DisabledPluginError, FailedPluginError, PluginDependenciesError, PluginDependenciesIgnoredError, PluginDependenciesUnresolvedError, PluginsManager, UnknownCategoryError, UnknownPluginError

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.initializePlugins ⇒ Object

Initialize a plugins singleton



376
377
378
379
 
# File 'lib/rUtilAnts/Plugins.rb', line 376

def self.initializePlugins
  $rUtilAnts_Plugins_Manager = PluginsManager.new
  Object.module_eval('include RUtilAnts::Plugins')
end

Instance Method Details

#accessPlugin(iCategoryName, iPluginName, iParameters = {}) ⇒ Object

Give access to a plugin. An exception is thrown if the plugin does not exist.

Parameters:

  • iCategoryName (String): Category of the plugin to access

  • iPluginName (String): Name of the plugin to access

  • iParameters (map<Symbol,Object>): Additional parameters:

** OnlyIfExtDepsResolved (Boolean): Do we return the plugin only if there is no need to install external dependencies ? [optional = false] ** RDIInstaller (RDI::Installer): The RDI installer if available, or nil otherwise [optional = nil] ** RDIContextModifiers (map<String,list<[String,Object]>>): The map of context modifiers to be filled by the RDI installer if specified, or nil if ignored [optional = nil]

  • CodeBlock: The code called when the plugin is found:

** ioPlugin (Object): The corresponding plugin



443
444
445
446
447
 
# File 'lib/rUtilAnts/Plugins.rb', line 443

def accessPlugin(iCategoryName, iPluginName, iParameters = {})
  $rUtilAnts_Plugins_Manager.accessPlugin(iCategoryName, iPluginName, iParameters) do |ioPlugin|
    yield(ioPlugin)
  end
end

#clearPlugins ⇒ Object

Clear the registered plugins



450
451
452
 
# File 'lib/rUtilAnts/Plugins.rb', line 450

def clearPlugins
  $rUtilAnts_Plugins_Manager.clearPlugins
end

#getPluginDescription(iCategory, iPluginName) ⇒ Object

Get the named plugin description

Parameters:

  • iCategory (Object): Category those plugins will belong to

  • iPluginName (String): Plugin name

Return:

  • map<Symbol,Object>: The corresponding description, or nil in case of failure



427
428
429
 
# File 'lib/rUtilAnts/Plugins.rb', line 427

def getPluginDescription(iCategory, iPluginName)
  return $rUtilAnts_Plugins_Manager.getPluginDescription(iCategory, iPluginName)
end

#getPluginInstance(iCategory, iPluginName, iParameters = {}) ⇒ Object

Get the named plugin instance

Parameters:

  • iCategory (Object): Category those plugins will belong to

  • iPluginName (String): Plugin name

  • iParameters (map<Symbol,Object>): Additional parameters:

** OnlyIfExtDepsResolved (Boolean): Do we return the plugin only if there is no need to install external dependencies ? [optional = false] ** RDIInstaller (RDI::Installer): The RDI installer if available, or nil otherwise [optional = nil] ** RDIContextModifiers (map<String,list<[String,Object]>>): The map of context modifiers to be filled by the RDI installer if specified, or nil if ignored [optional = nil] Return:

  • Object: The corresponding plugin, or nil in case of failure

  • Exception: The error, or nil in case of success



416
417
418
 
# File 'lib/rUtilAnts/Plugins.rb', line 416

def getPluginInstance(iCategory, iPluginName, iParameters = {})
  return $rUtilAnts_Plugins_Manager.getPluginInstance(iCategory, iPluginName, iParameters)
end

#getPluginNames(iCategoryName, iParameters = {}) ⇒ Object

Get the list of plugin names of a given category

Parameters:

  • iCategoryName (String): The category for which we want the plugin names list

  • iParameters (map<Symbol,Object>): Additional parameters:

** IncludeDisabled (Boolean): Do we include disabled plugins ? [optional = false] Return:

  • list<String>: The list of plugin names in this category



462
463
464
 
# File 'lib/rUtilAnts/Plugins.rb', line 462

def getPluginNames(iCategoryName, iParameters = {})
  return $rUtilAnts_Plugins_Manager.getPluginNames(iCategoryName, iParameters)
end

#getPluginsDescriptions(iCategoryName, iParameters = {}) ⇒ Object

Get the map of plugins descriptions, indexed with plugin names

Parameters:

  • iCategoryName (String): The category for which we want the plugin names list

  • iParameters (map<Symbol,Object>): Additional parameters:

** IncludeDisabled (Boolean): Do we include disabled plugins ? [optional = false] Return:

  • map<String,map<Symbol,Object>>: The map of plugin descriptions per plugin name



474
475
476
 
# File 'lib/rUtilAnts/Plugins.rb', line 474

def getPluginsDescriptions(iCategoryName, iParameters = {})
  return $rUtilAnts_Plugins_Manager.getPluginsDescriptions(iCategoryName, iParameters)
end

#parsePluginsFromDir(iCategory, iDir, iBaseClassNames) ⇒ Object

Parse plugins from a given directory

Parameters:

  • iCategory (Object): Category those plugins will belong to

  • iDir (String): Directory to parse for plugins

  • iBaseClassNames (String): The base class name of plugins to be instantiated



400
401
402
 
# File 'lib/rUtilAnts/Plugins.rb', line 400

def parsePluginsFromDir(iCategory, iDir, iBaseClassNames)
  $rUtilAnts_Plugins_Manager.parsePluginsFromDir(iCategory, iDir, iBaseClassNames)
end

#registerNewPlugin(iCategoryName, iPluginName, iFileName, iDesc, iClassName, iInitCodeBlock) ⇒ Object

Register a new plugin

Parameters:

  • iCategoryName (String): Category this plugin belongs to

  • iPluginName (String): Plugin name

  • iFileName (String): File name containing the plugin (can be nil)

  • iDesc (map<Symbol,Object>): Plugin’s description (can be nil)

  • iClassName (String): Name of the plugin class

  • iInitCodeBlock (Proc): Code block to call when initializing the real instance (can be nil)



390
391
392
 
# File 'lib/rUtilAnts/Plugins.rb', line 390

def registerNewPlugin(iCategoryName, iPluginName, iFileName, iDesc, iClassName, iInitCodeBlock)
  $rUtilAnts_Plugins_Manager.registerNewPlugin(iCategoryName, iPluginName, iFileName, iDesc, iClassName, iInitCodeBlock)
end