Fork: 0
tundra / tren
Browse code
Wrote section on multiple substitutions.
Removed "Examples" section.
master
1 parent 3a239b9 commit 6e5c076147258716f5771ed87d4f7c54fbd123a1
@tundra tundra authored on 25 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
202
■■■■■
 tren.rst
explicit "end of options" delimiter::
 
tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
 
Most shells aren't too fussy about space between an option
that takes an argument, and that argument::
 
-i 1
-i1
 
Use whichever form you prefer. Just be aware that there are places
where spaces matter. For example, you can quote spaces on your
command line to create renaming requests that, say, replace spaces
with dashes..
 
Some options below are "global" - they change the state of the entire
program permanently and cannot be undone by subsequent options. Some
options are "toggles", they can be turned on- and off as you move from
 
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
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
line *from left to right*, incrementally constructing the new name
as it goes. For instance::
 
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?
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
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
on the command line will work fine, but you have to do one of
two things (or both):
 
1) Make sure you're tracking what the "intermediate" names
will look like as the new file name is being constructed,
renaming request, by renaming request.
 
2) Make sure the renaming requests operate on completely
disjoint parts of the file name.
 
.. NOTE:: Similarly, **tren** remembers the last state of each option
as you move from left to right on the command line. For instance::
 
tren.py -i1 -r f=F -r o=O foo1-foo2-foo3.foo4
 
You might be tempted to believe that this would produce,
``fOo1-Foo2-foo3.foo4``, but it doesn't. It produces,
``foO1-Foo2-foo3.foo4`` instead because the ``-i 1`` appears
prior to *both* renaming requests and thus applies to each
of them. If you want the first instance of "o" to be
replaced, you need a command line like this::
 
tren.py -i1 -r f=F -i0 -r o=O foo1-foo2-foo3.foo4
 
This sort of thing is generally true for *all* options, so
be sure they're set the way you want them to the left of a
renaming request.
 
As a practical matter, this can get really complicated to track. If
in doubt, it's always better to run two separate **tren** commands in,
say, a shell script to make the renaming explicit, rather than to
obscure things with clever command line trickery.
 
So, let's go back to our example from the previous section. We
want to replace the 2nd and 4th instances of the string "foo"
in our file name. We do this with two renaming requests on the
same command line, considering what each one does to the name
as it is encountered::
 
tren.py -i1 -r foo=bar -i2 -r foo=bar foo1-foo2-foo3.foo4
 
 
 
Forcing Renaming
For most purposes, though, the order, rather than the
absolute time is both more useful and more readable.
 
 
EXAMPLES
--------
 
Here are some common examples of **tren** in action - the resulting
file name(s) shown to the right as a comment. Study each example
carefully. Small subtleties are introduced in various adjacent
examples to illustrate different features of **tren**:
 
 
Get help::
 
tren.py -h
 
Print out detailed version information::
 
tren.py -v
 
Simple rename::
 
tren.py -r old=New fold.txt log.old # fNew.txt log.New
 
Change file "name"::
 
tren.py -b -r old=New fold.txt log.old # fNew.txt log.old
 
Change file "extension"::
 
tren.py -e -r old=New fold.txt log.old # fold.txt log.New
 
Rename all instances of a given string::
 
tren.py -g -r bin=Bin binary_bin.binbin # Binary_Bin.BinBin
 
Rename, ignoring case::
 
tren.py -c -r bin=BIN Binary_bIN.txt # BINary_bIN.txt
 
Rename multiple strings at once::
 
tren.py -r log=txt -r New=old New.log # old.txt
 
Rename using regular expressions::
 
tren.py -x -r a+=a Saaaaaaaally.doc # Sally.doc
 
Rename a file containing the ``=`` symbol::
 
tren.py -r a\=b=c\=d a=b.txt # c=d.txt
 
Use renaming token::
 
tren.py -r =/I/ file.1 # 2010-01-12
 
Use renaming token to change file "name"::
 
tren.py -b -r =/I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2
 
Use renaming token to change file "extension"::
 
tren.py -e -r =/D/ file.1 # file.20100112
 
 
BUGS, MISFEATURES, OTHER
------------------------
 
You must be running Python 2.6.x or later. **tren** makes use of
-----------------------------
 
::
 
$Id: tren.rst,v 1.149 2010/03/25 23:36:58 tundra Exp $
$Id: tren.rst,v 1.150 2010/03/26 00:17:52 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren