Fork: 0
tundra / tren
Browse code
Added description of partial literal renaming requests and name length limitations.
master
1 parent 832cf8c commit 2d8a14561a8624475b6bad5daa06db570173a86a
@tundra tundra authored on 26 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
120
■■■■■
 tren.rst
-i instances Specifies which "instances" of matching strings should
be replaced.
(*Default*: 0 or leftmost)
 
A file may have multiple instances of the "old"
A file may have multiple instances of the ``old``
renaming string in it. The ``-i`` option lets you
specify which of these (one, several, all) you'd
like to have replaced.
 
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
This would rename all files (or directories) whose names contained the
string ``.Jpeg`` and replace it with ``.jpg``. Well ... that's
not quite right. Unless you specify otherwise with the ``-i``
option, *only the first (leftmost) instance of ``old`` is replaced
with ``new``*. So, for example, if you started out with the file,
``My.Jpeg.Jpeg`` and ran the command above, you'd end up with a
new file name of ``My.jpg.Jpeg``
string ``.Jpeg`` and replace it with ``.jpg``. Well ... that's not
quite right. Unless you specify otherwise with the ``-i`` option,
*only the first (leftmost) instance of ``old`` is replaced with
``new``*. So, for example, if you started out with the file,
``My.Jpeg.Jpeg`` and ran the command above, you'd end up with a new
file name of ``My.jpg.Jpeg``
 
You can omit either ``old`` or ``new`` strings in a renaming
specification, but never both.
 
If you omit the ``old`` string, you're telling **tren** to *change the
whole file name*::
 
tren.py -r =MyNewFilename foo # New Name: MyNewFilename
 
Be careful with this one. If you apply it to a list of files or
directories, it's going to try and name them all to the *same* name.
By default, **tren** will refuse to overwrite an existing filename, so
it will stop you from doing this. If you absolutely insist on this
via the ``-f`` option, you'll get a bunch of files ending with
``.backup``. Say you have files ``a``, ``b``, and ``c``::
 
tren.py -fr =NewName a b c
 
When the command completes, the files will have been renamed
in this fashion::
 
a -> NewName.backup.backup
b -> NewName.backup
c -> NewName
 
If you omit the ``new`` string, you're telling **tren** to *remove*
the leftmost instance of ``old`` string (or other instances via the
``-i`` option described below) from the file- or directory name. For
example::
 
tren.py -rfoo= foo1-foo2-foo3.foo4 # New name: 1-foo2-foo3.foo4
 
If you try to omit *both* ``old`` and ``new`` strings, you're
effectively telling **tren** to change the existing file name to
... nothing (a null string). This is impossible because file names
must be at least one character long. **tren** enforces both this
minimum length AND the maximum legal length of new file names. It
will print an error and exit if your renaming attempt would violate
either of these limits. (As of this writing, the maximum file- or
directory name length allowed by the operating systems on which
**tren** runs is 255 characters.)
 
 
Substitution Instances
======================
 
As we just saw above, sometimes the "old" string appears in several
As we just saw above, sometimes the ``old`` string appears in several
places in a file- or directory name. By default, **tren** only
replaces the first, or leftmost "instance" of an "old" string.
replaces the first, or leftmost "instance" of an ``old`` string.
However, using the ``-i`` option you can specify *any* instance you'd
like to replace. In fact, you can even specify a *range* of instances
to replace.
 
instance -4. The rightmost ``foo4`` is instance 3 of old string
``foo``, and also instance -1.
 
 
You can specify a *single instance* (other than the default leftmost)
to replace::
You can specify a *single instance* to replace::
 
tren.py -i 1 -r f=b foo1-foo2-foo3.foo4 # New name: foo1-boo2-foo3.foo4
 
tren.py -i -1 -r f=b foo1-foo2-foo3.foo4 # New Name: foo1-foo2-foo3.boo4
tren.py -i :-2 -r f=b foo1-foo2-foo3.foo4 # New Name: boo1-boo2-foo3.foo4
 
Note that you cannot specify individual, non-adjacent instances.
There is no way to use a single **tren** command to replace, say, the
only the 2nd and the 4th instance of an "old" string. Doing that
only the 2nd and the 4th instance of an ``old`` string. Doing that
requires two renaming requests. The good news is that we can do them
both on a single **tren** invocation.
 
 
Multiple Substitutions
======================
 
You can put as many renaming requests on a **tren** command line as
you like .... well, up to the length limit imposed by your operating
system and shell, anyway. As we just saw, this can be handy when
you like (.... well, up to the length limit imposed by your operating
system and shell, anyway). As we just saw, this can be handy when
a single renaming request can't quite do everything we want.
 
BUT ... there's a catch. In designing your renaming requests,
you have to keep in mind that **tren** processes the command
 
tren.py -r foo=bar -r foo=baz foo1-foo2-foo3.foo4
 
Produces ... wait a second ... why on earth are there two renaming
requests with idential "old" strings on the same command line?
requests with idential ``old`` strings on the same command line?
Shouldn't this produce a final name of ``baz1-foo2-foo3.foo4``?
 
Nope. After the leftmost renaming request has been processed,
the new name is ``bar1-foo2-foo3.foo4``. Remember that, by
default, **tren** only replaces the *leftmost* or 0th instance
of an "old" string. So, when the second renaming request is
of an ``old`` string. So, when the second renaming request is
processed, the instance 0 of ``foo`` is now found in the
string ``foo2``. So, the final name will be, ``bar1-baz2-foo3.foo4``.
 
The lesson to learn from this is that multiple renaming requests
 
3) Build a table of every file name to be renamed.
 
We'll need this information if any of the renaming requests use
renaming tokens.
the file- or sequence renaming tokens (discussed later in this
document).
 
4) Build a table containg each renaming request storing the current
state of every program option at that point on the command line.
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.152 2010/03/26 01:42:13 tundra Exp $
$Id: tren.rst,v 1.153 2010/03/26 19:46:33 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren