diff --git a/tren.rst b/tren.rst index a25f442..675f151 100644 --- a/tren.rst +++ b/tren.rst @@ -409,11 +409,36 @@ with the '``-t``' option) to see what would happen. You have been warned! +Overview +======== + **tren** is a general purpose file and directory renaming tool. Unlike commands like '``mv``', **tren** is particularly well suited for renaming *batches* of files and/or directories with a single command line invocation. **tren** eliminates the tedium of having to script -simpler tools to provide higher-level renaming capabilities. +simpler tools to provide higher-level renaming capabilities. + +**tren** is also adept at renaming only *part of an existing file +or directory name* either based on a literal string or a regular +expression pattern. You can replace any single, group, or all +instances of a given string in a file or directory name. + +**tren** implements the idea of a "Renaming Token" which is +a symbolic variable that is resolved at runtime to create a new +file name. Renaming Tokens allow you to embed information about +the file's time or length, the contents of an environment variable, +and even the output of an arbitrary command line program into the new +name of a file. + +**tren** can automatically generate *sequences* of file names based on +their dates, lengths, times within a given date, and so on. In fact, +sequences can be generated on the basis of any of the file's +'``stat``' information. Sequence "numbers" can be ascending or +descending and the count can start at any initial value. Counting can +take place in one of several internally defined counting "alphabets" +(decimal, hex, octal, alpha, etc.) OR you can define your own counting +alphabet. This allows you to create sequences in any base (2 or +higher please :) using any symbol set for the count. **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 @@ -462,16 +487,22 @@ tren.py -r .Jpeg=.jpg *.Jpeg This would rename all files (or directories) whose names contained the -string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's not -quite right. Unless you specify the '``-g``' option, *only the first -(leftmost) instance of '``old``' is replaced with '``new``'*. +string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's +not quite right. Unless you specify otherwise with the '``-i``' +option, *only the first (leftmost) instance of '``old``' is replaced +with '``new``'*. So, for example, if you started out with the file, +'``My.Jpeg.Jpeg``' and ran the command above, you'd end up with a +new file name of '``My.jpg.Jpeg``' -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). You can limit the replacement to just the -"name" ('``-b``') or "extension" ('``-e``') portions of the filename. -You may specify multiple replacement operations ('``-r``') on the **tren** +Substitution Instances +====================== + + +Multiple Substitutions +====================== + +You may specify multiple '``-r``' replacement operations on the **tren** command line:: tren.py -g -r .Jpeg=.jpg -r old=ReallyOld * @@ -487,6 +518,59 @@ This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'. +Forcing Renaming +================ + +Ignoring Case +============= + +The Strange Case Of Mac OS X And Windows +======================================== + +Mac OS X and Windows have an "interesting" property that makes case +handling a bit tricky. Both of these operating systems *preserve* +case in file and directory names, but they do not *observe* it. (It +is possible to change this behavior in OS X when you first prepare a +drive, and make the filesystem case sensitive. This is rarely done in +practice, however.) + +These OSs show upper- and lower- case in file names as you request, +but they do not *distinguish* names on the basis of case. For +instance, the files '``Foo``', `''foo``', and '``FOO``', are all the +same name in these operating systems, and only one of these can exist +in a given directory. This can cause **tren** to do the unexpected +when your renaming command is doing nothing more than changing case. +Suppose you start with a file called '``Aa.txt``' and run this +command:: + + tren.py -rA=a Aa.txt + +**tren** will immediately complain and tell you that the file +'``aa.txt``' already exists and it is skipping the renaming. Why? +Because from the point-of-view of OS X or Windows, '``aa.txt``' (your +new file name) is the same as '``Aa.txt``' (your original file name). +you attempt to force the renaming:: + + tren.py -frA=a Aa.txt + +Guess what happens? Since **tren** thinks the new file name already +exists, it backs it up to '``aa.txt.backup``'. But now, when it goes +to rename the original file ... the file is *gone* (thanks to the +backup renaming operation)! **tren** declares an error and +terminates. + +This is not a limitation of **tren** but a consequence of a silly +design decision in these two operating systems. As a practical +matter, the way to avoid this issue is to never do a renaming +operation in OS X or Windows *that only converts case*. Try +to include some other change to the filename to keep the +distinction between "old name" and "new name" clear to the +OS. In the worst case, you'll have to resort to something like:: + + tren.py -rA=X Aa.txt + tren.py -rX=a Xa.txt + + Using Regular Expressions ------------------------- @@ -1208,7 +1292,7 @@ :: - $Id: tren.rst,v 1.141 2010/03/23 20:19:17 tundra Exp $ + $Id: tren.rst,v 1.142 2010/03/23 21:01:12 tundra Exp $ You can find the latest version of this program at: