BRN(1p) User Contributed Perl Documentation BRN(1p)
NAME
brn - bulk rename - a fork of rename.
SYNOPSIS
brn [ -v ] [ -n ] [ -f ]
[ -C configpath ] [ -M perlmodule ]
[ -p perlexpr [ -p perlexpr ... ] ]
{ [ -e ] perlexpr | -u preset }
[ files ... ]
brn [ -C configpath ]
{ -L preset | --list preset ]
brn [ -C configpath ] ...
{ -S preset | --save preset ]
brn -V | --version
brn -? | --help
brn -R | --readme
brn -m | --man
DESCRIPTION
"brn" renames the filenames supplied according to the rule(s)
given by the --expr (-e) option(s). If no such option is present
then the first argument is taken to be the rule. The perlexpr
argument is a Perl expression which is expected to modify the $_
string in Perl for at least some of the filenames specified. If a
given filename is not modified by the expression, it will not be
renamed. If no filenames are given on the command line, filenames
will be read via standard input.
For example, to rename all files matching "*.bak" to strip the
extension, you might say
brn 's/\.bak$//' *.bak
To translate uppercase names to lower, you'd use
brn 'y/A-Z/a-z/' *
brn loads all Modules into a UserCommand package
(App::FileTools::BulkRename::UserCommands), and this is also where
all expresions are evaluated. Note that the UserCommand package
doesn't have 'strict' turned on, so variables do not need to be
pre-declared. There are also a few predefined helper functions in
its scope, to ease common rename tasks.
In void context, all of these helper functions output as if in
scalar context by modifing their first parameter or $_ (if their
parameter is unmodifiable). They will use $_ for their input data
if called without. Thus, one can now uppercase all files in a
directory just by saying
brn 'uc' *
This can also be used in expression interpolation inside larger
strings, so as to achieve more complex results. The command:
brn 's/Show-(.*?).avi/Show - @{[ hc(spc($1)) ]}.avi/' *
Will extract a substring, perform space replacement, convert to
highlight case, and re-insert the substring back into the name.
The full set of helper functions are:
slurp slurp reads in an entire file given a filename or
filehandle. In array context it returns individual
chomped lines, while in scalar context it returns the
entire file.
rd rd reads entire directories and is the equivalent of
slurp. In array context it returns an array containing
all the entries in all the directories passed to it.
In scalar context it returns all the directory names
in a single string, separated by newlines.
spc($;$) by default spc() takes a string and returns it with
all dots ('.') and underscores ('_') converted to
spaces. An optional second argument can provide a
string of characters that overrides the list of
characters to convert to spaces.
sc($) sc() returns its input string converted to 'Sentence'
case, meaning that the letter of each embedded
sentence will be capitalized.
tc($) tc() returns its input string converted to 'Title'
case, meaning that the first letter of each word is
uppercased.
hc($) hc() returns its input string converted to 'Highlight'
case, meaning that the first letter of each non-
trivial word is uppercased.
OPTIONS
-v, --verbose
Verbose: print names of files successfully renamed.
-n, --nop
No Operation (NOP): show what files would have been
renamed.
-f, --force
Force: overwrite existing files.
-e, --expr
Expression: this option holds a rename expression to be
used to rename files. Multiple instances of this flag may
appear on the command line, and they are executed in
order, for each file specified.
If no occurance of this flag appears on the command line,
then the first argument will be taken as a rename
expression and subsequent arguments will be taken as file
names.
If this flag does appear on the command line, then all
arguments are assumed to be file names.
-M module[=foo,bar]
Load the listed modules at the start of the program. If
the optional extra parameters are added, then they will be
used to import the listed functions. Multiple instances
can appear on the command line, and they will be loaded in
the order given.
-p perlexpr, --preamble=perlexpr
Preamble: execute the expression once, before looping over
the files to rename, this can be useful to load data files
or do other setup before complex rename procedures.
Multiple preambles can be given, and they will be executed
in order.
-u | --use preset
Use preset: Rather than specifying a complex operation on
the command line, you can also save a set of command line
options in a config file, and use them by using the 'use'
option. By default the config file is stored in
${HOME}/.config/rn.conf but this can be changed with the
--config (-c) command. Multiple use options can be
specified, and their operations will be executed in turn.
-S | --save preset
Save preset: Rather than executing the contents of the
current command line, the options will be stored in the rn
config file under the given preset name.
-L | --list preset
List preset: Rather than performing a rename operation,
just list the command line options stored under the given
preset name. Multiple --list options can be given, to see
multiple presets.
-C | --config configpath
Normally, all stored presets are assumed to be in the
default location, which is ${HOME}/.config/rn.conf, but
this can be changed on a preset-by-preset basis with the
--config option, which allows you to specify the full
pathname of another config file.
If a preset itself references other presets then they will
be looked up either in the last specified config file,
which will be the one specified in that preset (if any).
-V | --version
Version: display the current version of this program, and
exit with a code of 1.
-?, --help
Help: Display this documentation.
-m, --man
Manual: Display a full man page.
ENVIRONMENT
The 'HOME' environment variable is used to determine the default
location of the rn.conf file.
AUTHOR
Original Author: Larry Wall Second Author: Robin Barker Current
Author: Stirling Westrup
SEE ALSO
mv(1), perl(1), rename(1), prename(1), File::rename(3pm),
App::perlmv(3pm)
DIAGNOSTICS
If you give an invalid Perl expression you'll get a syntax error.
BUGS
There are probably innumerable bugs in this code as it is still in
alpha state. Among the known problems are the possibly incorrect
chaining of -u options, and the failure to always maintain the
order of mixed -e and -u options.
In addition there are many stubs for features that do not yet work
fully (if at all) and the documentation is slightly behind the
work.
HISTORY
The original "rename" did not check for the existence of target
filenames, so had to be used with care. I hope I've fixed that
(Robin Barker).
The original "rename" seemed to me to be lacking a number of
useful features, and as its last update had been back in 1998, I
(Stirling Westrup) decided to fork a version to work on.
perl v5.10.1 2010-10-30 BRN(1p)
