Steven Lembark > Plugin-Installer-0.04 > Plugin::Installer

Download:
Plugin-Installer-0.04.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.10   Source  

NAME ^

Plugin::Installer

Call the plugin's compiler, install it via quality_to_ref, then dispatch it using goto.

SYNOPSIS ^

    package Myplugin;

    use base qw( Plugin::Installer Plugin::Language::Foobar );

    ...

    my $plugin = Myplugin->construct;

    # frobnicate is passed first to Plugin::Installer 
    # via AUTOLOAD, then to P::L::Foobar's compile
    # method. if what comes back from the compiler is
    # a referent it is intalled in the P::L::F namespace
    # and if it is a code referent it is dispatched.

    $plugin->frobnicate;

DESCRIPTION ^

The goal of this module is to provide a simple, flexable interface for developing plugin languages. Any language that can store its object data as a hash and implement a "compile" method that takes the method name as an argument can use this class. The Plugin framework gives runtime compile, install, and dispatch of user-defined code. The code doesn't have to be Perl, just something that the object handling it can compile.

The installer is language-agnostic: in fact it has no idea what the object does with the name passed to its compioer. All it does is (by default) install a returned reference and dispatch coderefs. This is intended as a convienence class that standardizes the top half of any plugin language.

Note that any referent returned by the compiler is installed. Handing back a hashref can deposit a hash into the caller's namespace. This allows for plugins to handle command line switches (via GetoptFoo and a hashref) or manipulate queues (by handing back an [udpated] arrayref.

By default coderefs are dispatched via goto, which allows the obvious use of compiling the plugin to an anonymous sub for later use. This make the plugins something of a trampoline object, with the exception that the "trampolines" are the class' methods rather than the object itself.

AUTOLOAD

Extracts the package and method name from a call, dispatches $package->compile( $name ), and handles the result. Results can be installed (if they are referents of any type) and dispatched (if they are coderefs).

The point of this is that the pluing language is free to compile the plugin source to whatever suits it best, Plugin::Installer will install the result.

In most cases the result will be a coderef, which will be installed as $AUTOLOAD, which allows plugins to resolve themselves from source to method at runtime.

DESTROY

Stub, saves passing back through the AUTOLOAD unnecessarly. Plugin classes that need housekeeping should implement a DESTROY of their own.

Plugin install metadata

During compilation, Plugin::Install::AUTOLOAD places an {install_meta} entry into the object. This is done via local hash value, and will not be visible to the caller after the autoloader has processed the call.

This defines switches used for post-compile handling:

    my $default_meta = 
    {
        install     => 1,
        dispatch    => 1,
        storemeta   => 0,

        alt_package => '',
    };
install => 1,

Does a referent returned from $obj->compile get installed into the namespace or simply dispatched?

This is used to avoid installing plugins whose contents will be re-defined during execution and called multiple times.

dispatch => 1,

Is a code referent dispatched (whether or not it is installed into a package)?

Some methods may be easier to pre-install but not dispatch immediately (e.g. if they involve expensive startup but have per-execution side-effects). Setting this to false will skip dispatch of coderef's even if they are installed.

alt_package => '',

Package to install the referent into (default if false is the object's package). This the namespace passed with the method name to 'qualify_to_ref'.

This can be used by the compiler to install data or coderef's into a caller's namespace (e.g. via caller(2)). If this is used with storemeta then ALL of the methods for the plugin class will be installed into the alternate package space unless they set their own alt_package when called.

storemeta => 0,

Store the current metdata as the default for this class? The metadata is stored by class name, allowing an initial "startup" call (say in the constructor or import) to configure appropriate defaults for the entire class.

Note that if install is true for a coderef then none of these matter much after the first call since the installed method will bypass the AUTOLOAD.

Corrilary: If a "setup" method is used to set metadata values then it probably should not be installed so that it can fondle the class' metadata and modify it if necewsary on later calls.

This also means that plugin languages should implement some sort of instructions to modify the metadata.

SEE ALSO ^

./t/01.t

Example plugin class with simple, working compiler.

Plugin::Language::DML

Little language for bulk data filtering, including pre- and post-processing DBI calls; uses Plugin::Install to handle method installation.

Symbol

Installing symbols without resoting to no strict 'refs'.

Scalar::Util

Extracting the basetype of a blessed referent.

Object::Trampoline

Trampoline object: construction and initilization are put off until a method is called on the compiled object.

AUTHORS ^

Steven Lembark <lembark@wrkhors.com> Florian Mayr <florian.mayr@gmail.com>

COPYRIGHT ^

Copyright (C) 2005 by the authors; this code can be reused and re-released under the same terms as Perl-5.8.0 or any later version of the Perl.

syntax highlighting: