Fork: 0
tundra / tren
Browse code
Added -a and -p options.
Started filling in the TEMPLATE CONSTRUCTION and EXAMPLES sections.
master
1 parent 1ed1f5f commit 05a313be8dbc6fc4366a07f485825ebfa8f7cec5
@tundra tundra authored on 16 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
130
■■■■■
 tren.rst
--------
 
::
 
tren.py [-cbeghqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ...
tren.py [-acbeghpqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ...
 
 
DESCRIPTION
-----------
renaming *batches* of files and/or directories with a single command
line invocation. **tren** eliminates the tedium of having to script
simpler tools to provide higher-level renaming capabilities.
 
**tren** will not allow you to rename a file/directory if a
file/directory with the new name already exists. Such attempts will
cause no change to the file/directory being processed and a warning
message will be displayed. This is intentional to force you to
manually rename or remove the directory that would have been clobbered
by a rename.
**tren** will not allow you to rename a file or directory if one with
the new name already exists. Such attempts will cause no change to the
file or directory being processed and a warning message will be
displayed. This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename.
 
**tren** supports two kinds of renaming operations, *String Substitution*
and *Rename By Template*.
 
There are many other renaming tokens and ways to construct
all manner of clever templates. These are discussed below in the
section entitled `TEMPLATE CONSTRUCTION`_.
 
Ordinarily the template text *replaces* the *entire* existing
filename. You can limit the replacement to either the "name" (``-b``)
or "extension" (``-e``) portions of the filename. Instead of
replacing the existing name, extension, or both, you can also choose
to append (``-a``) or prepend ``-p`` the template text.
 
 
OPTIONS
-------
 
 
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
 
-b Only perform string substitution within "name" portion of
-a Append the template text to the existing file or directory
name.
 
(*Default*: Replace the file or directory name with the
template text.)
 
 
-b Only perform renaming within "name" portion of file
or directory name.
 
(*Default*: Substitute within the entire file/directory name)
(*Default*: Substitute within the entire file or 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::
contents or type of file. By default, **tren** does renaming
in the entire filename *including* the extension. For example
doing this::
 
tren.py -r eg=ug peg.jpeg
 
Renames the file to ``pug.jpug`` .. probably not what you want.
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
 
-e Only perform string substitution within "extension" portion of
-e Only perform renaming within "extension" portion of
or directory name.
 
(*Default*: Substitute within the entire file/directory name)
(*Default*: Substitute within the entire file or directory name)
 
This option is the inverse of ``-b``. It instructs **tren**
to do the requested subsitution *only* in the filename
to do the requested renaming *only* in the filename
"extension" not on the file name portion. For example::
 
tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg
 
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.
 
-p Prepend the template text to the existing file or directory
name.
 
(*Default*: Replace the file or directory name with the
template text.)
 
 
-q Quiet mode, do not show progress.
 
(*Default*: Display progress)
 
TEMPLATE CONSTRUCTION
---------------------
 
Template based renaming is used when you want to impose a naming
"pattern" on a group of files or directories. This is most useful
when the existing filenames have little or nothing in common. In such
situations, there's often no direct way to use string substitutions to
order the names in some coherent way.
 
A "template" is built from literal text and *renaming tokens*.
 
 
EXAMPLES
--------
 
Here are some common examples of **tren** in action:
 
 
Simple rename::
 
tren.py
 
Change file "name"::
 
tren.py
 
Change file "extension"::
 
tren.py
 
Rename all instances of a given string::
 
tren.py
 
Rename, ignoring case::
 
tren.py
 
Rename multiple strings at once::
 
tren.py
 
Rename using regular expressions::
 
tren.py
 
Use template::
 
tren.py
 
Use template to change file "name"::
 
tren.py
 
Use template to change file "extension"::
 
tren.py
 
Append template text::
 
tren.py
 
Prepend template text::
 
tren.py
 
Get help::
 
tren.py -h
 
Print out detailed version information::
 
tren.py -v
 
 
OTHER
-----
 
You must have a reasonably current version of Python installed.
 
 
BUGS AND MISFEATURES
--------------------
 
None known as of this release.
 
 
COPYRIGHT AND LICENSING
-----------------------
 
program distribution. If you install **tren** on a FreeBSD
system using the 'ports' mechanism, you will also find this file in
``/usr/local/share/doc/tren``.
 
 
AUTHOR
------
 
::
Tim Daneliuk
tren@tundraware.com
 
 
 
DOCUMENT REVISION INFORMATION
-----------------------------
 
::
 
$Id: tren.rst,v 1.113 2010/01/16 15:38:10 tundra Exp $
$Id: tren.rst,v 1.114 2010/01/16 16:11:40 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren