diff --git a/tren.rst b/tren.rst index edf07df..3cb7a27 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - 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 @@ -25,12 +25,12 @@ 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*. @@ -116,6 +116,12 @@ 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 ------- @@ -127,15 +133,22 @@ 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 @@ -161,13 +174,13 @@ 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 @@ -211,6 +224,13 @@ 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) @@ -298,21 +318,90 @@ 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 ----------------------- @@ -323,6 +412,7 @@ system using the 'ports' mechanism, you will also find this file in ``/usr/local/share/doc/tren``. + AUTHOR ------ @@ -332,12 +422,13 @@ 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: