BRN(1) User Contributed Perl Documentation BRN(1)
NNAAMMEE
brn - bulk rename - a fork of rename.
SSYYNNOOPPSSIISS
bbrrnn [ { --vv | --qq } ... ] ] [ --nn ] [ --ff ] [ --DD ] [ --CC _c_o_n_f_i_g_p_a_t_h ]
[ --MM _p_e_r_l_m_o_d_u_l_e ] [ --pp _p_e_r_l_e_x_p_r [ --pp _p_e_r_l_e_x_p_r ... ] ]
{ [ --ee ] _p_e_r_l_e_x_p_r | --uu _p_r_e_s_e_t } [ _f_i_l_e_s ... ]
bbrrnn [ --CC _c_o_n_f_i_g_p_a_t_h ] { --LL | ----lliisstt } [ _p_r_e_s_e_t ] ...
bbrrnn [ --CC _c_o_n_f_i_g_p_a_t_h ] ... { --SS | ----ssaavvee } _p_r_e_s_e_t
bbrrnn --VV | ----vveerrssiioonn
bbrrnn --?? | ----hheellpp
bbrrnn --RR | ----rreeaaddmmee
bbrrnn --mm | ----mmaann
DDEESSCCRRIIPPTTIIOONN
"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 _p_e_r_l_e_x_p_r 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 _USER package, and this is also where all
expresions are evaluated. Note that the _USER 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:
sslluurrpp 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.
rrdd 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.
ssppcc(($$;;$$)) by default _s_p_c_(_) 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.
sscc(($$)) _s_c_(_) returns its input string converted to 'Sentence' case,
meaning that the letter of each embedded sentence will be
capitalized.
ttcc(($$)) _t_c_(_) returns its input string converted to 'Title' case,
meaning that the first letter of each word is uppercased.
hhcc(($$)) _h_c_(_) returns its input string converted to 'Highlight'
case, meaning that the first letter of each non-trivial
word is uppercased.
OOPPTTIIOONNSS
--vv, ----vveerrbboossee
Verbose: increases the verbosity of brn. This option can appear
multiple times, and each appearance increases brn's verbosity
level by one. The option ----qquuiieett can be used to decrease
verbosity. The following table lists the information presented
at different verbosity levels. The default verbosity is 1.
-1 VVeerryy QQuuiieett No Text Output at All
0 QQuuiieett Only Display Errors
1 NNoorrmmaall Display Errors and Warnings
2 VVeerrbboossee List the Files being Processed.
Note that currently not all text is surpressed at level -1.
--qq, ----qquuiieett
Quiet: decreases the verbosity level of brn by 1. See ----vveerrbboossee
for a discussion of verbosity levels.
--nn, ----nnoopp
No Operation (NOP): show what files would have been renamed.
--ff, ----ffoorrccee
Force: overwrite existing files.
--DD, ----ddeebbuugg
Debug: Turn on internal debugging shims. Intended for
developers only.
--ee, ----eexxpprr
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.
--MM _m_o_d_u_l_e_[_=_f_o_o_,_b_a_r_]
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.
--pp _p_e_r_l_e_x_p_r, ----pprreeaammbbllee=_p_e_r_l_e_x_p_r
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.
--uu | ----uussee _p_r_e_s_e_t
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 _$_{_H_O_M_E_}_/_._c_o_n_f_i_g_/_r_n_._c_o_n_f
but this can be changed with the ----ccoonnffiigg (--cc) command.
Multiple use options can be specified, and their operations
will be executed in turn.
--SS | ----ssaavvee _p_r_e_s_e_t
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.
--LL | ----lliisstt _p_r_e_s_e_t
List preset: Rather than performing a rename operation, just
list the command line options stored under the given preset
name. Multiple ----lliisstt options can be given, to see multiple
presets.
--CC | ----ccoonnffiigg _c_o_n_f_i_g_p_a_t_h
Normally, all stored presets are assumed to be in the default
location, which is _$_{_H_O_M_E_}_/_._c_o_n_f_i_g_/_r_n_._c_o_n_f, but this can be
changed on a preset-by-preset basis with the ----ccoonnffiigg 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).
--VV | ----vveerrssiioonn
Version: display the current version of this program.
--??, ----hheellpp
Help: Display this documentation.
--mm, ----mmaann
Manual: Display a full man page.
EEXXIITT CCOODDEESS
brn returns an exit code indicating the success or failure of the
requested operation. 0 always indicates a success. A return code less
than 16 indicates success in an auxiliary function of brn (such as
successfully return its version.) Starting at 16, the error codes
indicate various fatal errors.
0 NNoonnee No Error
1 HHeellpp Help was requested
2 DDooccss Readme or manual was requested
3 IInnffoo Other information was requested
16 GGeenneerraall Unknown Error
17 NNooSSuucchhFFiillee File Not Found
18 BBaaddCCoonnffiiggFFiillee Configuration File Error
19 BBaaddPPrreesseett No Such Preset
20 NNoottIImmpplleemmeenntteedd This Feature is Currently Not Implemented
EENNVVIIRROONNMMEENNTT
The 'HOME' environment variable is used to determine the default
location of the rn.conf file.
AAUUTTHHOORR
Original Author: Larry Wall
Second Author: Robin Barker
Current Author: Stirling Westrup
SSEEEE AALLSSOO
_m_v(1), _p_e_r_l(1), _r_e_n_a_m_e(1), _p_r_e_n_a_m_e(1), _F_i_l_e_:_:_r_e_n_a_m_e(3pm),
_A_p_p_:_:_p_e_r_l_m_v(3pm)
DDIIAAGGNNOOSSTTIICCSS
If you give an invalid Perl expression you'll get a syntax error.
BBUUGGSS
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.
HHIISSTTOORRYY
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.14.2 2012-07-17 BRN(1)