Hi folks on the modules list,
I'd like permission to submit a module called Devel::Reloader that's similar to the
concept of Apache::StatInc but serves as a more general-purpose development tool.
To describe it, I'm pasting the entire contents of the .pm file, which is more pod
than code, below, since the pod docs are fairly complete.
Thanks for your consideration, and also any advice or pointers you have time to offer
before I release this module to the public.
Sincerely,
-chris
-- Begin wide page width; tab stops of 4 --
#!/usr/bin/perl
use strict;
package Devel::Reloader;
=pod
Devel::Reloader
Copyright (c) 2000, INNX, Inc. http://innx.com
Released to the public under the terms of the Perl Artistic License.
SYNOPSIS
Instead of:
useFoobar::MyModule(@ImportArgs);
Do this:
use Devel::Reloader;
Devel::Reloader->reload(qw(Foobar::MyModule));
import Foobar::MyModule(@ImportArgs);
Or, instead of:
useFoobar::MyModule;
Do this:
use Devel::Reloader;
Devel::Reloader->reload(qw(Foobar::MyModule));
(assuming you don't need "import" semantics from Foobar::MyModule)
OVERVIEW
This module defines a "relaod" routine that scripts, CGI scripts,
Embperl scripts, handlers, etc. can use to reload (re-require) a
module or modules, optionally forcing the modules AND ANY MODULES THEY
USE, recursively, to reload, even if already previously loaded and
listed in %INC.
The reloading feature is helpful for when you're actively writing and
debugging modules intended to be used with Apache and mod_perl (either
used by Apache::Registry or HTML::Embperl script, or handlers, or
other mechanisms) and want to ensure that your code changes get
reloaded on every hit, even if the module had previously been loaded
into the parent or child process.
Before reloading, this module can dynamically prepend some additional
paths to @INC to allow programmers to work on, test, and debug
development copies of modules in a private directory while other
modules are loaded from a more stable library directory.
The @INC-modifying feature is helpful even if you're only developing
command-line perl scripts in an environment where there are multiple
programmers and an individual programmer, for testing purposes, needs
to optionally load some modules under development from his or her own
private source directory in preference to the "standard" locations.
How this module differs from Apache::StatINC:
- Reloads requested modules (recursively) regardless of
modification date.
- Skips reloading any modules that have been previously loaded
from lib/perl* (or other customizable list of dir name
patterns), so you can only reload items outside the standard
library locations, by default.
- Allows dynamic overriding of @INC on a per-USER basis.
- This module lacks StatINC's ability to disable symbol-redef
warnings, so best not to reload modules with const
subroutines... (sorry).
- Works outside of Apache as well as within it (not sure whether
this is true of Apache::StatINC), so is testable from the
command line, and even useful in a batch script context, if not
for its reloading capabilities, then at least for its ability to
override the search path on a per-USER basis, allowing the
development and debugging of a private copy of a system-wide
module or modules.
- Works fine from within individual pages or scripts; does not
necessarily need to be loaded at server startup time.
- Is a no-op (does not reload) unless certain environment
variables and/or options are set, allowing you to leave calls to
it in production code with negligible performance hit on
non-debugging servers.
DISCUSSION
To request that a module Foobar::MyModule, and any modules it calls,
be reloaded, do this:
use Devel::Reloader;
Devel::Reloader->reload(qw(Foobar::MyModule));
This reloads the module, executing its BEGIN blocks, syntax-checking
it, and recompiling any subroutines it has.
Then, if you want to import any semantics from the module into the
current namespace, you should directly "import" the module.
import Foobar::MyModule(@ImportArgs);
Under normal circumstances, reload will load the module normally with
no difference from the usual behavior of "use" ... i.e. files won't be
reloaded if they already have been, and no special modifications to
@INC will be applied.
BUT, if certain environment variables (see below) are set to non-false
values, Devel::Reloader will force them and any modules THEY need, to
be reloaded from their source file every time, also using temporary
modifications to @INC.
The variables are:
$ENV{RLD} ## Useful for command-line testin
