Fork: 0
tundra / tren
Browse code
Added -c option for case collapsing.
Wrote detailed documentation for all options.
master
1 parent ed4c99d commit 5fe2029214d02e4dfa4639b8816fb66da461182e
@tundra tundra authored on 15 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
179
■■■■■
 tren.rst
--------
 
::
 
tren.py [-beghqtvwx] [-l string] [-m template] [-r old=new]... file|dir file|dir ...
tren.py [-cbeghqtvwx] [-l string] [-m template] [-r old=new]... file|dir file|dir ...
 
 
DESCRIPTION
-----------
tren -r .Jpeg=.jpg *.Jpeg
 
would rename all files (or directories) whose names contained the string
``.Jpeg`` and replace it with ``.jpg``. It's important to realize that
such a substitution takes place *anywhere* in the filename, not just at
such a substitution takes place *anywhere* in the file name, not just at
the end or "extension" (as it is called in Windows).
 
By default, only the first instance of the string is replaced in the
name, but you can use the ``-g`` option to replace *all* instances
-b Exclude file/directory "extension" when doing string
substitution.
(*Default*: Substitute within the entire file/directory name)
 
Many applications use the suffix of a filename to indicate the
contents or type of file. By default, **tren** does string
substiution in the entire filename *including* the extension.
For example doing this::
 
tren -r eg=ug peg.jpeg
 
Renames the file to ``pug.jpug`` .. probably not what you want.
 
The ``-b`` option tells **tren** to only perform string renaming
in the actual "name portion" of the filename thereby
cirumventing problems like this::
 
tren -b -r eg=ug peg.jpeg # Renames file to pug.jpeg
-c Collapse case when doing string substitution.
 
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 -c -r 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.
 
-e Only do string substitutions in the filename "extension".
(*Default*: Substitute within the entire file/directory name)
 
This option is the inverse of ``-b``. It instructs **tren**
to do the requested subsitution *only* in the filename
"extension" not on the file name portion. For example::
 
tren -e -r pe=p peg.jpeg # Renames file to peg.jpg
 
-g Replace all instances (greedy replace) of the old string
with the new.
 
Ordinarily, **tren** only replaces the single *leftmost*
instance of a string in the entire filename (default), the name
portion (``-b``) or the extension (``-e``). If you want
*all* instances of a particular string replaced, use this
option to enable "greedy" replacement::
 
tren -g -r p:P pop.txp # Renames file to: PoP.txP
 
-h Print help information.
 
 
-l string File "extension" delimiter string.
(*Default*: ".")
 
**tren** has to know what separates the "name" from the
"extension" in a filename. By default, it uses the
rightmost ``.`` character. You can change it with this
option to "divide" the filename into name and extension
for renaming purposes, using any string you like. This
is particularly helpful with ``-b`` and ``-e`` options::
 
tren -b -l .long.txt -r long:short long.long.txt.long.txt.foo
 
This would rename the file to::
 
short.short.txt.long.txt.foo
 
Notice that **tren** looks for the *rightmost* instance
of the separator to split the whole filename into name
and extension components. Notice also that when you do
this, no renaming of characters *within* the separator
takes place.
 
-m template Rename by template. (*Default*: Rename via string replacement.)
 
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
 
 
-q Quiet mode, do not show progress.
(*Default*: Display progress)
 
 
-r <old=new> Replace "oldstring" with "newstring" in filenames.
Ordinarily, **tren** displays what it is doing as it
processes each file. If you prefer to not see this
"noisy" output, use the ``-q`` option. Note that this
does not suppress warning and error messages.
 
This option is ignored when running in test mode (``-t``).
 
 
-r <old=new> Replace "oldstring" with "newstring" in file names.
 
Use this option to specify which strings you
want to replace in each file name. These strings
are treated literally unless you also invoke
the ``-x`` option.
 
You can have multiple instances of this option on
your **tren** command line::
 
tren -e old:new -e txt:doc old-old.txt
 
This renames the file to::
 
new-old.doc
By default, **tren** only replaces the first
(leftmost) instance of the old string with the new.
This option's behavior is modified by the ``-b``,
``-c``, ``-e``, ``g``, ``l``, and ``x`` options.
 
 
-t Test mode, don't rename, just show what the program *would* do
(ignores -q).
 
**tren** is very powerful and capable of doing nasty things to
your files (like making a file disappear when another one is
renamed over it). For this reason, it is helpful to test
your **tren** commands before actually using them. With this
option enabled, **tren** will print out diagnostic information
about what your command *would* do, *without actually doing it*.
 
 
-v Print detailed program version information and exit.
 
-w Turn off warnings about potentially overwriting existing
files or directories.
(*Default*: Warn if target exists.)
 
By default, **tren** warns you if you're about to rename a
file/directory with a name of a file/directory that already
exists. No renaming takes place in that case. You can
suppress this behavior with the ``-w`` option. In that
case **tren** will attempt to do the renaming without
warning you. If it cannot - for example, if your
proposed renaming would remove a non-empty directory -
**tron** will print a message to that effect even with this
option selected.
 
-x Treat the old string in a ``-r`` replacement as a Python
style regular expression for matching purposes.
(*Default*: Treat the old string as literal text)
 
String substitution arguments to the ``-r`` option are usually
understood to be taken literally. There are, however, instances
where this is tedius to do. Say you have a set of files
that are similar, but not idential in name, and you want to
rename them all::
 
sbbs-1.txt
sbbbs-2.txt
sbbbbbbbbs-3.txt
 
Suppose you want to rename them, replacing two or more instances
of ``b`` with ``X``. It is tedious to have to write a separate
``-r old:new`` string substitution for each instance above.
This is where regular expressions can come in handy. When you
invoke the ``-x`` option, **tren** understands this to mean that
the ``old`` portion of the replacement option is to be treated as
a *Python style regular expression*. That way, a single string
can be used to match many cases::
 
tren -x -r bb+:X *.txt
 
This renames the files to::
 
sXs-1.txt
sXs-2.txt
sXs-3.txt
 
.. WARNING:: Be VERY Careful with this option. It's very easy
to write regular expressions that collapse all
existing file names to a single new name. If you
do this with the ``-w`` option selected, you're
likely going to end up clobbering files you never
meant to.
 
**tron** only accepts Python style regular expressions. Anything
else will cause an error message to be displayed.
 
 
TEMPLATE CONSTRUCTION
---------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.108 2010/01/15 18:47:47 tundra Exp $
$Id: tren.rst,v 1.109 2010/01/15 20:51:44 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren