oops, forgot to add this to svn

lib/WebGUI/Pluggable.pm

@@ -0,0 +1,136 @@
+package WebGUI::Pluggable;
+
+=head1 LEGAL
+
+ -------------------------------------------------------------------
+  WebGUI is Copyright 2001-2008 Plain Black Corporation.
+ -------------------------------------------------------------------
+  Please read the legal notices (docs/legal.txt) and the license
+  (docs/license.txt) that came with this distribution before using
+  this software.
+ -------------------------------------------------------------------
+  http://www.plainblack.com                     info@plainblack.com
+ -------------------------------------------------------------------
+
+=cut
+
+use strict;
+use Carp qw(croak);
+
+=head1 NAME
+
+Package WebGUI::Pluggable
+
+=head1 DESCRIPTION
+
+This package provides a standard way of quickly and safely dynamically loading plugins. 
+
+=head1 SYNOPSIS
+
+ use WebGUI::Pluggable;
+
+ WebGUI::Pluggable::load($module);
+
+ my $object = WebGUI::Pluggable::instanciate($module, $method, \@params);
+
+ my $output = WebGUI::Pluggable::run($module, $function, \@params);
+
+=head1 FUNCTIONS
+
+These functions are available from this package:
+
+=cut
+
+#-------------------------------------------------------------------
+
+=head2 instanciate ( module, method, params )
+
+Dynamically ensures that a plugin module is loaded into memory. Then instanciates a new object from the module. Croaks on failure.
+
+=head3 module
+
+The name of the module you'd like to load like "WebGUI::Asset::Snippet";
+
+=cut
+
+sub instanciate {
+    my ($module, $sub, $params) = @_;
+    eval { load($module) };
+    if ($@) {
+        croak "Could not instanciate object using $sub on $module because $module could not be loaded.";
+    }
+    else {
+        my $object = eval{$module->$sub(@{$params})};
+        if ($@) {
+            croak "Could not instanciate object using $sub on $module because $@";
+        }
+        else {
+            return $object;
+        }
+    }
+}
+
+#-------------------------------------------------------------------
+
+=head2 load ( module )
+
+Dynamically ensures that a plugin module is loaded into memory. Croaks on failure.
+
+=head3 module
+
+The name of the module you'd like to load like "WebGUI::Asset::Snippet";
+
+=cut
+
+sub load {
+    my $module = shift;
+    my $modulePath = $module.".pm";
+    $modulePath =~ s{::}{/}g;
+    eval { require $modulePath };
+    if ($@) {
+        croak "Could not load $module because $@";
+    }
+}
+
+#-------------------------------------------------------------------
+
+=head2 run ( module, sub, params )
+
+Dynamically ensures that a plugin module is loaded into memory. Then executes a function in that new module.  Croaks on failure.
+
+=head3 module
+
+The name of the module you'd like to load like "WebGUI::Asset::Snippet";
+
+=head3 sub
+
+The name of a subroutine to execute.
+
+=head3 params
+
+An array reference of parameters to pass in to the sub routine.
+
+=cut
+
+sub run {
+    my ($module, $sub, $params) = @_;
+    eval { load($module) };
+    if ($@) {
+        croak "Could not run $sub on $module because $module could not be loaded.";
+    }
+    else {
+        my $command = $module."::".$sub;
+        no strict qw(refs);
+        my $out = eval { &$command(@{$params}) };
+        use strict;
+        if ($@) {
+            croak "Could not run $sub on $module because $@";
+        }
+        else {
+            return $out;
+        }
+    }
+}
+
+1;
+