1999-10-31
Emil Brink
About gentoo's RenameRE command
1. INTRODUCTION
This document contains a few notes, hints and tips on how
to use the RenameRE command in gentoo. This command was
introduced in the 0.11.10 release, which became available
early November, 1999.
2. PURPOSE OF RenameRE
The purpose of the RenameRE command is to support flexible
renaming. For example, you can use RenameRE to change the
extension on a bunch of files with a single command, or
replace some other portion in a set of filenames. It's not
a command that sees usage every day, but when you need it
you tend to need it badly. :)
Hopefully, the RenameRE command will "save" you
from having to throw together a script or a fancy shell
command line. If you really enjoy writing those scripts,
feel free not to use the command.
3. OPERATING MODES
For maximum ease of use, RenameRE provides not only a
regular expression-based replacement algorithm, but also
a simpler replacement algorithm.
Before executing the RenameRE command, select
one or more files. It often makes more sense to use the
command when you have more than one file selected, but
of course it will work on a single file as well. If you
have no files selected when envoking the command, nothing
happens (just as with most other file operation commands
in gentoo).
When there is a selection, the command pops up a
simple dialog letting you chose one of the two operating
modes, and then start the renaming operation by clicking
the dialog's "OK" button. If you change your mind, just
hit "Cancel" or the Escape key.
You select operating mode by clicking the tabs
in the top of the dialog; this also changes the dialog's
contents to show that mode's controlling widgets.
When you hit "OK", RenameRE will operate in the
mode whose controls are visible.
3.1 Replacement
The first mode is called "simple". It operates like the
text replacement found in most editors, or like everybody's
favorite Perl operator, s//.
The simple replacement mode takes the following
parameters:
"Replace" The string you to search for.
"With" The string you to replace any found
occurances of the "Replace" string
with.
"Ignore Case?" If checked, the search will ignore
any differences in case between the
"Replace" string and the filenames.
Perl people, think of this as the
/i option character.
"Replace All?" This causes the command to continue
searching through the input filename
even after having found and performed
a replacement.
In Perl, this looks like a trailing
/g option.
For example, if you had a filename of "abcabcabc" and
specified the parameters as replace="abc", with="ABC",
and leave the two options at their default values of
false, the file would be renamed to "ABCabcabc". Check
the "Replace All?" button, and the result is "ABCABCABC".
The primary use for the Simple replacement mode
is perhaps to change filename extensions. Doing this
requires some care, however, since you cannot be sure
that the string you find is indeed the extension, i.e.
that it is last in the filename. For such control, you
need to use the Regular Expression mode.
3.2 Regular Expressions
The second mode is a lot more complicated, but also a
lot more powerful and flexible.
The basic idea is to match a regular expression
against each of the filenames. The expression can con-
tain subexpressions (enclosed in round parens). If the
expression matches against an incoming filename, a second
string is used to generate the new filename. In this
second string, you can use $N to refer to the text in
the incoming filename that matched the N:th subexpression
in the regular expression. N should be a digit in the
range 1..9. Any other text in the second string will be
copied verbatim. To get a single dollar sign in the
new filename, use $$. Any other character following a
dollar sign will cause a parse error, and the rename
will be aborted.
The parameters you can provide in the dialog
are as follows:
"From" This is where you enter the regular
expression. You can use parenthesis
to indicate subexpression, and use
the matching text in the new filename.
"To" Here, you specify a string that forms
the new filename. You can use $N to
refer to the text that matched the N:th
subexpression in the From string.
"Ignore Case?" If checked, the regular expression
matcher will disregard differences in
case.
Let's use a huge example to make the operation of the
regular expression RenameRE a bit clearer. Let's assume
you have a set of HTML documents whose names have the
general form "gentoo-TOPIC(CATEGORY).htm", like this:
"gentoo-commands(internals).htm",
"gentoo-selecting(usage).htm",
"gentoo-quitting(usage).htm",
"gentoo-config(usage).htm",
"gentoo-gui(internals).htm",
"gentoo-re(misc).htm".
We want to rename these so that the category (the word
in parenthesis) is moved to the front, the word gentoo
is removed, the actual content label is last before the
dot, and that the extension is "html". To do this, we
specify the following expression in the "From" box:
"^gentoo-([^(]+)\(([^)]+)\)\.htm$"
1 2 3 4 5 6 7 8
This expression can be broken down:
1. The caret (^) anchors the expression to the beginning
of the incoming string, thus making sure that we begin
at the very start. Without this, there could be any
prefix before the "gentoo", and we would produce an
incorrect result.
2. The word "gentoo-" matches itself.
3. The construct ([^(]+) matches one more more characters
that are not opening parenthesis. This should collect
the letters of the topic part of the incoming names.
4. The backslash followed by opening paren "\(" matches
exactly one opening parenthesis, which is the one
between the topic and category parts of the filenames.
5. ([^)]+) matches the category, up to (but not including)
the closing parenthesis.
6. Then follows a backslash-escaped closing parenthesis.
7. The sequence "\.htm" matches a dot followed by the three
letters "htm".
8. The dollar sign anchors the expression to the end of
the string, so that the ".htm" is really the final part
of the filename.
OK. That should take care of the incoming filenames, make
sure they have the desired format, while at the same time
storing away the information we want to conserve. Now, we
specify a "To" string like this:
"$2-$1.html"
That's all there is! The $2 will insert the text that
matched the second parenthesized subexpression, i.e. the
one labeled 5 in the above breakdown. This will make the
category appear first in the output. The dash goes straight
through into the output name, followed by the topic as
referenced by the $1 operator. The dot and the "html" suffix
go straight through as well.
Of course, we could have used a subexpression to
match the "htm" extension as well, and entered "$3l" in the
"To" string to add the final 'l', but that seemed like over-
kill to me... :)
The point of this example was to show how you can
do fairly non-trivial permutations of the input filenames.
A good understanding of regular expressions helps.
4. CLOSING WORDS
Well, that should introduce the RenameRE command sufficiently
and allow you to use it. The Simple mode is probably simple
enough to just use once you know what its parameters mean,
while the full-blown Regular Expression mode might warrant
some practice. Anway, enjoy!
