diff --git a/tren.rst b/tren.rst index 4f390c6..edf07df 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - tren.py [-cbeghqtvx] [-l string] [-m template] [-r old=new]... file|dir file|dir ... + tren.py [-cbeghqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ... DESCRIPTION @@ -48,7 +48,9 @@ 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 file name, not just at -the end or "extension" (as it is called in Windows). +the end or "extension" (as it is called in Windows). You can limit +the replacement to just the "name" (``-b``) or "extension" (``-e``) +portions of the filename. 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 @@ -92,11 +94,11 @@ construction and the use of renaming tokens, but here's a simple example to illustrate the general idea using the files above:: - tren.py -m -MyVacation-<0001>.jpeg *.jp* + tren.py -T /D/-MyVacation-/0001/.jpeg *.jp* This would rename all the files in the current directory ending with -``.jp*``. The ```` would be replaced with the *date* the picture -was taken. The ``<0001>`` refers to a *starting sequence number* to +``.jp*``. The ``/D/`` would be replaced with the *date* the picture +was taken. The ``/0001/`` refers to a *starting sequence number* to uniquely identify pictures taken on the same date. The other strings in the template, ``-MyVacation-`` and ``.jpeg``, are inserted *literally* in the final file names. After we ran this command, the @@ -107,7 +109,7 @@ 20100105-MyVacation-0002.jpeg (Bob's) Notice that the files taken on the same date have been sequenced by -the time-of-day they were taken because we included the "<0001>" +the time-of-day they were taken because we included the ``/0001/`` renaming token in our pattern. There are many other renaming tokens and ways to construct @@ -118,27 +120,37 @@ OPTIONS ------- - -b Exclude file/directory "extension" when doing string - substitution. - (*Default*: Substitute within the entire file/directory name) + -T template Rename by template. - 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:: + (*Default*: Rename via string replacement.) - tren.py -r eg=ug peg.jpeg + Use a template to rename the file. This is discussed in + detail in the `TEMPLATE CONSTRUCTION`_ section below. - Renames the file to ``pug.jpug`` .. probably not what you want. + -b Only perform string substitution within "name" portion of + or directory name. - The ``-b`` option tells **tren** to only perform string renaming - in the actual "name portion" of the filename thereby - cirumventing problems like this:: + (*Default*: Substitute within the entire file/directory name) - tren.py -b -r eg=ug peg.jpeg # Renames file to pug.jpeg + 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.py -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.py -b -r eg=ug peg.jpeg # Renames file to pug.jpeg -c Collapse case when doing string substitution. + (*Default*: Search for string to replace is case sensitive.) + 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:: @@ -149,8 +161,10 @@ 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) + -e Only perform string substitution within "extension" portion of + or directory name. + + (*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 @@ -161,6 +175,8 @@ -g Replace all instances (greedy replace) of the old string with the new. + (*Default*: Only the first matching string is replaced.) + 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 @@ -173,7 +189,8 @@ -l string File "extension" delimiter string. - (*Default*: ".") + + (*Default*: ".") **tren** has to know what separates the "name" from the "extension" in a filename. By default, it uses the @@ -194,14 +211,9 @@ 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) + + (*Default*: Display progress) Ordinarily, **tren** displays what it is doing as it processes each file. If you prefer to not see this @@ -247,39 +259,40 @@ -v Print detailed program version information and exit. - -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) + -x Treat the old string in a ``-r`` replacement as a Python + style regular expression for matching purposes. - 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:: + (*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:: + 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.py -x -r bb+:X *.txt - tren.py -x -r bb+:X *.txt + This renames the files to:: - This renames the files to:: + sXs-1.txt + sXs-2.txt + sXs-3.txt - sXs-1.txt - sXs-2.txt - sXs-3.txt - - **tren** only accepts Python style regular expressions. Anything - else will cause an error message to be displayed. + **tren** only accepts Python style regular expressions. Anything + else will cause an error message to be displayed. TEMPLATE CONSTRUCTION @@ -324,7 +337,7 @@ :: - $Id: tren.rst,v 1.112 2010/01/16 00:04:27 tundra Exp $ + $Id: tren.rst,v 1.113 2010/01/16 15:38:10 tundra Exp $ You can find the latest version of this program at: