diff --git a/tren.rst b/tren.rst index 6dca419..dd2bf52 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - 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 @@ -43,7 +43,7 @@ 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 @@ -118,33 +118,128 @@ 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) + 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. - -r Replace "oldstring" with "newstring" in filenames. + This option is ignored when running in test mode (``-t``). + + + -r 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. @@ -152,10 +247,57 @@ 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 --------------------- @@ -199,7 +341,7 @@ :: - $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: