Fork: 0
tundra / tren
Browse code
Fixed verbatim sections that needed to be wrapped for proper pdf/ps output.
Removed warning about cygwin platform.
master
1 parent addf592 commit fdab147c2217bb389b76011cff5c2e022ec3b228
@tundra tundra authored on 29 Aug 2010
Patch
Unified Split
Showing 1 changed file
View
129
■■■■■
 tren.rst
renamed. If one of your rename targets start with the ``-``
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::
 
 
(*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.
 
When looking for a match on the old string to replace,
**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
is preserved.
this path. If none are found, ``tren`` uses the file path as passed on
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 *
 
'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
export TRENINCL=$HOME/.tren:/some/where/else
cp file1 $HOME/.tren/
tren.py -I file1 -I foo/file2 -I /foo/bar/file3 *
 
'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.
For Windows, this is ``;``, For all other supported OSes, it
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 1: # Instance 1 to end of name
 
-i :-2 # Instances to (not including) next-to-last
 
-i : # All instances
-P char Use ``char`` as the escape symbol.
 
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.
By default, **tren** will refuse to overwrite an existing filename, so
 
 
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-foo2-foo3.boo4
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::
 
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
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
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
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
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 -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
renaming request.
 
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``
 
This is the number for the group to which the file- or
from "interpolating" the variables before **tren** is
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
equivalent function. The *only* way to achieve what these
do on Windows is via renaming tokens. In Windows, you also
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``
 
 
.. 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::
 
tren.py -r=InHexMtimeOrder-0x/+MTIME:HexLower:00000/ *
argument to the ``-r`` option, thereby separating the
text from the count::
 
-r=InHexMtimeOrder-0x/+MTIME:HexLower:00000/
 
In short, **tren** treats *every character in a counting pattern
the same* - with complete indifference.
 
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
 
``win32all`` Python extensions installed, **tren** will take advantage
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
OS X. It has not, however, been run on 64-bit versions of those OSs.
**tren** is primarily intented for use by power users, sys admins, and
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/
 
 
-----------------------------
 
::
 
$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:
 
http://www.tundraware.com/Software/tren