diff --git a/tren.rst b/tren.rst index 75dada6..62f995a 100644 --- a/tren.rst +++ b/tren.rst @@ -919,11 +919,30 @@ 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 ========================= @@ -942,14 +961,71 @@ 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 @@ -2951,7 +3027,7 @@ :: - $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: