Wrote section on renaming token/renaming request collisions.

Fork: 0

tundra / tren

Browse code Wrote section on renaming token/renaming request collisions. master
1 parent 2d8a145 commit a0b262138dfcf75fabcfe452bd20a4e4ac0bfd2f tundra authored on 26 Mar 2010

Patch

Unified Split

Showing 1 changed file

                Ignore Space
               Show notes
              View
            
          
          198 ■■■■■
          tren.rst
        This allows **tren** to apply options differently to different
       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.
 
 
 
**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`_.
 
 
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
section below entitled `Renaming Tokens: The Gory Details`_.
 
 
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:
 
  - 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.
 
  - Regular expression processing is unaffected by the ``-g / -1``
    (global rename) and ``-c / -C`` (ignore case) options.
 
  - 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** 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.
 
 
RENAMING TOKENS: THE GORY DETAILS
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::
 
  tren.py -r =New-/FNAME/ -r My=Your MyFile.txt
 
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:: 
 
  tren.py -r My=Your -r =New-/FNAME/ MyFile.txt
 
``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
=================================
 
As we've just seen, a *renaming token* is nothing more than 
a string representing something **tren** knows about.  These
-----------------------------
 
::
 
  $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:
 
  http://www.tundraware.com/Software/tren
        This allows **tren** to apply options differently to different
        renaming requests on the same command line.  This came in handy
        in our example of the previous section.
+) 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.
 ) 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.
 **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`_.
+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
+section below entitled `Renaming Tokens: The Gory Details`_.
+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:
+  - 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.
+  - Regular expression processing is unaffected by the ``-g / -1``
+    (global rename) and ``-c / -C`` (ignore case) options.
+  - 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** processes each renaming string in the following
+    manner:
+) Select the target portion of the filename for
+       renaming (all, name only, extension only).
+) Replace all renaming tokens with their equivalent
+       text in both the ``old`` and ``new`` renaming strings.
+) 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)
+) 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.
+RENAMING TOKENS: THE GORY DETAILS
+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::
+  tren.py -r =New-/FNAME/ -r My=Your MyFile.txt
+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::
+  tren.py -r My=Your -r =New-/FNAME/ MyFile.txt
+``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
 =================================
 As we've just seen, a *renaming token* is nothing more than
 a string representing something **tren** knows about.  These
 -----------------------------
 ::
+  $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:
   http://www.tundraware.com/Software/tren

Show line notes below