diff --git a/tren.rst b/tren.rst index b6401d4..8766f4d 100644 --- a/tren.rst +++ b/tren.rst @@ -1036,7 +1036,7 @@ tren.py -i -1 -c -r.jpeg=.jpg *.jpeg *.Jpeg *.JPEG -Notice that the case-insensitivity only applies to the *matching* of +Notice that the case insensitivity only applies to the *matching* of the ``old`` string. Once **tren** has determined such a match exists, the ``new`` string is used *literally* with case intact. @@ -1155,7 +1155,7 @@ a regular expression, it has to be escaped like this: ``\=``. As with literal string renaming, regular expression renaming requests -honor both the case-sensitivity options (``-C`` and ``-c``) as well +honor both the case sensitivity options (``-C`` and ``-c``) as well as the instance option, ``-i``. So, for example:: tren.py -x -ci -1 -r Bb+=X sbbsbbbsbbbbsbbbbbs @@ -1188,6 +1188,38 @@ Interactive Renaming ==================== +By default, **tren** attempts to perform all the renaming requests on +all the file- and directory names given on the command line +automatically. It is sometimes helpful to work *interactively* +wherein you're asked what to do for each proposed renaming. +Interactive renaming is requested via the ``-a``, "ask" option:: + + tren.py -a -rfoo=Bar foo1.txt foo2.txt foo3.txt + +**tren** will compute each file's proposed new name and ask you +what you want to do. You have 4 possible choices:: + + N, n, or Enter - No, don't rename this file + Y, y - Yes, rename the file + ! - Yes, rename this and all remaining files without asking any more + Q, q - Quit the program + + +There is one slight subtlety here to watch for when doing forced +renaming. As we've seen, if you select the ``-f`` option and the new +file name already exists, **tren** will backup the existing file name +before doing the renaming. In interactive mode, you will be asked +whether or not to proceed with the renaming both for the file in +question *and for any consequenent backups*. If you decline to do the +backup but accept the primary renaming, this will have the same effect +as the ``-b`` option: The existing file- or directory will be +overwritten by the renaming operation. + +If the ``-b`` option is selected in interactive mode, then you'll only +be prompted for the primary file renamings (because ``-b`` suppresses +the creation of backups). + + An Overview Of Renaming Tokens ============================== @@ -1201,36 +1233,46 @@ renaming based on some property the file or directory possesses like its creation date, size, owner's name, and so on. -In their simplest form, renaming tokens are nothing more than -"canned" information **tren** knows about a particular file or -directory. For instance, if you insert the ``/D/`` token into a -old- or new string definition, **tren** will replace it with *the -creation date of the file or directory being renamed* and use that -string in the renaming process. +Renaming tokens are nothing more than special symbols that represent +"canned" information **tren** knows about the file- or directory +being renamed, information from the OS itself, and information used to +sequence or order the files being renamed. -There are also tokens that allow you to use system information in your -renaming strings. Finally, there are tokens that can be used to -automatically renumber or sequence (order) a set of files or -directories being renamed. +For instance, if you insert the ``/MYEAR/`` token into a old- or new +string definition, **tren** will replace it with *the year the file or +directory being renamed was last modified* and use that string in the +renaming process:: -For example, suppose you and your friends pool your vacation photos -but each of your cameras uses a slightly different naming scheme. You -might want to just reorder them by the date and time each picture was -taken, for example. That way you end up with one coherent set of -named and numbered files. You might start with something like this:: + tren.py -ryear=/MYEAR/ My-year.txt # New name: My-2010.txt + +A really handy way to use renaming tokens is to name your files in a +particular *order*. For example, suppose you and your friends pool +your vacation photos but each of your cameras uses a slightly +different naming scheme. You might want to just reorder them by the +date and time each picture was taken, for example. That way you end +up with one coherent set of named and numbered files. You might start +with something like this:: DSC002.jpg # Bob's camera, taken 1-5-2010 at noon dc0234.Jpg # Mary's camera, taken 1-5-2010 at 8am 032344.jpeg # Sid's camera, taken 1-3-2010 at 4pm -It would be nice to get these in order somehow:: +It would be nice to get these in order somehow. We can, by combining +*file* renaming tokens (that know thing about the file being renamed) +and *sequence* renaming tokens (that know how to order all the files +being renamed by some key like date, length, who owns it, and so on):: - tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp* + tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp* + +Every place you see something in the form ``/.../``, think, "That is a +renaming token whose value will be filled in by **tren**." This +syntax is the same whether you're using a *file*-, *system*-, or +*sequence* renaming token. This would rename all the files in the current directory ending with -``.jp*``. The ``/D/`` would be replaced with the *date* the picture -was taken. The ``/+T0001/`` refers to a *starting sequence number* to -uniquely identify pictures taken on the same date. The other strings, +``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the picture +was taken. The ``/+MDATE::0001/`` refers to a *starting sequence number* to +uniquely identify files modified on the same date. The other strings, ``-MyVacation-`` and ``.jpeg``, are inserted *literally* in the final file names. After we ran this command, the files above would end up with these names:: @@ -1240,63 +1282,75 @@ 20100105-MyVacation-0002.jpeg # Bob's Notice that the files taken on the same date have been sequenced by -the time-of-day they were taken because we included the ``/+T0001/`` -renaming token in our pattern. The ``+`` here means to construct -the sequence in *ascending* order. A ``-`` would specify -*descending* order. +the time-of-day they were taken because we included the +``/+MDATE.../`` sequence renaming token in our pattern. The ``+`` +here means to construct the sequence in *ascending* order. A ``-`` +would specify *descending* order. .. Note:: Notice that there is *no old string* in our example above. That is, there is nothing to the left of the ``=`` symbol in the ``-r`` option. This effectively means "replace - everything" in the existing file or directory name. You can - do the same thing using a regular expression:: - - tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp* - - Of course, if you use the ``-b`` or ``-e`` flags, you limit - just what portion of the filename is considered - "everything". + everything" in the existing file or directory name. Of course, you don't *have* to replace the entire filename when using tokens. It's perfectly legitimate to replace only a portion of the existing name:: - tren.py -r file=/D/-file file-1 file.2 + tren.py -r file=/MYEAR/MMON//MDAY/-file file-1 file.2 -This would rename our files to: ``20100101-file-1 and -20100101-file.2`` Notice that we combined literal text and a renaming +This would rename our files to: ``20100101-file-1`` and +``20100101-file.2`` Notice that we combined literal text and a renaming token to do this. You can even use renaming tokens in your *old string* specification. For instance, suppose you manage a number of different systems and you -set their system name in an environment variable called SYSNAME. You -might then do something like this:: +set their system name in an environment variable called ``SYSNAME`` and +this same name is used to identify backup files. You might then do +something like this:: - tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old + tren.py -xr '/$SYSNAME/.*.bku=/FNAME/.old' * If your system name was "matrix", then the command above would only rename files whose names began with ``matrix`` and ended with ``.bku``. If your system name were "morton", then the command above would only rename files whose names began with ``morton`` and ended with ``.bku``. -There are a couple of things to keep in mind when doing things like +Notice that we combined a reference to an environment variable within +a regular expression. This was done to do the match on "names +beginning with... and ending with ...". Also notice that the renaming +token ``/FNAME/`` is just the *original name of the file*. + +In order for this to work, we had to single quote the renaming +request. This is because Unix shells will themselves try to replace +``$SYSNAME`` which is not what we want. If we don't single quote +(thereby turning off shell variable interpolation) and run this, say, +on a machine called "matrix", the command will be handed to **tren** +looking like this:: + + tren.py -xr /matrix/.*.bku=/FNAME/.old' * + +**tren** will then promptly error out and tell you that it doesn't +know about a renaming token called ``/matrix/``. + +There are a several things to keep in mind when doing things like this: - 1) The ``/$SYSNAME/`` in the old string is used to *find the text to - rename*, whereas the same renaming token in the new string means - *insert the contents of that environment variable here*. + 1) The ``/$SYSNAME/`` in the ``old`` string is used to *find the + text to rename*, whereas the same renaming token in the ``new`` + string means *insert the contents of that environment variable + here*. 2) Renaming tokens are always evaluated *before* any regular expression processing takes place. It's up to you to make sure that when the two are combined (as we have in the example above), *that the final result is still a valid Python regular expression*. This may involve explicit quoting of the renaming - tokens used in the old string specification. + tokens used in the ``old`` string specification. -**tren** has many other kinds of renaming tokens. Their -structure and use is described in some detail in the -section below entitled `Renaming Tokens: The Gory Details`_. +**tren** has many other kinds of renaming tokens. Their structure and +use is described in some detail in the section below entitled +`Renaming Tokens: The Gory Details`_. Renaming Token Pitfalls @@ -1320,10 +1374,10 @@ ``New-YourFile.txt``. In effect, the second renaming request is *overwriting part of the string produced by the renaming token reference*. This is an intentional feature of **tren** to allow -maximum renaming flexibility. However, you need to understand -how it works so you don't get unexpected and strange results. -For example, look what happens when you reverse the order -of the renaming requests in this case:: +maximum renaming flexibility. However, you need to understand how it +works so you don't get unexpected and strange results. For example, +look what happens when you reverse the order of the renaming requests +in this case:: tren.py -r My=Your -r =New-/FNAME/ MyFile.txt @@ -1740,7 +1794,7 @@ :: - $Id: tren.rst,v 1.158 2010/03/29 16:15:00 tundra Exp $ + $Id: tren.rst,v 1.159 2010/03/29 17:40:19 tundra Exp $ You can find the latest version of this program at: