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

DESCRIPTION

   USE OPTIONS
       Parameters to "use File::Rename" consists of functions to be imported and configuration
       options.

       The only exported function is "rename()".  The configuation options are preceded by
       :config, and are passed to File::Rename::Options.

   FUNCTIONS
       "rename( FILES, CODE [, VERBOSE])"
           rename FILES using CODE, if FILES is empty read list of files from stdin

       "rename_files( CODE, VERBOSE, FILES)"
           rename FILES using CODE

       "rename_list( CODE, VERBOSE, HANDLE [, FILENAME])"
           rename a list of file read from HANDLE, using CODE

   OPTIONS
       FILES   List of files to be renamed, for "rename" must be an ARRAY reference

       CODE    Subroutine to change file names, for "rename" can be a string, otherwise it is a
               code reference

       VERBOSE Flag for printing names of files successfully renamed, optional for "rename"

       HANDLE  Filehandle to read file names to be renames

       FILENAME (Optional)
               Name of file that HANDLE reads from

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

       If CODE is a HASH, VERBOSE is ignored and CODE is supplied by the _code key.

       Other options are

       verbose         As VERBOSE above, provided by -v.

       input_null      Input separator \0 when reading file names from stdin.

       no_action       Print names of files to be renamed, but do not rename (i.e. take no
                       action), provided by -n.

       over_write      Allow files to be over-written by the renaming, provided by -f.

       filename_only   Only apply renaming to the filename component of the path, provided by -d.

       show_help       Print help, provided by -h.

       show_manual     Print manual page, provided by -m.

       show_version    Print version number, provided by -V.

       unicode_strings Enable unicode_strings feature, provided by -u.

       encoding        Encoding for filenames, provided by -u.

   EXPORT
       rename

ENVIRONMENT

       No environment variables are used.

SEE ALSO

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

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.

DIAGNOSTICS

       Errors from the code argument are not trapped.

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.