1Refactor(3)           User Contributed Perl Documentation          Refactor(3)
2
3
4

NAME

6       Devel::Refactor - Perl extension for refactoring Perl code.
7

VERSION

9       $Revision: $  This is the CVS revision number.
10

SYNOPSIS

12         use Devel::Refactor;
13
14         my $refactory = Devel::Refactor->new;
15
16         my ($new_sub_call,$new_sub_code) =
17            $refactory->extract_subroutine($sub_name, $code_snippet);
18
19         my $files_to_change = $refactory->rename_subroutine('./path/to/dir',
20                                                             'oldSubName','newSubName');
21         # $files_to_change is a hashref where keys are file names, and values are
22         # arrays of hashes with line_number => new_text
23

ABSTRACT

25       Perl module that facilitates refactoring Perl code.
26

DESCRIPTION

28       The Devel::Refactor module is for code refactoring.
29
30       While Devel::Refactor may be used from Perl programs, it is also
31       designed to be used with the EPIC plug-in for the eclipse integrated
32       development environment.
33

CLASS METHODS

35       Just the constructor for now.
36
37   new
38       Returns a new Devel::Refactor object.
39

PUBLIC OBJECT METHODS

41       Call on a object returned by new().
42
43   extract_subroutine($new_name,$old_code [,$syntax_check])
44       Pass it a snippet of Perl code that belongs in its own subroutine as
45       well as a name for that sub.  It figures out which variables need to be
46       passed into the sub, and which variables might be passed back.  It then
47       produces the sub along with a call to the sub.
48
49       Hashes and arrays within the code snippet are converted to hashrefs and
50       arrayrefs.
51
52       If the syntax_check argument is true then a sytax check is performed on
53       the refactored code.
54
55       Example:
56
57           $new_name = 'newSub';
58           $old_code = <<'eos';
59             my @results;
60             my %hash;
61             my $date = localtime;
62             $hash{foo} = 'value 1';
63             $hash{bar} = 'value 2';
64             for my $loopvar (@array) {
65                print "Checking $loopvar\n";
66                push @results, $hash{$loopvar} || '';
67             }
68           eos
69
70           ($new_sub_call,$new_code) = $refactory->extract_subroutine($new_name,$old_code);
71           # $new_sub_call is 'my ($date, $hash, $results) = newSub (\@array);'
72           # $new_code is
73           # sub newSub {
74           #     my $array = shift;
75           #
76           #   my @results;
77           #   my %hash;
78           #   my $date = localtime;
79           #   $hash{foo} = 'value 1';
80           #   $hash{bar} = 'value 2';
81           #   for my $loopvar (@$array) {
82           #      print "Checking $loopvar\n";
83           #      push @results, $hash{$loopvar} || '';
84           #   }
85           #
86           #
87           #     return ($date, \%hash, \@results);
88           # }
89
90       Included in the examples directory is a script for use in KDE under
91       Linux.  The script gets its code snippet from the KDE clipboard and
92       returns the transformed code the same way.  The new sub name is
93       prompted for via STDIN.
94
95   rename_subroutine($where,$old_name,$new_name,[$max_depth])
96       where is one of:
97         path-to-file
98         path-to-directory
99
100       If where is a directory then all Perl files (default is ".pl", ".pm",
101       and ".pod" See the perl_file_extensions method.) in that directory and
102       its' descendents (to max_depth deep,) are searched.
103
104       Default for max_depth is 0 -- just the directory itself; max_depth of 1
105       means the specified directory, and it's immeadiate sub-directories;
106       max_depth of 2 means the specified directory, it's sub-directories, and
107       their sub-directrories, and so forth.  If you want to scan very deep,
108       use a high number like 99.
109
110       If no matches are found then returns undef, otherwise:
111
112       Returns a hashref that tells you which files you might want to change,
113       and for each file gives you the line numbers and proposed new text for
114       that line.  The hashref looks like this,  where old_name was found on
115       two lines in the first file and on one line in the second file:
116
117        {
118          ./path/to/file1.pl => [
119                                  { 11  => "if (myClass->newName($x)) {\n" },
120                                  { 27  => "my $result = myClass->newName($foo);\n"},
121                                ],
122          ./path/to/file2.pm => [
123                                  { 235 => "sub newName {\n"},
124                                ],
125        }
126
127       The keys are paths to individual files. The values are arraryrefs
128       containing hashrefs where the keys are the line numbers where old_name
129       was found and the values are the proposed new line, with old_name
130       changed to new_name.
131
132   is_perlfile($filename)
133       Takes a filename or path and returns true if the file has one of the
134       extensions in perl_file_extensions, otherwise returns false.
135

OBJECT ACCESSORS

137       These object methods return various data structures that may be stored
138       in a Devel::Refactor object. In some cases the method also allows
139       setting the property, e.g. perl_file_extensions.
140
141   get_new_code
142       Returns the return_snippet object property.
143
144   get_eval_results
145       Returns the eval_err object property.
146
147   get_sub_call
148       Returns the return_sub_call object property.
149
150   get_scalars
151       Returns an array of the keys from scalar_vars object property.
152
153   get_arrays
154       Returns an array of the keys from the array_vars object property.
155
156   get_hashes
157       Returns an array of the keys from the hash_vars object property.
158
159   get_local_scalars
160       Returns an array of the keys from the local_scalars object property.
161
162   get_local_arrays
163       Returns an array of the keys from the local_arrays object property.
164
165   get_local_hashes
166       Returns an array of the keys from the local_hashes object property.
167
168   perl_file_extensions([$arrayref|$hashref])
169       Returns a hashref where the keys are regular expressions that match
170       filename extensions that we think are for Perl files. Default are
171       ".pl", ".pm", and ".pod"
172
173       If passed a hashref then it replaces the current values for this
174       object. The keys should be regular expressions, e.g. "\.cgi$".
175
176       If passed an arrayref then the list of values are added as valid Perl
177       filename extensions. The list should be filename extensions, NOT
178       regular expressions, For example:
179
180         my @additonal_filetypes = qw( .ipl .cgi );
181         my $new_hash = $refactory->perl_file_extensions(\@additional_filetypes);
182         # $new_hash = {
183         #   '\.pl$'   => 1,
184         #   '\.pm$'   => 1,
185         #   '\.pod$'  => 1,
186         #   '\.ipl$'  => 1,
187         #   '\.cgi$'  => 1,
188         #   '\.t$'    => 1,
189         # }
190

TODO LIST

192       Come up with a more uniform approach to ACCESSORS.
193       Add more refactoring features, such as add_parameter.
194       Add a SEE ALSO section with URLs for eclipse/EPIC, refactoring.com,
195       etc.
196

AUTHOR

198       Scott Sotka, <ssotka@barracudanetworks.com>
199
201       Copyright 2005 by Scott Sotka
202
203       This library is free software; you can redistribute it and/or modify it
204       under the same terms as Perl itself.
205
206
207
208perl v5.34.0                      2022-01-21                       Refactor(3)
Impressum