Fork: 0
tundra / tren
Browse code
Wrote tutorial on instances.
master
1 parent b7bdaf3 commit 3a239b96ef9e4f22e0cbefab3b48eb4c6dad04ff
@tundra tundra authored on 25 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
159
■■■■■
 tren.rst
You can also refer to instances relative to the
right. So the -1 instance is the last (rightmost),
-2, second from the last, and so forth.
 
A "range" of instances is specified
using the ``:`` separator in the form::
Often, you just want to replace a specific instance::
 
-i :3 -r foo=boo
-i :-1 -r foo=boo
 
Both of these refer to the last instance of old string
``foo`` (found at ``foo4`` in our example name).
 
Sometimes, you'd like to replae a whole *range* of
instances. An "instance range" is specified using the
``:`` separator in the form::
 
-i first-to-replace:stop-here
 
All instances from the "first-to-replace"
up to, *but NOT including* "the stop-here"
are replaced. ``-i :`` means "replace
*all* instances.
 
Examples::
 
tren.py -i 1 -r f=b foo1-foo2-foo3.foo4
-> foo1-boo2-foo3.foo4
 
tren.py -i -1 -r f=b foo1-foo2-foo3.foo4
-> foo1-foo2-foo3.boo4
 
tren.py -i 1:3 -r f=b foo1-foo2-foo3.foo4
-> foo1-boo2-boo3.foo4
 
tren.py -i -4:-2 -r f=b foo1-foo2-foo3.foo4
-> boo1-boo2-foo3.foo4
 
tren.py -i : -r f=b foo1-foo2-foo3.foo4
-> boo1-boo2-boo3.boo4
 
Notice that the "stop-here" instance is NOT replaced.
In our string above, the option::
 
-i 1:-1 -r foo=boo
 
Would change the file name to::
 
foo1-boo2-boo3.foo4
 
You can also provide partial ranges::
 
-i 1: # From instance 1 to end of name
 
-i :-2 # All instances up to (not including) next-to-last
 
-i : # All instances
-P char Use ``char`` as the escape symbol.
(*Default*: ``\``)
 
 
Substitution Instances
======================
 
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.
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.
 
Instances are nothing more than *numbers* that tell **tren** just
where in the name you'd like the replacement to take place. Positive
numbers means we're counting instances from the *left* end of the
name. The leftmost instance is 0 (not 1!!!).
 
You can also count *backwards* from the right end of the string using
negative numbers. -1 means the last instance, -2 means next-to-last,
and so on. In summary, counting from the left starts at zero and
counting from the right starts at -1.
 
Suppose you have a file called::
 
foo1-foo2-foo3.foo4
 
The leftmost ``foo1`` is instance 0 of old string ``foo``. It is also
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::
 
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
 
 
You can also specify a *range of instances* to replace using the
notation::
 
-i first-to-replace:stop-here
 
All instances from the "first-to-replace" up to, *but NOT including*
"the stop-here" are replaced::
 
tren.py -i 1:3 -r f=b foo1-foo2-foo3.foo4 # New Name: foo1-boo2-boo3.foo4
 
tren.py -i -4:-2 -r f=b foo1-foo2-foo3.foo4 # New Name: boo1-boo2-foo3.foo4
 
``-i :`` means "replace *all* instances::
 
tren.py -i : -r f=b foo1-foo2-foo3.foo4 # New Name: boo1-boo2-boo3.boo4
 
You can also use *partial range specifications*::
 
tren.py -i 1: -r f=b foo1-foo2-foo3.foo4 # New Name: foo1-boo2-boo3.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
requires two renaming requests. The good news is that we can do them
both on a single **tren** invocation.
 
 
Multiple Substitutions
======================
 
You may specify multiple ``-r`` replacement operations on the **tren**
command line::
 
tren.py -g -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.
 
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``.
 
 
 
 
Forcing Renaming
-----------------------------
 
::
 
$Id: tren.rst,v 1.148 2010/03/25 22:39:58 tundra Exp $
$Id: tren.rst,v 1.149 2010/03/25 23:36:58 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren