diff --git a/tren.rst b/tren.rst index be77a9e..24c4da5 100644 --- a/tren.rst +++ b/tren.rst @@ -41,8 +41,8 @@ tren.py [-aCcdfhqtvXx] [-A alphabet] [-I file] [-i range] [-P esc] [-R sep] [-r old=new] [-S suffix] [-w width] file|dir ... -OPTIONS -------- +SPECIFYING OPTIONS +------------------ You may specify *tren* options in one of three ways: @@ -62,54 +62,48 @@ tren.py -opt -opt -opt -- -this_file_starts_with_a_dash -This allows you to rename different files and directories with -different options. *However*, keep in mind that all the options to -the left of the file or directory being renamed are in force. That -is, options are *cumulative*. In the example above, the rightmost -files and directory would be renamed with all the options 1-6 in -force. This is why there are "toggles" in the options below - they -allow you to selectively turn features on- and off as you move to the -right on the command line. - -1 Rename only the first instance of the specified string +Some options below are "global" - they change the state of the entire +program permanently and cannot be undone by subsequent options. Some +options are "toggles", they can be turned on- and off as you move from +left- to right on the command line. In this way, certain options +(like case sensitivity, regular expression handling, and so on) can be +set differently for each individual renaming request (``-r``). (If +you're very brave, you can select the ``-d`` option to do a debug +dump. Among many other things, the **tren** debugger dumps the state +of each renaming request, and what options are in effect for that +request.) - (*Default*: This is the program default) - This option is provided so you can toggle the program back to - its default behavior after a previous ``-g`` on the command - line. +OPTIONS +======= - This option is ignored during regular expression processing - (``-x``). + -A alphabet Install a user-defined "alphabet" to be used by + Sequence Renaming Tokens. The alphabet is + specified in the form:: - -a Rename within the entire file or directory name + name:characterset - (*Default*: This is the program default) + Both the name and the characterset are case- and + whitespace-sensitive (if your shell permits passing + spaces on the command line). The "0th" element + of the alphabet is the leftmost character. The + counting base is the length of ``characterset``. + So, for instance, the following alphabet is + named ``Foo``, counts in base 5 in the + sequence, ``a, b, c, d, e, ba, bb, ...``:: + + -A Foo:abcde + + -a Ask interactively before renaming each selected file or + directory. + + (*Default*: off) This option is provided so you can toggle the program back to its default behavior after a previous ``-b`` or ``-e`` on the command line. - -b Only perform renaming within "name" portion of file - or directory name. - - (*Default*: Rename 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 renaming - in the entire filename *including* the extension. For example - doing this:: - - tren.py -g -r e=u peg.jpeg # -g = "rename all" - - 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 -g -b -r e=u peg.jpeg # Renames file to pug.jpeg - -C Do case-sensitive renaming (*Default*: This is the program default) @@ -118,8 +112,8 @@ its default behavior after a previous ``-c`` on the command line. - This option is ignored during regular expression processing - (``-x``). + This option is observed both for literal and regular + expression-based renaming (``-x``). . -c Collapse case when doing string substitution. @@ -135,8 +129,9 @@ respectively. Notice that the new (replacement) string's case is preserved. - This option is ignored during regular expression processing - (``-x``). + This option is observed both for literal and regular + expression-based renaming (``-x``). + -d Dump debugging information @@ -145,42 +140,20 @@ Dumps all manner of information about **tren** internals - of interest only to program developers and maintainers. - -E Continue renaming even after an error is encountered - - (*Default*: Stop processing after any error) - - -e Only perform renaming within "extension" portion of - or 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 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 - -f Force renaming even if target file or directory name already exists. - (*Default*: Skip renaming if a file or directory already - exists by the same name as the target.) + (*Default*: Skip renaming if a file or directory already + exists by the same name as the target.) - -g Replace all instances (global rename) 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 - *all* instances of a particular string replaced, use this - option to enable "global" renaming:: - - tren.py -g -r p:P pop.txp # Renames file to: PoP.txP - - This option is ignored during regular expression processing - (``-x``). + By default, **tren** will not rename something to a name that + is already in use by another file or directory. This option + forces the renaming to take place. However, the old file or + directory is not lost. It is merely renamed itself first, by + appending a suffix to the original file name. (*Default*: + .backup, but you can change it via the ``-S`` option.) This + way even forced renames don't clobber existing files or + directories. -h Print help information. @@ -192,7 +165,7 @@ line. However, this can make the command line very long and hard to read. This is especially true if the renaming strings are complex, contain regular expressions or renaming - templates, or if you make heavy use of command line toggles. + tokens, or if you make heavy use of command line toggles. The ``-I`` option allows you to place any command line arguments in a separate *file* in place of- or in addition to @@ -210,10 +183,9 @@ # Each line appended sequentially # to the command line - -r t[ext]+=txt # Appended first - -c -g my=Mine + -xr t[ext]+=txt # Appended first -X - -r =/L/ -r foo=bar + -r =/MYEAR/ -r foo=bar my.file your.file # Appended last @@ -224,40 +196,46 @@ do this. Suppose file ``z`` tried to include file ``x`` in this example? You'd be specifying an infinite inclusion loop. To avoid this, **tren** limits the total number of inclusions - to 50. If you exceed this, you'll get an error message and the - program will terminate. + to 1000. If you exceed this, you'll get an error message and + the program will terminate. - .. NOTE:: There is one important difference between an actual - command line and keeping the arguments in a file like - this. *Filename wildcards are not expanded within the - file.* ``*.txt`` will typically be expanded by a command - shell to create a list of files ending in ``.txt``. - However, the ``*`` metacharacter has no such meaning when - used inside an arguments file. + .. NOTE:: Wilcard metacharcters like ``*`` and ``?`` that are + embedded in filenames included this way *are* expanded as + they would be from the command shell. - -l string File "extension" delimiter string. + -i num|range Specifies which "instances" of matching strings should + be replaced. (*Default*: 0 or leftmost) - (*Default*: ".") + An existing file may have multiple instances of the + "old" renaming string in it. The ``-i`` option lets + you specify which of these (one, several, all) you'd + like to have replaced. - **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:: + Suppose you have a file called + ``foo1-foo2-foo3.foo4``. The leftmost ``foo`` is + instance 0. The rightmost ``foo`` is instance 3. + You can also refer to instances relative to the + right. So the -1 instance is the last (rightmost), + -2, second from the last, and so forth. - tren.py -g -b -l .long.txt -r long:short long.long.txt.long.txt.foo + A "range" of instances is specified + using the ``:`` separator in the form:: - This would rename the file to:: + -i first-to-replace:stop-here - short.short.txt.long.txt.foo + All instances from the first-to-replace + up to, *but NOT including* the stop-here + are replaced. ``-i :`` means "replace + *all* instances. - 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. + Examples:: + tren.py -i 1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-foo3.foo4 + tren.py -i -1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-foo2-foo3.bar4 + tren.py -i 1:3 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-bar3.foo4 + tren.py -i -4:-2 -r foo=bar foo1-foo2-foo3.foo4 -> bar1-bar2-foo3.foo4 + tren.py -i : -r foo=bar foo1-foo2-foo3.foo4 -> bar-bar2-foo3.bar4 + -q Quiet mode, do not show progress. (*Default*: Display progress) @@ -656,7 +634,7 @@ that if ``-x`` is selected the *entire* ``old`` string is treated as a Python regular expression. Pay particular attention to this if you're combing literal text and/or - renaming templates with regular expression metacharacters. + renaming tokens with regular expression metacharacters. - When all the renaming operations are complete - and thus a new filename has been constructed - **tren** checks to see if a file or directory @@ -1081,7 +1059,7 @@ ------------------------ You must be running Python 2.6.x or later. **tren** makes use of -features not supported in released prior to this. +features not supported in releases prior to this. As a general matter, **tren** should run on any POSIX-compliant OS that has this version (or later) of Python on it. It will also run on @@ -1130,7 +1108,7 @@ :: - $Id: tren.rst,v 1.137 2010/03/19 17:19:14 tundra Exp $ + $Id: tren.rst,v 1.138 2010/03/19 18:47:17 tundra Exp $ You can find the latest version of this program at: