diff --git a/tren.rst b/tren.rst index c865576..ca3723d 100644 --- a/tren.rst +++ b/tren.rst @@ -871,6 +871,14 @@ renaming requests on the same command line. This came in handy in our example of the previous section. + 5) Resolve any renaming tokens found in either the ``old`` or + ``new`` portions of the renaming request. + + At this point, both ``old`` and ``new`` are nothing more than + simple strings, although ``old`` may be interpreted as a + regular expression rather than literally if the option to do so + is in effect. + 5) Process each file found on the command line in left to right order, applying each renaming request, in the order it appeared from left to right on the command line. @@ -1168,102 +1176,43 @@ **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`_. +section below entitled `Renaming Tokens: The Gory Details`_. -COMMAND LINE TOGGLES -==================== - -**tren** defaults to a specific set of behaviors: - - - ``old`` and ``new`` renaming text is treated *literally* - - Renaming takes place within *the entire filename* - - *Only the first instance* of ``old`` is replaced with ``new`` - - Renaming is *case sensitive* - -There are command line "switches" to override each of these defaults -(``-x``, ``-b``, ``-e``, ``-g``, and ``-c``). - -There are additional "switches" to return the program to its -default behavior (``-X``, ``-a``, ``-1``, and ``-C``). - -The idea is that you can specify what kind of replacement -behavior you want *for each different renaming operation*. -For instance:: - - tren.py -e -r txt=TXT -g -a -c -r M=0 -C -x -r [ss]+=S filelist - -This would rename the files as follows: - - - The first instance of ``txt`` would be replaced with - ``TXT`` in each of the file extensions. - - - All instances of ``m`` or ``M`` would be replaced - anywhere they were found in the filename. - - - All instances of one or more strings in the form ``ss`` would - be replaced with ``S``. - - -OTHER PROGRAM SEMANTICS +Renaming Token Pitfalls ======================= -It's important to understand some subtleties of just how **tren** -works, particularly if you intend to create complex, multi-replacement -command lines: +As we saw in earlier sections, **tren** command line option and file +name interaction can be tricky. It can depend on order and on whether +the various renaming request "collide" with each other as a new file +name is computed. A similar potential collision exists between +renaming tokens and renaming requests. Recall from `More About +Command Line Pitfalls`_ that renaming tokens are resolved *before* a +renaming request is processed. This means that the string +substitution (literal or regular expression) of the renaming operation +can *conflict with the characters returned when the renaming token was +resolved*. For example, suppose we do this:: - - Command line processing is from left to right. As we saw in the - `COMMAND LINE TOGGLES`_ above, this means the options can be - different for each renaming operating you specify. + tren.py -r =New-/FNAME/ -r My=Your MyFile.txt - - Regular expression processing is unaffected by the ``-g / -1`` - (global rename) and ``-c / -C`` (ignore case) options. +The first renaming request computes the name ``New-MyFile.txt``. +However, the second renaming request further modifies this to +``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:: - - Filenames may be absolute, relative, or implict (to the current - working directory). **tren** keeps track of this and can do - renaming in directories other than the current one. + tren.py -r My=Your -r =New-/FNAME/ MyFile.txt - - **tren** processes each renaming string in the following - manner: - - 1) Select the target portion of the filename for - renaming (all, name only, extension only). - - 2) Replace all renaming tokens with their equivalent - text in both the ``old`` and ``new`` renaming strings. - - 3) If doing literal string replacement: - - - If ``-c`` is in effect, collapse the target and the ``old`` - renaming string to *lower case* before checking for a match. - - - Replace the first- (default and ``-1``) or all (``-g``) - instances of ``old`` with ``new``. 4) - - 4) If doing regular expression processing, replace any regex - matches with the corresponding ``new`` string. Keep in mind - 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 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 - by that name already exists. Unless the ``-f`` flag is in force, - **tren** will refuse to do a renaming *over an existing filename*. - If the new filename does not exist, **tren** will attempt the - renaming. If the rename fails for some reason - say you don't - have permission to rename a particular file or directory - you'll - see an error message to that effect. - - - By default, **tren** will stop processing on any error. You - can override this with the ``-E`` option. In that case, - an error message will be displayed. No matter what caused - the error, **tren** will skip the file currently being processed - and go on to the next one. +``My`` gets replaces with ``Your``, but as soon as the second renaming +request is processed, the whole string is thrown away and replaced +with the final name ``New-MyFile.txt``. -RENAMING TOKENS: THE GORY DETAILS +Renaming Tokens: The Gory Details ================================= As we've just seen, a *renaming token* is nothing more than @@ -1670,7 +1619,7 @@ :: - $Id: tren.rst,v 1.153 2010/03/26 19:46:33 tundra Exp $ + $Id: tren.rst,v 1.154 2010/03/26 20:09:32 tundra Exp $ You can find the latest version of this program at: