File::Rename(3pm)

✨ File::Rename ✨

okay bestie, gather round, because this is File::Rename(3pm) — a Perl extension for renaming multiple files, and it is lowkey iconic 💅 like, you have a whole pile of files and you want them all renamed by a rule instead of by hand like some kind of Victorian orphan. That's what this does. No cap.

---

🌸 SYNOPSIS 🌸

use File::Rename qw(rename);          # hide CORE::rename
rename \@ARGV, sub { s/\.pl\z/.pm/ }, 1;

use File::Rename;
File::Rename::rename \@ARGV, '$_ = lc';

use File::Rename qw(:config no_require_order);

the first one imports rename and shadows the CORE one, because otherwise Perl's builtin rename is gonna be sitting there like "hi I'm the main character" and no. The second one doesn't import anything, it just calls the fully qualified File::Rename::rename. The third one pulls in config options with the :config tag and turns off require_order. Slay.

---

🦋 DESCRIPTION 🦋

💖 USE OPTIONS 💖

When you use File::Rename, the stuff you pass in is split into two vibes: functions to be imported and configuration options.

The only function that gets exported is rename(). The configuration options have to be introduced by :config, and then they get handed straight off to File::Rename::Options. That's the whole tea. 🍓

🧚 FUNCTIONS 🧚

• rename( FILES, CODE [, VERBOSE]) — renames FILES using CODE. and if FILES is empty?? it reads the list of files from stdin instead. very demure, very mindful. 🙈
• rename_files( CODE, VERBOSE, FILES) — renames FILES using CODE. (yes the argument order is different, no I will not be explaining why, it just is, periodt.)
• rename_list( CODE, VERBOSE, HANDLE [, FILENAME]) — renames a list of files read from HANDLE, using CODE.

👑 OPTIONS 👑

• FILES — the list of files you wanna rename. for rename this must be an ARRAY reference, so like, \@ARGV not @ARGV. don't come for me.
• CODE — the subroutine that actually changes the file names. for rename it's allowed to be a plain string, but everywhere else it's a code reference.
• VERBOSE — a flag that prints the names of files that got successfully renamed. it's optional for rename because she's flexible like that 💅
• HANDLE — the filehandle you read the file names from.
• FILENAME (optional) — the name of the file that HANDLE is reading from.

🌈 HASH 🌈

Either CODE or VERBOSE can be a HASH of options. plot twist.

If CODE is a HASH, then VERBOSE gets ignored (rip) and the code comes from the _code key instead.

The other options are:

• verbose — same energy as VERBOSE up above. provided by -v.
• input_null — sets the input separator to \0 when reading file names from stdin.
• no_action — prints the names of files that would be renamed but doesn't rename them, i.e. takes no action at all. provided by -n.
• over_write — lets files get over-written by the renaming. provided by -f.
• filename_only — only applies the renaming to the filename component of the path, not the whole path. provided by -d.
• show_help — prints the help. provided by -h.
• show_manual — prints the manual page. provided by -m.
• show_version — prints the version number. provided by -V.
• unicode_strings — enables the unicode_strings feature. provided by -u.
• encoding — sets the encoding for filenames. provided by -u.

⭐ EXPORT ⭐

rename

that's it. that's the list. one (1) whole function. minimalism is the vibe. 🫶

---

💜 ENVIRONMENT 💜

No environment variables are used. none. zero. the environment is untouched and unbothered. ✨

---

🌟 SEE ALSO 🌟

mv(1), perl(1), rename(1)

go read those too, bestie, they're the supporting cast 💖

---

🎀 AUTHOR 🎀

Robin Barker <RMBarker@cpan.org>

🍓 Acknowledgements 🍓

Based on code from Larry Wall. (yes, that Larry Wall. legend behaviour 👑)

Options -e, -f, -n were suggested by more recent code written by Aristotle Pagaltzis.

---

💀 DIAGNOSTICS 💀

Errors from the code argument are not trapped. so like, if your CODE dies, it dies, and nobody is catching it for you. it's giving "you're on your own babe". 😭

---

🌸 COPYRIGHT AND LICENSE 🌸

Copyright (C) 2004, 2005, 2006, 2011, 2018, 2021, 2022, 2023 by Robin Barker

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

---

and that's the whole page, bestie 🎀 this one's from perl v5.36.0, dated 2024-01-01, and it lives at File::Rename(3pm) — go rename something, you absolute icon 💅✨