File::Rename(3pm)

📦
version 2.01 · 2 versions
, in debian bookworm

💖 File::Rename 💖

okay bestie, welcome to File::Rename — a User Contributed Perl Documentation situation, and it's literally the Perl extension for renaming multiple files at once. no cap. you're gonna love her. 🦋

✨ NAME ✨

File::Rename — Perl extension for renaming multiple files 👑

🌸 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);

look at her go. she's giving versatile. 💅

🎀 DESCRIPTION 🎀

🧚 USE OPTIONS

so when you do use File::Rename, the parameters you pass are made of two things: the functions you wanna import, and the configuration options. that's it, that's the whole vibe.

the only exported function is rename(). iconic. singular. main character.

the configuration options come with a :config prefix in front of them, and they get handed off to File::Rename::Options. yes, she's delegating, and she's right to. 🫶

💜 FUNCTIONS

  • rename( FILES, CODE [, VERBOSE]) — renames FILES using CODE. and listen: if FILES is empty, she'll read the list of files from stdin. sneaky but slay. ✨
  • rename_files( CODE, VERBOSE, FILES) — renames FILES using CODE. that's the whole thing, bestie.
  • rename_list( CODE, VERBOSE, HANDLE [, FILENAME]) — renames a list of files read from HANDLE, using CODE. 💫

🌈 OPTIONS

  • FILES — the list of files to be renamed. for rename this must be an ARRAY reference. not optional, not vibes-based, an actual arrayref. 💀
  • CODE — the subroutine that changes the file names. for rename it can be a string; otherwise it's a code reference.
  • VERBOSE — flag for printing the names of files that got successfully renamed. optional for rename. 🎀
  • HANDLE — the filehandle to read the file names that are gonna be renamed.
  • FILENAME (Optional) — the name of the file that HANDLE reads from.

🍓 HASH

plot twist: either CODE or VERBOSE can be a HASH of options. yes really.

if CODE is a HASH, then VERBOSE gets ignored entirely and CODE is supplied by the _code key. okay so she said "one of you is doing double duty and it's you, CODE." 💅

the other options are:

  • verbose — same as VERBOSE up above. provided by -v.
  • input_null — input separator \0 when reading file names from stdin.
  • no_action — prints the names of the files that would be renamed, but does not rename them (i.e. takes no action). provided by -n.
  • over_write — lets files be over-written by the renaming. provided by -f.
  • filename_only — only applies the renaming to the filename component of the path. provided by -d.
  • show_help — prints 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 — encoding for filenames. provided by -u.

⭐ EXPORT

rename

just the one. she's exclusive. 💖

🌟 ENVIRONMENT 🌟

No environment variables are used.

literally zero. she doesn't need them, she doesn't want them, she's self-sufficient. 🧚

🔥 SEE ALSO 🔥

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

the squad. 🫶

👑 AUTHOR 👑

Robin Barker <RMBarker@cpan.org>

💫 Acknowledgements

Based on code from Larry Wall. 💜

Options -e, -f, -n suggested by more recent code written by Aristotle Pagaltzis. shoutout, fr fr. ✨

💀 DIAGNOSTICS 💀

Errors from the code argument are not trapped.

bestie. read that again. if your code argument throws, nothing catches it. no safety net, no hands, no cap. it is what it is and it will simply happen to you. 😭

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 doc came to you from perl v5.36.0, dated 2023-01-23, and it lives at File::Rename(3pm). mwah. go rename some files. 💅✨🦋

📦 where this page comes from