1Class::Refresh(3)     User Contributed Perl Documentation    Class::Refresh(3)
2
3
4

NAME

6       Class::Refresh - refresh your classes during runtime
7

VERSION

9       version 0.07
10

SYNOPSIS

12         use Class::Refresh;
13         use Foo;
14
15         Class::Refresh->refresh;
16
17         # edit Foo.pm
18
19         Class::Refresh->refresh; # changes in Foo.pm are applied
20

DESCRIPTION

22       During development, it is fairly common to cycle between writing code
23       and testing that code. Generally the testing happens within the test
24       suite, but frequently it is more convenient to test things by hand when
25       tracking down a bug, or when doing some exploratory coding. In many
26       situations, however, this becomes inconvenient - for instance, in a
27       REPL, or in a stateful web application, restarting from the beginning
28       after every code change can get pretty tedious. This module allows you
29       to reload your application classes on the fly, so that the code/test
30       cycle becomes a lot easier.
31
32       This module takes a hash of import arguments, which can include:
33
34       track_require
35             use Class::Refresh track_require => 1;
36
37           If set, a "require()" hook will be installed to track modules which
38           are loaded. This will make the list of modules to reload when
39           "refresh" is called more accurate, but may cause issues with other
40           modules which hook into "require" (since the hook is global).
41
42       This module has several limitations, due to reloading modules in this
43       way being an inherently fragile operation. Therefore, this module is
44       recommended for use only in development environments - it should not be
45       used for reloading things in production.
46
47       It makes several assumptions about how code is structured that simplify
48       the logic involved quite a bit, and make it more reliable when those
49       assumptions hold, but do make it inappropriate for use in certain
50       cases. For instance, this module is named "Class::Refresh" for a
51       reason: it is only intended for refreshing classes, where each file
52       contains a single namespace, and each namespace corresponds to a single
53       file, and all function calls happen through method dispatch. Unlike
54       Module::Refresh, which makes an effort to track the files where subs
55       were defined, this module assumes that refreshing a class means wiping
56       out everything in the class's namespace, and reloading the file
57       corresponding to that class. If your code includes multiple files that
58       all load things into a common namespace, or defines multiple classes in
59       a single file, this will likely not work.
60

METHODS

62   refresh
63       The main entry point to the module. The first call to "refresh"
64       populates a cache of modification times for currently loaded modules,
65       and subsequent calls will refresh any classes which have changed since
66       the previous call.
67
68   modified_modules
69       Returns a list of modules which have changed since the last call to
70       "refresh".
71
72   refresh_module $mod
73       This method calls "unload_module" and "load_module" on $mod, as well as
74       on any classes that depend on $mod (for instance, subclasses if $mod is
75       a class, or classes that consume $mod if $mod is a role). This ensures
76       that all of your classes are consistent, even when dealing with things
77       like immutable Moose classes.
78
79   unload_module $mod
80       Unloads $mod, using Class::Unload.
81
82   load_module $mod
83       Loads $mod, using Class::Load.
84

CAVEATS

86       Refreshing modules may miss modules which have been externally loaded
87       since the last call to refresh
88           This is because it's not easily possible to tell if a module has
89           been modified since it was loaded, if we haven't seen it so far. A
90           workaround for this may be to set the "track_require" option in the
91           import arguments (see above), although this comes with its own set
92           of caveats (since it is global behavior).
93
94       Global variable accesses and function calls may not work as expected
95           Perl resolves accesses to global variables and functions in other
96           packages at compile time, so if the package is later reloaded,
97           changes to those will not be noticed. As mentioned above, this
98           module is intended for refreshing classes.
99
100       File modification times have a granularity of one second
101           If you modify a file and then immediately call "refresh" and then
102           immediately modify it again, the modification may not be seen on
103           the next call to "refresh". Note however that file size and inode
104           number are also compared, so it still may be seen, depending on if
105           either of those two things changed.
106
107       Tracking modules which "use" a given module isn't possible
108           For instance, modifying a Moose::Exporter module which is used in a
109           class won't cause the class to be refreshed, even if the change to
110           the exporter would cause a change in the class's metaclass.
111
112       Classes which aren't completely defined in a single file and files
113       which define multiple classes cause problems
114           If a class is defined across multiple files, there's no easy
115           guaranteed way to restore the entire state of the class, since
116           there may be load order issues.  This includes Moose classes which
117           have "make_immutable" called on them from outside of the class file
118           itself.
119
120           Also, files which define multiple classes cause problems since we
121           can't always determine which classes are defined in the file, and
122           so reloading the file may cause class definitions to be run more
123           than once.
124
125       Classes which build themselves differently based on the state of other
126       classes may not work properly
127           This module attempts to handle several cases of this sort for Moose
128           classes (modifying a class will refresh all of its subclasses,
129           modifying a role will refresh all classes and roles which consume
130           that role, modifying a metaclass will refresh all classes whose
131           metaclass is an instance of that metaclass), but it's not a problem
132           that's solvable in the general case.
133

BUGS

135       Reloading classes when their metaclass is modified doesn't quite work
136       yet
137           This will require modifications to Moose to support properly.
138
139       Tracking changes to metaclasses other than the class metaclass isn't
140       implemented yet
141       Metacircularity probably has issues
142           Refreshing a class which is its own metaclass will likely break.
143
144       Please report any bugs to GitHub Issues at
145       <https://github.com/doy/class-refresh/issues>.
146

SEE ALSO

148       Module::Refresh
149

SUPPORT

151       You can find this documentation for this module with the perldoc
152       command.
153
154           perldoc Class::Refresh
155
156       You can also look for information at:
157
158       •   MetaCPAN
159
160           <https://metacpan.org/release/Class-Refresh>
161
162       •   Github
163
164           <https://github.com/doy/class-refresh>
165
166       •   RT: CPAN's request tracker
167
168           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Refresh>
169
170       •   CPAN Ratings
171
172           <http://cpanratings.perl.org/d/Class-Refresh>
173

CREDITS

175       This module was based in large part on Module::Refresh by Jesse
176       Vincent.
177

AUTHOR

179       Jesse Luehrs <doy@tozt.net>
180
182       This software is copyright (c) 2014 by Jesse Luehrs.
183
184       This is free software; you can redistribute it and/or modify it under
185       the same terms as the Perl 5 programming language system itself.
186
187
188
189perl v5.34.0                      2022-01-21                 Class::Refresh(3)
Impressum