Fork: 0
tundra / tren
Browse code
Cleaned up introductory renaming token section.
master
1 parent c52ca2d commit 0d335877450df0848d35d5e0f9ebd9794befa501
@tundra tundra authored on 29 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
210
■■■■■
 tren.rst
That's what the ``-c`` option is for::
 
tren.py -i -1 -c -r.jpeg=.jpg *.jpeg *.Jpeg *.JPEG
 
Notice that the case-insensitivity only applies to the *matching* of
Notice that the case insensitivity only applies to the *matching* of
the ``old`` string. Once **tren** has determined such a match exists,
the ``new`` string is used *literally* with case intact.
 
You can turn case sensitivity on- and off for various renaming
operands for the ``-r`` option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: ``\=``.
 
As with literal string renaming, regular expression renaming requests
honor both the case-sensitivity options (``-C`` and ``-c``) as well
honor both the case sensitivity options (``-C`` and ``-c``) as well
as the instance option, ``-i``. So, for example::
 
tren.py -x -ci -1 -r Bb+=X sbbsbbbsbbbbsbbbbbs
 
 
Interactive Renaming
====================
 
By default, **tren** attempts to perform all the renaming requests on
all the file- and directory names given on the command line
automatically. It is sometimes helpful to work *interactively*
wherein you're asked what to do for each proposed renaming.
Interactive renaming is requested via the ``-a``, "ask" option::
 
tren.py -a -rfoo=Bar foo1.txt foo2.txt foo3.txt
 
**tren** will compute each file's proposed new name and ask you
what you want to do. You have 4 possible choices::
 
N, n, or Enter - No, don't rename this file
Y, y - Yes, rename the file
! - Yes, rename this and all remaining files without asking any more
Q, q - Quit the program
 
 
There is one slight subtlety here to watch for when doing forced
renaming. As we've seen, if you select the ``-f`` option and the new
file name already exists, **tren** will backup the existing file name
before doing the renaming. In interactive mode, you will be asked
whether or not to proceed with the renaming both for the file in
question *and for any consequenent backups*. If you decline to do the
backup but accept the primary renaming, this will have the same effect
as the ``-b`` option: The existing file- or directory will be
overwritten by the renaming operation.
 
If the ``-b`` option is selected in interactive mode, then you'll only
be prompted for the primary file renamings (because ``-b`` suppresses
the creation of backups).
 
An Overview Of Renaming Tokens
==============================
 
**tren** implements the notion of *renaming tokens*. These can
naming scheme on them. Another use for renaming tokens is to do the
renaming based on some property the file or directory possesses like
its creation date, size, owner's name, and so on.
 
In their simplest form, renaming tokens are nothing more than
"canned" information **tren** knows about a particular file or
directory. For instance, if you insert the ``/D/`` token into a
old- or new string definition, **tren** will replace it with *the
creation date of the file or directory being renamed* and use that
string in the renaming process.
 
There are also tokens that allow you to use system information in your
renaming strings. Finally, there are tokens that can be used to
automatically renumber or sequence (order) a set of files or
directories being renamed.
 
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 start with something like this::
Renaming tokens are nothing more than special symbols that represent
"canned" information **tren** knows about the file- or directory
being renamed, information from the OS itself, and information used to
sequence or order the files being renamed.
 
For instance, if you insert the ``/MYEAR/`` token into a old- or new
string definition, **tren** will replace it with *the year the file or
directory being renamed was last modified* and use that string in the
renaming process::
 
tren.py -ryear=/MYEAR/ My-year.txt # New name: My-2010.txt
 
A really handy way to use renaming tokens is to name your files in a
particular *order*. 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 start
with 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::
 
tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp*
It would be nice to get these in order somehow. We can, by combining
*file* renaming tokens (that know thing about the file being renamed)
and *sequence* renaming tokens (that know how to order all the files
being renamed by some key like date, length, who owns it, and so on)::
 
tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp*
 
