Fork: 0
tundra / tren
Browse code
More work on templates.
master
1 parent f6ac4a1 commit b04fe2dd0274fa3e8c158fdb8a09d9fd8169ba6c
@tundra tundra authored on 19 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
431
■■■■■
 tren.rst
--------
 
::
 
tren.py [-acbeghpqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ...
tren.py [-cbefghqtvx] [-l string] [-r old=new]... file|dir file|dir ...
 
 
DESCRIPTION
-----------
the new name already exists. Such attempts will cause no change to the
file or directory being processed and a warning message will be
displayed. This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename.
 
**tren** supports two kinds of renaming operations, *String Substitution*
and *Rename By Template*.
 
 
String Substition
-----------------
 
String substitution is handy when you have files and directories
that have a common set of characters in them you'd like to change.
For instance::
rename. You can override this default and *force* a renaming and thus
the removal of such existing files or directories (``-f`` option).
 
**tren** supports a variety of renaming mechanisms. The one thing
they have in common is that you must specify an *old string* which
will be replaced by a *new string* when the file or directory is
renamed. Each of these can take on one of several forms:
 
---------- ----------
Old String New String
---------- ----------
 
Literal Text Literal Text
Regular Expression Literal Text With Templates
Literal Text With Templates
 
The sections below describe each of these mechanisms.
 
 
Literal String Substitution
---------------------------
 
Literal String Substitution is just that - it replaces one literal
string with another to rename the target file or directory. This is
handy when you have files and directories that have a common set of
characters in them you'd like to change. For instance::
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
would rename all files (or directories) whose names contained the string
``.Jpeg`` and replace it with ``.jpg``. It's important to realize that
such a substitution takes place *anywhere* in the file name, not just at
the end or "extension" (as it is called in Windows). You can limit
the replacement to just the "name" (``-b``) or "extension" (``-e``)
portions of the filename.
would rename all files (or directories) whose names contained the
string ``.Jpeg`` and replace it with ``.jpg``. It's important to
realize that such a substitution takes place *anywhere* in the file
name, not just at the end or "extension" (as it is called in Windows).
You can limit the replacement to just the "name" (``-b``) or
"extension" (``-e``) portions of the filename.
 
You may specify multiple replacement operations (``-r``) on the **tren**
command line::
 
tren.py -r .Jpeg=.jpg -r old=ReallyOld *
 
This would rename all the files in the current directory, replacing
``.Jpeg`` with ``.jpg`` and ``old`` with ``ReallyOld`` anywhere these
strings appeared in any of the file or directory names.
 
By default, only the first instance of the string is replaced in the
name, but you can use the ``-g`` option to replace *all* instances
of the old string with the new one.
 
Ordinarily **tren** treats both the old string you specify with
the ``-r`` option *literally*. However, it is sometimes handy
to be able to write a regular expression to specify what you
want replaced. If you specify the ``-x`` option, **tren** will
treat your old string as a Python style regex, compile it (or
try to anyway!) and use it to select which strings to replace.
This makes it much easier to rename files that have repeated
characters or patterns, and groups of files that have similar,
but not idential strings in their names you'd like to replace.
 
 
Rename By Template
------------------
 
It is sometimes useful to be able to take a group of files/directories
whose names have nothing in common and impose a common naming scheme
on them. For example, suppose you and your friends pool your vacation
photos but each of your cameras uses a slightly different naming
scheme. You might want to just reorder them by the date and time each
picture was taken, for example. That way you end up with one
coherent set of named and numbered files. You might have
name, but you can use the ``-g`` option to replace *all* instances of
the old string with the new one.
 
If you need to include the equals sign as part of the old string or
the new string literal text, you have to escape it (``\=``)::
 
tren.py -r name\=bob=name\=sally name=bob.dbms
 
This renames the file ``name=bob.dbms`` to ``name=sally.dbms``.
 
 
Using Regular Expressions
-------------------------
 
Ordinarily **tren** treats both the old string you specify with the
``-r`` option *literally*. However, it is sometimes handy to be able
to write a regular expression to specify what you want replaced. If
you specify the ``-x`` option, **tren** will treat your old string as
a Python style regex, compile it (or try to anyway!) and use it to
select which strings to replace. This makes it much easier to rename
files that have repeated characters or patterns, and groups of files
that have similar, but not idential strings in their names you'd like
to replace.
 
Say you have a set of files that are similar, but not idential in
name, and you want to rename them all::
 
sbbs-1.txt
sbbbs-2.txt
sbbbbbbbbs-3.txt
 
Suppose you want to rename them, replacing two or more instances of
``b`` with ``X``. It is tedious to have to write a separate literal
``-r old:new`` string substitution for each instance above. This is
where regular expressions can come in handy. When you invoke the
``-x`` option, **tren** understands this to mean that the ``old``
portion of the replacement option is to be treated as a *Python style
regular expression*. That way, a single string can be used to match
many cases::
tren.py -x -r bb+:X *.txt
 
This renames the files to::
 
sXs-1.txt
sXs-2.txt
sXs-3.txt
 
Keep in mind that a literal string is a subset of a regular
expression. This effectively means that with ``-x`` processing
enabled you can include *both* regular expressions and literal text in
your "old string" specification. The only requirement is that the
string taken as a whole be a valid Python regular expression. If it
is not, **tren** will display an error message to that effect.
 
Because Python regular expressions can make use of the ``=`` symbol,
you need a way to distinguish between an ``=`` used in a regular
exression and the same symbol used to separate the old and new
operands for the ``-r`` option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: ``\=``.
 
 
An Overview Templates
---------------------
 
**tren** implements the notion of *Renaming Templates*. These can
appear in either the old- or the new string components of a ``-r``
renaming argument.
 
It is sometimes useful to be able to take a group of files or
directories whose names have nothing in common and impose a common
naming scheme on them. For example, suppose you and your friends pool
your vacation photos but each of your cameras uses a slightly
different naming scheme. You might want to just reorder them by the
date and time each picture was taken, for example. That way you end
up with one coherent set of named and numbered files. You might have
something like this::
 
DSC002.jpg (Bob's camera, taken 1-5-2010 at noon)
dc0234.Jpg (Mary's camera, taken 1-5-2010 at 8am)
032344.jpeg (Sid's camera, taken 1-3-2010 at 4pm)
 
It would be nice to get these in order somehow.
 
*Rename By Template* provides this ability. Given a list of files,
*Renaming Templates* provide this ability. Given a list of files,
you apply a "template" or pattern to be used when renaming them. This
template is nothing more than a string containing both literal
text and so-called *renaming tokens* built into **tren**.
template is nothing more than a string containing so-called *Renaming
Tokens* built into **tren**, and optionally, literal text, and even
regular expressions (old string only).
 
There's a whole section later in this document on template
construction and the use of renaming tokens, but here's a simple
example to illustrate the general idea using the files above::
 
tren.py -T /D/-MyVacation-/0001/.jpeg *.jp*
tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp*
 
This would rename all the files in the current directory ending with
``.jp*``. The ``/D/`` would be replaced with the *date* the picture
was taken. The ``/0001/`` refers to a *starting sequence number* to
was taken. The ``/+T0001/`` refers to a *starting sequence number* to
uniquely identify pictures taken on the same date. The other strings
in the template, ``-MyVacation-`` and ``.jpeg``, are inserted
*literally* in the final file names. After we ran this command, the
files above would end up with these names::
20100105-MyVacation-0001.jpeg (Mary's)
20100105-MyVacation-0002.jpeg (Bob's)
 
Notice that the files taken on the same date have been sequenced by
the time-of-day they were taken because we included the ``/0001/``
renaming token in our pattern.
the time-of-day they were taken because we included the ``/+T0001/``
renaming token in our pattern. The ``+`` here means to construct
the sequence in *ascending* order. A ``-`` would specify
*descending* order.
 
There are many other renaming tokens and ways to construct
all manner of clever templates. These are discussed below in the
section entitled `TEMPLATE CONSTRUCTION`_.
 
Ordinarily the template text *replaces* the *entire* existing
filename. You can limit the replacement to either the "name" (``-b``)
or "extension" (``-e``) portions of the filename. Instead of
replacing the existing name, extension, or both, you can also choose
to append (``-a``) or prepend ``-p`` the template text.
 
Notice that there is *no old string* in our example above.
That is, there is nothing to the left of the ``=`` symbol
in the ``-r`` option. This effectively means "match anything"
in the existing file or directory name. If you were using
regular expressions (``-x``) you could do the same thing
with::
 
-r *=/D/-MyVacation-/+T001/.jpeg *.jp*
 
Ordinarily the template text replaces the *entire* existing filename
when you do this. You can limit the replacement to either the "name"
(``-b``) or "extension" (``-e``) portions of the filename.
 
Of course, you don't *have* to replace the entire filename when
using templates. It's perfectly legitimate to replace only
a portion of the existing name::
 
tren.py -r file=/D/-file file-1 file.2
 
This would rename our files to: ``20100101-file-1 and 20100101-file.2
 
You can even use templates in your *old string* specification.
For instance, suppose you manage a number of different systems
that set their system name in an environment variable called SYSNAME.
You might then do something like this::
 
tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old
 
If your system name were "matrix", then the command above would only
rename files in the form ``matrix<anytext>bku``. If your system name
were "modar", then the command above would only rename files in the
form ``modar<anytext>bku``.
 
There are a couple of things to keep in mind when doing things like
this:
 
1) The ``/$SYSNAME/`` in the old string is used to *find the
text to rename*, whereas the same renaming token in the
new string means *insert the contents of that environment
variable here*.
 
2) Renaming tokens are always evaluated *before* any regular
expression processing takes place. It's up to you to
make sure that when you combine the two (as we have in
the example above), *that the final result is still a
valid Python regular expression*. This may involve
explicit quoting of the renaming tokens used in the old
string specification.
 
 
 
OPTIONS
-------
 
-T template Rename by template.
 
(*Default*: Rename via string replacement.)
 
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
 
-a Append the template text to the existing file or directory
name.
 
(*Default*: Replace the file or directory name with the
template text.)
 
 
-b Only perform renaming within "name" portion of file
or directory name.
 
to do the requested renaming *only* in the filename
"extension" not on the file name portion. For example::
 
tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg
 
-f Force renaming even if target file or directory name already
exists.
 
(*Default*: Skip renaming if a file or directory already
exists by the same name as the target.)
 
-g Replace all instances (greedy replace) of the old string
with the new.
 
of the separator to split the whole filename into name
and extension components. Notice also that when you do
this, no renaming of characters *within* the separator
takes place.
 
-p Prepend the template text to the existing file or directory
name.
 
(*Default*: Replace the file or directory name with the
template text.)
 
 
-q Quiet mode, do not show progress.
 
(*Default*: Display progress)
style regular expression for matching purposes.
 
(*Default*: Treat the old string as literal text)
 
String substitution arguments to the ``-r`` option are usually
understood to be taken literally. There are, however, instances
where this is tedius to do. Say you have a set of files
that are similar, but not idential in name, and you want to
rename them all::
 
sbbs-1.txt
sbbbs-2.txt
sbbbbbbbbs-3.txt
 
Suppose you want to rename them, replacing two or more instances
of ``b`` with ``X``. It is tedious to have to write a separate
``-r old:new`` string substitution for each instance above.
This is where regular expressions can come in handy. When you
invoke the ``-x`` option, **tren** understands this to mean that
the ``old`` portion of the replacement option is to be treated as
a *Python style regular expression*. That way, a single string
can be used to match many cases::
tren.py -x -r bb+:X *.txt
 
This renames the files to::
 
sXs-1.txt
sXs-2.txt
sXs-3.txt
 
**tren** only accepts Python style regular expressions. Anything
else will cause an error message to be displayed.
 
Because Python regular expressions can make use of the ``=``
symbol, you need a way to distinguish between an ``=`` used in a
regular exression and the same symbol used to separate the old
and new operands for the ``-r`` option. Where this symbol needs to
appear in a regular expression, it has to be escaped like this:
``\=``.
 
 
TEMPLATE CONSTRUCTION
---------------------
type:
D sequence on file creation date & time
O sequence on the command line file order
R sequence on the command line file order
S sequence on file size
T sequence on file creation time within a given day
 
 
Use template to change file "extension"::
 
tren.py -e -T /D/ file.1 # file.20100112
 
Append template text::
 
tren.py -a -T ./D/ file.1 # file.1.20100112
 
Prepend template text::
 
tren.py -p -T /D/- file.1 # 20100112-file.1
 
Get help::
 
tren.py -h
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.121 2010/01/18 23:43:36 tundra Exp $
$Id: tren.rst,v 1.122 2010/01/19 20:48:10 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren