diff --git a/tren.rst b/tren.rst index 399c543..c865576 100644 --- a/tren.rst +++ b/tren.rst @@ -242,7 +242,7 @@ be replaced. (*Default*: 0 or leftmost) - A file may have multiple instances of the "old" + A 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. @@ -657,20 +657,61 @@ 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 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`` +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`` + +You can omit either ``old`` or ``new`` strings in a renaming +specification, but never both. + +If you omit the ``old`` string, you're telling **tren** to *change the +whole file name*:: + + tren.py -r =MyNewFilename foo # New Name: MyNewFilename + +Be careful with this one. If you apply it to a list of files or +directories, it's going to try and name them all to the *same* name. +By default, **tren** will refuse to overwrite an existing filename, so +it will stop you from doing this. If you absolutely insist on this +via the ``-f`` option, you'll get a bunch of files ending with +``.backup``. Say you have files ``a``, ``b``, and ``c``:: + + tren.py -fr =NewName a b c + +When the command completes, the files will have been renamed +in this fashion:: + + a -> NewName.backup.backup + b -> NewName.backup + c -> NewName + +If you omit the ``new`` string, you're telling **tren** to *remove* +the leftmost instance of ``old`` string (or other instances via the +``-i`` option described below) from the file- or directory name. For +example:: + + tren.py -rfoo= foo1-foo2-foo3.foo4 # New name: 1-foo2-foo3.foo4 + +If you try to omit *both* ``old`` and ``new`` strings, you're +effectively telling **tren** to change the existing file name to +... nothing (a null string). This is impossible because file names +must be at least one character long. **tren** enforces both this +minimum length AND the maximum legal length of new file names. It +will print an error and exit if your renaming attempt would violate +either of these limits. (As of this writing, the maximum file- or +directory name length allowed by the operating systems on which +**tren** runs is 255 characters.) Substitution Instances ====================== -As we just saw above, sometimes the "old" string appears in several +As we just saw above, sometimes the ``old`` string appears in several places in a file- or directory name. By default, **tren** only -replaces the first, or leftmost "instance" of an "old" string. +replaces the first, or leftmost "instance" of an ``old`` string. However, using the ``-i`` option you can specify *any* instance you'd like to replace. In fact, you can even specify a *range* of instances to replace. @@ -694,8 +735,7 @@ ``foo``, and also instance -1. -You can specify a *single instance* (other than the default leftmost) -to replace:: +You can specify a *single instance* to replace:: tren.py -i 1 -r f=b foo1-foo2-foo3.foo4 # New name: foo1-boo2-foo3.foo4 @@ -726,7 +766,7 @@ Note that you cannot specify individual, non-adjacent instances. There is no way to use a single **tren** command to replace, say, the -only the 2nd and the 4th instance of an "old" string. Doing that +only the 2nd and the 4th instance of an ``old`` string. Doing that requires two renaming requests. The good news is that we can do them both on a single **tren** invocation. @@ -735,8 +775,8 @@ ====================== You can put as many renaming requests on a **tren** command line as -you like .... well, up to the length limit imposed by your operating -system and shell, anyway. As we just saw, this can be handy when +you like (.... well, up to the length limit imposed by your operating +system and shell, anyway). As we just saw, this can be handy when a single renaming request can't quite do everything we want. BUT ... there's a catch. In designing your renaming requests, @@ -747,13 +787,13 @@ tren.py -r foo=bar -r foo=baz foo1-foo2-foo3.foo4 Produces ... wait a second ... why on earth are there two renaming -requests with idential "old" strings on the same command line? +requests with idential ``old`` strings on the same command line? Shouldn't this produce a final name of ``baz1-foo2-foo3.foo4``? Nope. After the leftmost renaming request has been processed, the new name is ``bar1-foo2-foo3.foo4``. Remember that, by default, **tren** only replaces the *leftmost* or 0th instance -of an "old" string. So, when the second renaming request is +of an ``old`` string. So, when the second renaming request is processed, the instance 0 of ``foo`` is now found in the string ``foo2``. So, the final name will be, ``bar1-baz2-foo3.foo4``. @@ -821,7 +861,8 @@ 3) Build a table of every file name to be renamed. We'll need this information if any of the renaming requests use - renaming tokens. + the file- or sequence renaming tokens (discussed later in this + document). 4) Build a table containg each renaming request storing the current state of every program option at that point on the command line. @@ -1629,7 +1670,7 @@ :: - $Id: tren.rst,v 1.152 2010/03/26 01:42:13 tundra Exp $ + $Id: tren.rst,v 1.153 2010/03/26 19:46:33 tundra Exp $ You can find the latest version of this program at: