diff --git a/tren.rst b/tren.rst index 0f76d12..9b968a8 100644 --- a/tren.rst +++ b/tren.rst @@ -63,7 +63,7 @@ character, most command shells recognize the double dash as an explicit "end of options" delimiter:: - tren.py -opt -opt -opt -- -this_file_starts_with_a_dash + tren.py -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:: @@ -117,13 +117,17 @@ (*Default*: off) If you invoke this option, **tren** will prompt you before - renaming each file. The default (if you just hit ``Enter``) - is to *not* rename the file. Otherwise, you have the following + renaming each file. The default (if you just hit ``Enter``) is + to *not* rename the file. Otherwise, you have the following options:: n - Don't rename the current file + y - Rename the current file - ! - Rename all the remaining files without further prompting + + ! - Rename all the remaining files + without further prompting + q - Quit the program These options are all insensitive to case. @@ -171,7 +175,7 @@ **tren** will ignore the case of the characters found in the filename. For example:: - tren.py -c -r Old=NEW Cold.txt fOlD.txt + tren.py -cr Old=NEW Cold.txt fOlD.txt This renames both files to ``CNEW.txt`` and ``fNEW.txt`` respectively. Notice that the new (replacement) string's case @@ -265,13 +269,13 @@ the command line. This allows relative- and absolute include file paths to be used along with files in an include path:: - export TRENINCL=$HOME/.tren:/some/where/else:/and/else/where - cp include_file $HOME/.tren/ - tren.py -I include_file -I foo/rel_include -I /foo/bar/abs_include * + export TRENINCL=$HOME/.tren:/some/where/else + cp file1 $HOME/.tren/ + tren.py -I file1 -I foo/file2 -I /foo/bar/file3 * - 'include_file' will be found in $HOME/.tren/ - 'rel_include' will be found relative to current dir - 'abs_include' will be found on absolute path + 'file1' will be found in $HOME/.tren/ + 'file2' will be found relative to current dir + 'file3' will be found on absolute path Note that when defining ``TRENINCL``, you must use the path delimiter appropriate for the operating system in question. @@ -320,9 +324,9 @@ You can also provide partial ranges:: - -i 1: # From instance 1 to end of name + -i 1: # Instance 1 to end of name - -i :-2 # All instances up to (not including) next-to-last + -i :-2 # Instances to (not including) next-to-last -i : # All instances @@ -709,7 +713,7 @@ If you omit the ``old`` string, you're telling **tren** to *change the whole file name*:: - tren.py -r =MyNewFilename foo # New Name: MyNewFilename + 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. @@ -776,9 +780,9 @@ 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-boo2-foo3.foo4 - tren.py -i -1 -r f=b foo1-foo2-foo3.foo4 # New Name: foo1-foo2-foo3.boo4 + 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 @@ -789,19 +793,19 @@ 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 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 + tren.py -i -4:-2 -r f=b foo1-foo2-foo3.foo4 #New Name: boo1-boo2-foo3.foo4 -``-i :`` means "replace *all* instances:: +``-i :`` means "replace *all* instances":: - tren.py -i : -r f=b foo1-foo2-foo3.foo4 # New Name: boo1-boo2-boo3.boo4 + 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 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 + 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 @@ -859,14 +863,20 @@ 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:: + You might be tempted to believe that this would produce:: - tren.py -i1 -r f=F -i0 -r o=O foo1-foo2-foo3.foo4 + 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 -rf=F -i0 -ro=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 @@ -1640,7 +1650,7 @@ tren.py -r=/FNAME/-suffix ... # Adds "-suffix" to original name tren.py -r=prefix-/FNAME/ ... # Adds "-prefix" to original name tren.py -r /FNAME/=newname ... # Same as "-r=newname" - tren.py -r /FNAME/=/FNAME/ ... # Does nothing since old- and newname are the same + tren.py -r /FNAME/=/FNAME/ ... # Does nothing: old/new are same - ``/GID/ Returns File- Or Directory's Group ID`` @@ -1869,8 +1879,8 @@ called. If you don't do this, **tren** will complain about encountering unknown renaming tokens:: - tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # This is correct - tren.py -r =/`uname -n`/-/FNAME/ *.sh # This will fail + tren.py -r='/`uname -n`/'-/FNAME/ *.sh # Right + tren.py -r=/`uname -n`/-/FNAME/ *.sh # Wrong The real reason for providing these renaming tokens at all is because the Windows command interpreter does not have an @@ -1879,15 +1889,15 @@ have to pay attention to quoting, particularly when there are spaces in a ```cmd``` renaming token:: - tren.py -r=/FNAME/-/`command option1 option2 argument`/ files ... + tren.py -r=/FNAME/-/`command opts args`/ ... This causes **tren** to complain mightily because it thinks - ``/`command``, ``option``, ``option2``, are all separate + ``/`command``, ``opts``, ``args``, are all separate (invalid) command line arguments. To avoid this problem, you need to pass the renaming token as a single command line entity via quotes:: - tren.py -r=/FNAME/-"/`command option1 option2 argument`/" files ... + tren.py -r=/FNAME/-"/`command opts args`/" ... - ``/RAND#/ Random Number Generator`` @@ -2257,9 +2267,10 @@ .. TIP:: We could avoid the possibility of having the count ever consume our literal text, by taking it *out of the sequence renaming token* and putting it in as a literal - argument to the ``-r`` option:: + argument to the ``-r`` option, thereby separating the + text from the count:: - tren.py -r=InHexMtimeOrder-0x/+MTIME:HexLower:00000/ * + -r=InHexMtimeOrder-0x/+MTIME:HexLower:00000/ In short, **tren** treats *every character in a counting pattern @@ -2598,14 +2609,14 @@ Sometimes, all you want to do is replace a single substring in a name:: - tren.py -r Old=New OldRecords-OldPeople # Yields: NewRecords-OldPeople + tren.py -r Old=New OldHair-OldPeople # Yields: NewHair-OldPeople - Replacing Or Removing All Instances Of A String Sometimes you want to replace every instance of the string:: - tren.py -i : -r Old=New OldRecords-OldPeople # Yields: NewRecords-NewPeople + tren.py -i : -r Old=New OldHair-OldPeople # Yields: NewHair-NewPeople - Changing A File's "Extension" Suffix @@ -2733,12 +2744,6 @@ of them for purposes of deriving the names of the user and group that own the file or directory being renamed. - .. WARNING:: As of this writing, **tren** will not run in the - **cygwin** environment because their version of Python - is still backleveled to 2.5.x. When and if the - **cygwin** team upgrades to 2.6.x, **tren** is expected - to work there as well. - This program is **EXPERIMENTAL** (see the license). This means its had some testing but is certainly not guaranteed to be perfect. As of this writing, it has been run on FreeBSD, Linux, Windows XP, and Mac @@ -2755,8 +2760,8 @@ advanced users that (mostly) find GUIs more of a nuisance than a help. There are times, however when it would be handy to be able to select the files to be renamed graphically. TundraWare has a freely -available file browser that is macro programmed. It will work nicely -in such applications: +available macro programmed file browser. It will work nicely in such +applications: http://www.tundraware.com/Software/twander/ @@ -2787,7 +2792,7 @@ :: - $Id: tren.rst,v 1.188 2010/08/28 00:00:28 tundra Exp $ + $Id: tren.rst,v 1.189 2010/08/29 23:30:45 tundra Exp $ You can find the latest version of this program at: