.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Class::Refresh 3pm" .TH Class::Refresh 3pm "2018-03-31" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Class::Refresh \- refresh your classes during runtime .SH "VERSION" .IX Header "VERSION" version 0.07 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Class::Refresh; \& use Foo; \& \& Class::Refresh\->refresh; \& \& # edit Foo.pm \& \& Class::Refresh\->refresh; # changes in Foo.pm are applied .Ve .SH "DESCRIPTION" .IX Header "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 \s-1REPL,\s0 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. .PP This module takes a hash of import arguments, which can include: .IP "track_require" 4 .IX Item "track_require" .Vb 1 \& use Class::Refresh track_require => 1; .Ve .Sp If set, a \f(CW\*(C`require()\*(C'\fR hook will be installed to track modules which are loaded. This will make the list of modules to reload when \f(CW\*(C`refresh\*(C'\fR is called more accurate, but may cause issues with other modules which hook into \&\f(CW\*(C`require\*(C'\fR (since the hook is global). .PP 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. .PP 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 \f(CW\*(C`Class::Refresh\*(C'\fR 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 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. .SH "METHODS" .IX Header "METHODS" .SS "refresh" .IX Subsection "refresh" The main entry point to the module. The first call to \f(CW\*(C`refresh\*(C'\fR populates a cache of modification times for currently loaded modules, and subsequent calls will refresh any classes which have changed since the previous call. .SS "modified_modules" .IX Subsection "modified_modules" Returns a list of modules which have changed since the last call to \f(CW\*(C`refresh\*(C'\fR. .ie n .SS "refresh_module $mod" .el .SS "refresh_module \f(CW$mod\fP" .IX Subsection "refresh_module $mod" This method calls \f(CW\*(C`unload_module\*(C'\fR and \f(CW\*(C`load_module\*(C'\fR on \f(CW$mod\fR, as well as on any classes that depend on \f(CW$mod\fR (for instance, subclasses if \f(CW$mod\fR is a class, or classes that consume \f(CW$mod\fR if \f(CW$mod\fR is a role). This ensures that all of your classes are consistent, even when dealing with things like immutable Moose classes. .ie n .SS "unload_module $mod" .el .SS "unload_module \f(CW$mod\fP" .IX Subsection "unload_module $mod" Unloads \f(CW$mod\fR, using Class::Unload. .ie n .SS "load_module $mod" .el .SS "load_module \f(CW$mod\fP" .IX Subsection "load_module $mod" Loads \f(CW$mod\fR, using Class::Load. .SH "CAVEATS" .IX Header "CAVEATS" .IP "Refreshing modules may miss modules which have been externally loaded since the last call to refresh" 4 .IX 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 \f(CW\*(C`track_require\*(C'\fR option in the import arguments (see above), although this comes with its own set of caveats (since it is global behavior). .IP "Global variable accesses and function calls may not work as expected" 4 .IX 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 \fBclasses\fR. .IP "File modification times have a granularity of one second" 4 .IX Item "File modification times have a granularity of one second" If you modify a file and then immediately call \f(CW\*(C`refresh\*(C'\fR and then immediately modify it again, the modification may not be seen on the next call to \&\f(CW\*(C`refresh\*(C'\fR. Note however that file size and inode number are also compared, so it still may be seen, depending on if either of those two things changed. .ie n .IP "Tracking modules which ""use"" a given module isn't possible" 4 .el .IP "Tracking modules which \f(CWuse\fR a given module isn't possible" 4 .IX Item "Tracking modules which use a given module isn't possible" For instance, modifying a Moose::Exporter module which is used in a class won't cause the class to be refreshed, even if the change to the exporter would cause a change in the class's metaclass. .IP "Classes which aren't completely defined in a single file and files which define multiple classes cause problems" 4 .IX Item "Classes which aren't completely defined in a single file and files which define multiple classes cause problems" If a class is defined across multiple files, there's no easy guaranteed way to restore the entire state of the class, since there may be load order issues. This includes Moose classes which have \f(CW\*(C`make_immutable\*(C'\fR called on them from outside of the class file itself. .Sp Also, files which define multiple classes cause problems since we can't always determine which classes are defined in the file, and so reloading the file may cause class definitions to be run more than once. .IP "Classes which build themselves differently based on the state of other classes may not work properly" 4 .IX Item "Classes which build themselves differently based on the state of other classes may not work properly" This module attempts to handle several cases of this sort for Moose classes (modifying a class will refresh all of its subclasses, modifying a role will refresh all classes and roles which consume that role, modifying a metaclass will refresh all classes whose metaclass is an instance of that metaclass), but it's not a problem that's solvable in the general case. .SH "BUGS" .IX Header "BUGS" .IP "Reloading classes when their metaclass is modified doesn't quite work yet" 4 .IX Item "Reloading classes when their metaclass is modified doesn't quite work yet" This will require modifications to Moose to support properly. .IP "Tracking changes to metaclasses other than the class metaclass isn't implemented yet" 4 .IX Item "Tracking changes to metaclasses other than the class metaclass isn't implemented yet" .PD 0 .IP "Metacircularity probably has issues" 4 .IX Item "Metacircularity probably has issues" .PD Refreshing a class which is its own metaclass will likely break. .PP Please report any bugs to GitHub Issues at . .SH "SEE ALSO" .IX Header "SEE ALSO" Module::Refresh .SH "SUPPORT" .IX Header "SUPPORT" You can find this documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Class::Refresh .Ve .PP You can also look for information at: .IP "\(bu" 4 MetaCPAN .Sp .IP "\(bu" 4 Github .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .SH "CREDITS" .IX Header "CREDITS" This module was based in large part on Module::Refresh by Jesse Vincent. .SH "AUTHOR" .IX Header "AUTHOR" Jesse Luehrs .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2014 by Jesse Luehrs. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.