diff --git a/tren.rst b/tren.rst index 0b78ca0..fb22a59 100644 --- a/tren.rst +++ b/tren.rst @@ -8,12 +8,12 @@ ------------------------ **tren** is a powerful command line file/directory renaming tool. It -implements multiple, sophisticated renaming features than can be a bit +implements a variety of sophisticated renaming features than can be a bit complex to learn. For this reason, this document is split into two general sections: `REFERENCE`_ and `TUTORIAL AND DESCRIPTION`_. If you are new to **tren**, start by studying the latter section first. -It will take you from very simple- to the most complex renaming -operations the program supports. Once you've got a sense of what +It will take you from very simple- to highly complex **tren** renaming +operations. Once you've got a sense of what **tren** can do, the reference section will be handy to look up options and their arguments. @@ -56,9 +56,9 @@ options". All options must precede the list of files and/or directories being -renamed. If one of your rename targets start with the '``-``' character, -most command shells recognines the double dash as an explicit -"end of options" delimiter:: +renamed. If one of your rename targets start with the '``-``' +character, most command shells recognize the double dash as an +explicit "end of options" delimiter:: tren.py -opt -opt -opt -- -this_file_starts_with_a_dash @@ -79,8 +79,11 @@ ======= -A alphabet Install a user-defined "alphabet" to be used by - Sequence Renaming Tokens. The alphabet is - specified in the form:: + Sequence Renaming Tokens. + + (*Default*: Built-in alphabets only) + + The alphabet is specified in the form:: name:characterset @@ -100,9 +103,18 @@ (*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. + If you invoke this option, **tren** will prompt you before + renaming each file. The default (if you just hit '``Enter``') + is to *not* rename the file. Otherwise, you have the following + options:: + + n - Don't rename the current file + y - Rename the current file + ! - Rename all the remaining files without further prompting + q - Quit the program + + These options are all insensitive to case. + -C Do case-sensitive renaming @@ -123,7 +135,7 @@ **tren** will ignore the case of the characters found in the filename. For example:: - tren.py -c -r Old:NEW Cold.txt fOlD.txt + tren.py -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 @@ -253,10 +265,15 @@ (*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. + 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. + + It doesn't make much sense to use this option in test mode + ('``-t``'), although you can. The whole point of test mode is + to see what would happen. Using the quiet mode suppresses that + output. -R char Use '``char``' as the separator symbol in renaming @@ -287,7 +304,7 @@ You can have multiple instances of this option on your **tren** command line:: - tren.py -r old:new -r txt:doc old-old.txt + tren.py -r old=new -r txt:doc old-old.txt This renames the file to:: @@ -296,9 +313,9 @@ Remember that, by default, **tren** only replaces the first (leftmost) instance of the old string with the new. - Each rename specifiation on the command line "remembers" - the current state of all the program options and acts - accordingly. For example:: + Each rename specification on the command line + "remembers" the current state of all the program + options and acts accordingly. For example:: tren.py -cr A=bb -Cr B=cc ... @@ -307,17 +324,44 @@ where as the '``B=cc``' request would only replace '``B``'. - -t Test mode, don't rename, just show what the program *would* do - (ignores -q). + -S suffix Suffix to append when making backup copies of existing + targets. + + (*Default*: .backup) + + If you choose to force renaming if files when the new + name already exists ('``-f``'), **tren** simply renames + the existing file or directory by appending a suffix to + it. By default, this suffix is '``.backup``, but you + can change it to any string you like with the '``-S``` + option. + + -t Test mode, don't rename, just show what the program *would* do. **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*. + your file and directory names. 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. + -v Print detailed program version information and keep running. + + This is handy if you're capturing **tren** output into a log + and you want a record of what version of the program was used. + + -w length Set the length of diagnostic and error output. + + (*Default*: 80) + + **tren** limits output to this length when dumping + debug information, errors, warnings, and general + information as it runs. This option is especially + useful when you're capturing **tren** output into + a log and don't want lines wrapped:: + + tren.py -w999 ..... 2>&1 > tren.log + -X Treat the renaming strings literally @@ -441,14 +485,14 @@ Suppose you want to rename them, replacing two or more instances of '``b``' with '``X``'. It is tedious to have to write a separate literal -'``-r old:new``' string substitution for each instance above. This is +'``-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:: @@ -956,7 +1000,7 @@ This produces a sequence from shortest to longest (or the reverse) of the renamed objects. - ``tren.py -r /+L0002/ *.txt`` + ``tren.py -r =/+L0002/ *.txt`` This would rename all the files in the current directory into the form, '``0002.txt``', '``0003.txt``', @@ -1063,7 +1107,7 @@ Rename multiple strings at once:: - tren.py -r log:txt -r New:old New.log # old.txt + tren.py -r log=txt -r New=old New.log # old.txt Rename using regular expressions:: @@ -1139,7 +1183,7 @@ :: - $Id: tren.rst,v 1.139 2010/03/19 20:02:37 tundra Exp $ + $Id: tren.rst,v 1.140 2010/03/23 19:38:51 tundra Exp $ You can find the latest version of this program at: