view release on metacpan or  search on metacpan

lib/Class/Refresh.pm  view on Meta::CPAN

    my $file = $mod;
    $file =~ s{::}{/}g;
    $file .= '.pm';

    return $file;
}


1;

__END__

=pod

=head1 NAME

Class::Refresh - refresh your classes during runtime

=head1 VERSION

version 0.07

=head1 SYNOPSIS

  use Class::Refresh;
  use Foo;

  Class::Refresh->refresh;

  # edit Foo.pm

  Class::Refresh->refresh; # changes in Foo.pm are applied

=head1 DESCRIPTION

During development, it is fairly common to cycle between writing code and
testing that code. Generally the testing happens within the test suite, but
frequently it is more convenient to test things by hand when tracking down a
bug, or when doing some exploratory coding. In many situations, however, this
becomes inconvenient - for instance, in a REPL, or in a stateful web
application, restarting from the beginning after every code change can get
pretty tedious. This module allows you to reload your application classes on
the fly, so that the code/test cycle becomes a lot easier.

This module takes a hash of import arguments, which can include:

=over 4

=item track_require

  use Class::Refresh track_require => 1;

If set, a C<require()> hook will be installed to track modules which are
loaded. This will make the list of modules to reload when C<refresh> is called
more accurate, but may cause issues with other modules which hook into
C<require> (since the hook is global).

=back

This module has several limitations, due to reloading modules in this way being
an inherently fragile operation. Therefore, this module is recommended for use
only in development environments - it should not be used for reloading things
in production.

It makes several assumptions about how code is structured that simplify the
logic involved quite a bit, and make it more reliable when those assumptions
hold, but do make it inappropriate for use in certain cases. For instance, this
module is named C<Class::Refresh> for a reason: it is only intended for
refreshing classes, where each file contains a single namespace, and each
namespace corresponds to a single file, and all function calls happen through
method dispatch. Unlike L<Module::Refresh>, which makes an effort to track the
files where subs were defined, this module assumes that refreshing a class
means wiping out everything in the class's namespace, and reloading the file
corresponding to that class. If your code includes multiple files that all load
things into a common namespace, or defines multiple classes in a single file,
this will likely not work.

=head1 METHODS

=head2 refresh

The main entry point to the module. The first call to C<refresh> populates a
cache of modification times for currently loaded modules, and subsequent calls
will refresh any classes which have changed since the previous call.

=head2 modified_modules

Returns a list of modules which have changed since the last call to C<refresh>.

=head2 refresh_module $mod

This method calls C<unload_module> and C<load_module> on C<$mod>, as well as on
any classes that depend on C<$mod> (for instance, subclasses if C<$mod> is a
class, or classes that consume C<$mod> if C<$mod> is a role). This ensures that
all of your classes are consistent, even when dealing with things like
immutable L<Moose> classes.

=head2 unload_module $mod

Unloads C<$mod>, using L<Class::Unload>.

=head2 load_module $mod

Loads C<$mod>, using L<Class::Load>.

=head1 CAVEATS

=over 4

=item Refreshing modules may miss modules which have been externally loaded since the last call to refresh

This is because it's not easily possible to tell if a module has been modified
since it was loaded, if we haven't seen it so far. A workaround for this may be
to set the C<track_require> option in the import arguments (see above),
although this comes with its own set of caveats (since it is global behavior).

=item Global variable accesses and function calls may not work as expected

Perl resolves accesses to global variables and functions in other packages at
compile time, so if the package is later reloaded, changes to those will not be
noticed. As mentioned above, this module is intended for refreshing B<classes>.