Every place you see something in the form ``/.../``, think, "That is a
renaming token whose value will be filled in by **tren**." This
syntax is the same whether you're using a *file*-, *system*-, or
*sequence* renaming token.
 
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 ``/+T0001/`` refers to a *starting sequence number* to
uniquely identify pictures taken on the same date. The other strings,
``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the picture
was taken. The ``/+MDATE::0001/`` refers to a *starting sequence number* to
uniquely identify files modified on the same date. The other strings,
``-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 ``/+T0001/``
renaming token in our pattern. The ``+`` here means to construct
the sequence in *ascending* order. A ``-`` would specify
*descending* order.
the time-of-day they were taken because we included the
``/+MDATE.../`` sequence renaming token in our pattern. The ``+``
here means to construct the sequence in *ascending* order. A ``-``
would specify *descending* order.
 
.. Note:: 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 "replace
everything" in the existing file or directory name. You can
do the same thing using a regular expression::
 
tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp*
 
Of course, if you use the ``-b`` or ``-e`` flags, you limit
just what portion of the filename is considered
"everything".
everything" in the existing file or directory name.
 
Of course, you don't *have* to replace the entire filename when
using tokens. 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`` Notice that we combined literal text and a renaming
tren.py -r file=/MYEAR/MMON//MDAY/-file file-1 file.2
 
This would rename our files to: ``20100101-file-1`` and
``20100101-file.2`` Notice that we combined literal text and a renaming
token to do this.
 
You can even use renaming tokens in your *old string* specification.
For instance, suppose you manage a number of different systems and you
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
set their system name in an environment variable called ``SYSNAME`` and
this same name is used to identify backup files. You might then do
something like this::
 
tren.py -xr '/$SYSNAME/.*.bku=/FNAME/.old' *
 
If your system name was "matrix", then the command above would only
rename files whose names began with ``matrix`` and ended with ``.bku``.
If your system name were "morton", then the command above would only
rename files whose names began with ``morton`` and ended with ``.bku``.
 
There are a couple of things to keep in mind when doing things like
Notice that we combined a reference to an environment variable within
a regular expression. This was done to do the match on "names
beginning with... and ending with ...". Also notice that the renaming
token ``/FNAME/`` is just the *original name of the file*.
 
In order for this to work, we had to single quote the renaming
request. This is because Unix shells will themselves try to replace
``$SYSNAME`` which is not what we want. If we don't single quote
(thereby turning off shell variable interpolation) and run this, say,
on a machine called "matrix", the command will be handed to **tren**
looking like this::
 
tren.py -xr /matrix/.*.bku=/FNAME/.old' *
 
**tren** will then promptly error out and tell you that it doesn't
know about a renaming token called ``/matrix/``.
 
There are a several 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*.
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 the two are combined (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.
 
 
**tren** has many other kinds of renaming tokens. Their
structure and use is described in some detail in the
section below entitled `Renaming Tokens: The Gory Details`_.
tokens used in the ``old`` string specification.
 
 
**tren** has many other kinds of renaming tokens. Their structure and
use is described in some detail in the section below entitled
`Renaming Tokens: The Gory Details`_.
 
 
Renaming Token Pitfalls
=======================
However, the second renaming request further modifies this to
``New-YourFile.txt``. In effect, the second renaming request is
*overwriting part of the string produced by the renaming token
reference*. This is an intentional feature of **tren** to allow
maximum renaming flexibility. However, you need to understand
how it works so you don't get unexpected and strange results.
For example, look what happens when you reverse the order
of the renaming requests in this case::
maximum renaming flexibility. However, you need to understand how it
works so you don't get unexpected and strange results. For example,
look what happens when you reverse the order of the renaming requests
in this case::
 
tren.py -r My=Your -r =New-/FNAME/ MyFile.txt
 
``My`` gets replaces with ``Your``, but as soon as the second renaming
-----------------------------
 
::
 
$Id: tren.rst,v 1.158 2010/03/29 16:15:00 tundra Exp $
$Id: tren.rst,v 1.159 2010/03/29 17:40:19 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren