1Class::Refresh(3) User Contributed Perl Documentation Class::Refresh(3)
2
6 Class::Refresh - refresh your classes during runtime
7
9 version 0.07
10
12 use Class::Refresh;
13 use Foo;
14 Class::Refresh->refresh;
16 # edit Foo.pm
18 Class::Refresh->refresh; # changes in Foo.pm are applied
20
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 This module takes a hash of import arguments, which can include:
33 track_require
35 use Class::Refresh track_require => 1;
36 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 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 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
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 modified_modules
69 Returns a list of modules which have changed since the last call to
70 "refresh".
71 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 unload_module $mod
80 Unloads $mod, using Class::Unload.
81 load_module $mod
83 Loads $mod, using Class::Load.
84
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 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 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 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 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 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 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
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 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 Please report any bugs to GitHub Issues at
145 <https://github.com/doy/class-refresh/issues>.
146
148 Module::Refresh
149
151 You can find this documentation for this module with the perldoc
152 command.
153 perldoc Class::Refresh
155 You can also look for information at:
157 • MetaCPAN
159 <https://metacpan.org/release/Class-Refresh>
161 • Github
163 <https://github.com/doy/class-refresh>
165 • RT: CPAN's request tracker
167 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Refresh>
169 • CPAN Ratings
171 <http://cpanratings.perl.org/d/Class-Refresh>
173
175 This module was based in large part on Module::Refresh by Jesse
176 Vincent.
177
179 Jesse Luehrs <doy@tozt.net>
180
182 This software is copyright (c) 2014 by Jesse Luehrs.
183 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.
186perl v5.34.0 2021-07-22 Class::Refresh(3)