Author image Johan Vromans
and 1 contributors

NAME

File::PerlMove - Rename files using Perl expressions

SYNOPSIS

  use File::PerlMove qw(pmv);
  pmv( sub { lc($_[0]) }, \@filelist, { verbose => 1 });

DESCRIPTION

File::PerlMove provides a single subroutine: File::PerlMove::pmv.

pmv takes three arguments: transform, filelist, and options.

transform must be a string or a code reference. If it is a string, it is assumed to be a valid Perl expression that will be evaluated to modify $_.

When transform is invoked it should transform a file name passes as argument into a new file name.

filelist must be an array reference containing the list of file names to be processed.

options is a hash reference containing options to the operation.

Options are enabled when set to a non-zero (or otherwise 'true') value. Possible options are:

showonly

Show the changes, but do not rename the files.

Link instead of rename.

Symlink instead of rename. Note that not all platforms support symlinking,

reverse

Process the files in reversed order.

overwrite

Overwrite existing files.

createdirs

Create target directories if necessary.

legacy

If transform is a code reference, it is called with the old name as argument and must return the new, transformed name.

If legacy is true, the code reference adheres to the old API where the routine modifies the filename stored in $_.

verbose

More verbose information.

EXPORTS

The main subroutine pmv() can be exported on demand.

EXTENSIONS

If the transform argument is a verb, File::PerlMove will try to load (require) a package File::PerlMove::verb. This package must define a subroutine File::PerlMove::verb::verb. This subroutine is then used to perform the transformation.

If such a package cannot be loaded it may be the name of a builtin routine. See "BUILTINS".

If the transform argument is in the form pkg=verb then File::PerlMove::pkg is used instead of File::PerlMove::verb. This makes it possible to have extension modules that define multiple transform routines.

If the package name contains :: it is taken to be the full package name. For example,

    t::foo=bar

will load package t::foo and call subroutine t::foo::bar.

BUILTINS

If the transform argument is a verb and not an extension (see "EXTENSIONS"), it may be the name of a builtin routine.

Currently supported builtins:

lc

Performs a lowercase operation.

uc

Performs an uppercase operation.

ucfirst

Upcases the first letter.

tc

Performs a titlecase operation.

Note, however, that using any of these operations is useless on file systems that are case insensitive, like MS Windows and Mac.

EXAMPLES

See pmv for examples.

AUTHOR

Johan Vromans <jvromans@squirrel.nl>

SEE ALSO

App::perlmv (and perlmv), File::Rename (and rename).

COPYRIGHT

This programs is Copyright 2004,2010,2017,2020 Squirrel Consultancy.

This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.