Refactor(3pm)

💖 Refactor(3pm) — Devel::Refactor 💖

okay bestie, welcome to Refactor(3pm), a User Contributed Perl Documentation page, and honestly? it's giving ✨developer convenience✨. it's Devel::Refactor, and it's here to make your Perl code prettier. let's get into it 🫶

---

✨ NAME ✨

Devel::Refactor — Perl extension for refactoring Perl code. yes queen, that's literally the whole name. slay.

💫 VERSION 💫

$Revision: $ — this is the CVS revision number. iconic, lowkey old school, but we respect the classics 💅

🌸 SYNOPSIS 🌸

here's the vibe in code form, copy it exactly bestie:

use Devel::Refactor;

my $refactory = Devel::Refactor->new;

my ($new_sub_call,$new_sub_code) =
   $refactory->extract_subroutine($sub_name, $code_snippet);

my $files_to_change = $refactory->rename_subroutine('./path/to/dir',
                                                    'oldSubName','newSubName');
# $files_to_change is a hashref where keys are file names, and values are
# arrays of hashes with line_number => new_text

🦋 ABSTRACT 🦋

a Perl module that facilitates refactoring Perl code. no cap, that's it, that's the abstract 💜

🎀 DESCRIPTION 🎀

the Devel::Refactor module is for code refactoring. periodt.

and listen — even though you can use Devel::Refactor straight from Perl programs, it was also designed to be used with the EPIC plug-in for the eclipse integrated development environment. so it's versatile like that ✨

👑 CLASS METHODS 👑

just the constructor for now, we're keeping it cute and minimal.

💅 new

returns a new Devel::Refactor object. that's the whole thing. go off 🎀

🔥 PUBLIC OBJECT METHODS 🔥

call these on an object you got back from new(). bestie, this is where the magic happens.

🌈 extract_subroutine($new_name,$old_code [,$syntax_check])

okay so you pass it a snippet of Perl code that belongs in its own subroutine, plus a name for that sub. it figures out which variables need to be passed into the sub, and which variables might be passed back. then it produces the sub along with a call to the sub. it's giving psychic honestly 🔮

hashes and arrays within the code snippet get converted to hashrefs and arrayrefs. glow up ✨

if the syntax_check argument is true, then a sytax check is performed on the refactored code. (yes, we do check your work. self care 💅)

example:

$new_name = 'newSub';
$old_code = <<'eos';
  my @results;
  my %hash;
  my $date = localtime;
  $hash{foo} = 'value 1';
  $hash{bar} = 'value 2';
  for my $loopvar (@array) {
     print "Checking $loopvar\n";
     push @results, $hash{$loopvar} || '';
  }
eos

($new_sub_call,$new_code) = $refactory->extract_subroutine($new_name,$old_code);
# $new_sub_call is 'my ($date, $hash, $results) = newSub (\@array);'
# $new_code is
# sub newSub {
#     my $array = shift;
#
#   my @results;
#   my %hash;
#   my $date = localtime;
#   $hash{foo} = 'value 1';
#   $hash{bar} = 'value 2';
#   for my $loopvar (@$array) {
#      print "Checking $loopvar\n";
#      push @results, $hash{$loopvar} || '';
#   }
#
#
#     return ($date, \%hash, \@results);
# }

also!! included in the examples directory is a script for use in KDE under Linux. the script gets its code snippet from the KDE clipboard and returns the transformed code the same way. the new sub name is prompted for via STDIN. clipboard to clipboard, main character energy 👑

🧚 rename_subroutine($where,$old_name,$new_name,[$max_depth])

where is one of:

path-to-file
path-to-directory

if where is a directory then all Perl files (default is ".pl", ".pm", and ".pod" — see the perl_file_extensions method.) in that directory and its' descendents (to max_depth deep,) are searched. we're going deep, bestie 🕵️‍♀️

default for max_depth is 0 — just the directory itself. max_depth of 1 means the specified directory, and it's immeadiate sub-directories; max_depth of 2 means the specified directory, it's sub-directories, and their sub-directrories, and so forth. if you want to scan very deep, use a high number like 99. go feral 🌊

if no matches are found then it returns undef, otherwise:

it returns a hashref that tells you which files you might want to change, and for each file gives you the line numbers and proposed new text for that line. the hashref looks like this, where old_name was found on two lines in the first file and on one line in the second file:

 {
   ./path/to/file1.pl => [
                           { 11  => "if (myClass->newName($x)) {\n" },
                           { 27  => "my $result = myClass->newName($foo);\n"},
                         ],
   ./path/to/file2.pm => [
                           { 235 => "sub newName {\n"},
                         ],
 }

the keys are paths to individual files. the values are arraryrefs containing hashrefs where the keys are the line numbers where old_name was found and the values are the proposed new line, with old_name changed to new_name. obsessed 💖

🍓 is_perlfile($filename)

takes a filename or path and returns true if the file has one of the extensions in perl_file_extensions, otherwise returns false. simple. clean. vibe check passed ✅

🌟 OBJECT ACCESSORS 🌟

these object methods return various data structures that may be stored in a Devel::Refactor object. in some cases the method also allows setting the property, e.g. perl_file_extensions. versatile queens only 👸

💜 get_new_code

returns the return_snippet object property.

💜 get_eval_results

returns the eval_err object property.

💜 get_sub_call

returns the return_sub_call object property.

💜 get_scalars

returns an array of the keys from scalar_vars object property.

💜 get_arrays

returns an array of the keys from the array_vars object property.

💜 get_hashes

returns an array of the keys from the hash_vars object property.

💜 get_local_scalars

returns an array of the keys from the local_scalars object property.

💜 get_local_arrays

returns an array of the keys from the local_arrays object property.

💜 get_local_hashes

returns an array of the keys from the local_hashes object property.

🎀 perl_file_extensions([$arrayref|$hashref])

returns a hashref where the keys are regular expressions that match filename extensions that we think are for Perl files. default are ".pl", ".pm", and ".pod" ✨

if passed a hashref then it replaces the current values for this object. the keys should be regular expressions, e.g. "\.cgi$".

if passed an arrayref then the list of values are added as valid Perl filename extensions. the list should be filename extensions, NOT regular expressions. for example:

my @additonal_filetypes = qw( .ipl .cgi );
my $new_hash = $refactory->perl_file_extensions(\@additional_filetypes);
# $new_hash = {
#   '\.pl$'   => 1,
#   '\.pm$'   => 1,
#   '\.pod$'  => 1,
#   '\.ipl$'  => 1,
#   '\.cgi$'  => 1,
#   '\.t$'    => 1,
# }

---

📝 TODO LIST 📝

manifesting these, bestie:

• come up with a more uniform approach to ACCESSORS.
• add more refactoring features, such as add_parameter.
• add a SEE ALSO section with URLs for eclipse/EPIC, refactoring.com, etc.

💖 AUTHOR 💖

Scott Sotka, <ssotka@barracudanetworks.com>

⭐ COPYRIGHT AND LICENSE ⭐

Copyright 2005 by Scott Sotka

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! 🫶 this was Refactor(3pm) from perl v5.36.0, dated 2022-11-21, and honestly? she ate. go refactor something gorgeous 💅✨🌈