Fork: 0
tundra / tren
Browse code
Finished documenting -T and slice notation.
master
1 parent c70cf71 commit a38a8baaebfb12c8744bd09426d099181c7d24e2
@tundra tundra authored on 16 Nov 2010
Patch
Unified Split
Showing 1 changed file
View
145
■■■■■
 tren.rst
second example, removing the ``-T`` targeting gives us::
 
tren.py -i: -re=E abcdef.text # -> abcdEf.tExt
In summary, ``-T`` defines what substring of the full name
So, ``-T`` lets you specify what substring of the full name
is a candidate for renaming. All other renaming operations
like ``-i``, ``-r``, and so on operate *only upon the substring
specified by* ``-T``.
 
If you specify multiple renaming operations on the command line,
any ``-T`` targeting will remain in effect *for each renaming request*.
For instance::
 
tren.py -T -1 -r=OO -r=x foo
 
This will yield incremental renamings of::
 
foo -> foOO
foOO -> foOx # Final name
 
In other words, each incremental renaming request honors the
current state of the ``-T`` option. To turn off targeted
renaming - that is, make the whole file name the target again,
simply include ``-T :`` on the command line. All renaming requests
to the right of it will then target the whole name::
 
tren.py -T -1 -r=OO -T: -rO=x foo # Yields: foxO
 
 
More About Slice Notation
=========================
**tren** is written in the Python programing language. The slice
notation is lifted directly from that language. if you're a Python
programmer, you can skip this section :)
 
Imagine you have a filename like this::
Imagine you have a file name like this::
 
abcdef.txt
 
 
 
 
 
Each character in the name has an "index" or number that
tells you what position is occupies in the name. You can
count from the *left end* of the name starting with 0:
 
========= ===============
Character Index From Left
--------- ---------------
 
a 0
b 1
...
x 8
t 9
========= ===============
 
 
You can also count backwards relative to the *right end of
the name*:
 
========= ================
Character Index From Right
--------- ---------------=
 
a -10
b -9
...
x -2
t -1
========= ================
 
Notice that left-relative indexes are positive numbers beginning with
0, but right-relative indexes are are negative numbers beginning at -1.
 
So, what's a slice? A slice is a way of specifying *a range of one or more values*.
In the case of the ``-T`` argument, "values" means "positions in the name string
targeted for renaming." In the case of the ``-i`` argument, "values" means
*which instances of a given string should be renamed*.
 
In our example above, the ``bcd`` portion of the name could be
defined several different ways::
 
1:4
-9:-6
 
The general form of a slice is::
 
first character/instance:stop on this character or instance
 
This can be tricky to get used to. The number on the righthand side
*is not included in he slice* - it is where the slice *ends*.
 
There are other shortcut forms of slice notation::
 
:3 # Same as 0:3
3: # Start with 4th char/instance and go through, and including last one
: # All chars/instances are included in the slice
 
In short, slices are a compact way to specify a range of things. If
you specify a slice that makes no sense like ``-4:3``, **tren** will
just ignore it and not do any consequent renaming.
 
 
Multiple Substitutions
======================
-----------------------------
 
::
 
$Id: tren.rst,v 1.194 2010/10/18 19:06:29 tundra Exp $
$Id: tren.rst,v 1.195 2010/11/16 20:22:12 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren