BRN(1) User Contributed Perl Documentation BRN(1) NNAAMMEE brn - bulk rename - a fork of rename. SSYYNNOOPPSSIISS bbrrnn [ --vv ] [ --nn ] [ --ff ] [ --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 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: 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: print names of files successfully renamed. --nn, ----nnoopp No Operation (NOP): show what files would have been renamed. --ff, ----ffoorrccee Force: overwrite existing files. --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 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.10.1 2010-11-26 BRN(1)