NAME "Module::PluginFinder" - automatically choose the most appropriate plugin module. SYNOPSIS use Module::PluginFinder; my $finder = Module::PluginFinder->new( search_path => 'MyApp::Plugin', filter => sub { my ( $module, $searchkey ) = @_; $module->can( $searchkey ); }, ); my $ball = $finder->construct( "bounce" ); $ball->bounce(); my $fish = $finder->construct( "swim" ); $fish->swim(); DESCRIPTION This module provides a factory class. Objects in this class search for a specific plugin module to fit some criteria. Each time a new object is to be constructed by the factory, the caller should provide a value which in some way indicates the kind of object required. The factory's filter function is then used to determine which plugin module fits the criteria. The most flexible way to determine the required module is to provide a filter function. When looking for a suitable module, the function is called once for each candidate module, and is passed the module's name and the search key. The function can then return a boolean to indicate whether the module will be suitable. The value of the search key is not directly used by the "Module::PluginFinder" in this case, and therefore is not restricted to being a simple scalar value; any sort of reference may be passed. Instead of a filter function, the factory can inspect a package variable or constant method in each of the candidate modules, looking for a string match with the search key; see the "typevar" and "typefunc" constructor arguments. When using this construction, a map from type names to module names will be cached at the time the "Module::PluginFinder" object is created, and will therefore not be sensitive to changes in the values once this is done. Because of this, the key should be a simple string, rather than a reference. CONSTRUCTOR $finder = Module::PluginFinder->new( %args ) Constructs a new "Module::PluginFinder" factory object. The constructor will search the module path for all available plugins, as determined by the "search_path" key and store them. The %args hash must take the following keys: search_path => STRING or ARRAY A string declaring the module namespace, or an array reference of module namespaces to search for plugins (passed to Module::Pluggable::Object). In order to specify the way candidate modules are selected, one of the following keys must be supplied. filter => CODE The filter function for determining whether a module is suitable as a plugin typevar => STRING The name of a package variable to match against the search key typefunc => STRING The name of a package method to call to return the type name. The method will be called in scalar context with no arguments; as $type = $module->$typefunc(); If it returns "undef" or throws an exception, then the module will be ignored METHODS @modules = $finder->modules() Returns the list of module names available to the finder. $module = $finder->find_module( $searchkey ) Search for a plugin module that matches the search key. Returns the name of the first module for which the filter returns true, or "undef" if no suitable module was found. $searchkey A value to pass to the stored filter function. $object = $finder->construct( $searchkey, @constructorargs ) Search for a plugin module that matches the search key, then attempt to create a new object in that class. If a suitable module is found to match the $searchkey then the "new" method is called on it, passing the @constructorargs. If no suitable module is found then an exception is thrown. $searchkey A value to pass to the stored filter function. @constructorargs A list to pass to the class constructor. $finder->rescan() Perform another search for plugin modules. This method is useful whenever new modules may be present since the object was first constructed. EXAMPLES The filter function allows various ways to select plugin modules on different criteria. The following examples indicate a few ways to do this. Availability of a function / method my $f = Module::PluginFinder->new( search_path => ..., filter => sub { my ( $module, $searchkey ) = @_; return $module->can( $searchkey ); }, ); Each plugin then simply has to implement the required function or method in order to be automatically selected. Value of a method call my $f = Module::PluginFinder->new( search_path => ..., filter => sub { my ( $module, $searchkey ) = @_; return 0 unless $module->can( "is_plugin_for" ); return $module->is_plugin_for( $searchkey ); }, ); Each plugin then needs to implement a method called "is_plugin_for", that should examine the $searchkey and perform whatever testing it requires, then return a boolean to indicate if the plugin is suitable. Value of a constant Because a constant declared by the "use constant" pragma is a plain function, it can be called by the "typefunc" filter: my $f = Module::PluginFinder->new( search_path => ..., typefunc => 'PLUGIN_TYPE', ); Each plugin can then declare its type using a constuction like use constant PLUGIN_TYPE => "my type here"; Alternatively, a normal package method may be created that performs any work required to determine the plugin's type sub PLUGIN_TYPE { my $class = shift; ... return $typename; } Note that the type function in each module will only be called once, and the returned value cached. Value of a package scalar The "typevar" constructor argument generates the filter function automatically. my $f = Module::PluginFinder->new( search_path => ..., typevar => 'PLUGIN_TYPE', ); Each plugin can then declare its type using a normal "our" scalar variable: our $PLUGIN_TYPE = "my type here"; SEE ALSO * Module::Pluggable - automatically give your module the ability to have plugins AUTHOR Paul Evans