diff --git a/tren.rst b/tren.rst index 6788827..811eaa9 100644 --- a/tren.rst +++ b/tren.rst @@ -1272,12 +1272,13 @@ *sequence* renaming token. This would rename all the files in the current directory ending with -``.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:: +``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the +picture was taken ( well, actually, the date the file was last +modified). 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:: 20100103-MyVacation-0001.jpeg # Sid's 20100105-MyVacation-0001.jpeg # Mary's @@ -1310,12 +1311,12 @@ this same name is used to identify backup files. You might then do something like this:: - tren.py -xr '/$SYSNAME/.*.bku=/FNAME/.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``. +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``. +rename files whose names began with ``morton`` and ended with ``bku``. Notice that we combined a reference to an environment variable within a regular expression. This was done to do the match on "names @@ -1329,7 +1330,7 @@ on a machine called "matrix", the command will be handed to **tren** looking like this:: - tren.py -xr /matrix/.*.bku=/FNAME/.old' * + 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/``. @@ -1467,7 +1468,6 @@ Although they are both based on the file name (hence the common renaming token symbol), they do very different things. - How **tren** Uses File Metadata ================================ @@ -1537,6 +1537,29 @@ ID.) +There is one other important detail to keep in mind here. When +**tren** first starts up, it examines the metadata of every file- and +directory name on the command line. It uses this to pre-create the +sequences for every possible ordering (alphabetic, by date, within +date, by length, and so on) *whether or not every file actually ends +up being renamed later on*. In other words, sequences are built on +*the list of names passed on the command line* NOT on the list of +files- or directories that actually get renamed. If your renaming +requests only apply to some of the file names you passed on the +command line, you may find the resulting sequence unexpected. Say you +have three files, ``a``, ``b``, and ``c`` and you do this:: + + tren.py -rb=/FNAME/-/+FNAME::001/ a b c + +Only file ``b`` has a matching ``old`` string and thus is the only +file renamed. However, because it is second alphabetically *in the +list of files passed on the command line*, it gets renamed to +``b-002``. The way to avoid this surprise is to make sure any +renaming request with sequence renaming tokens in it is constructed in +such a way so that it applies to *all* the files- and directories +named on the command line. + + File Attribute Renaming Tokens ============================== @@ -1640,8 +1663,10 @@ System Renaming Tokens ====================== -These tokens are derived from the underlying operating system -and runtime environment. +These tokens are derived from the underlying operating system and +runtime environment. Notice that, because command interpreters +(shells) on various systems work differently, these tokens have to be +quoted in different ways. ``/$ENV/ Environment variable`` @@ -1649,7 +1674,8 @@ environment variable ``ENV``. If that variable does not exist, the token is replaced with an empty string:: - tren.py -r =/$ORGANIZATION/-/FNAME/ * + tren.py -r ='/$ORGANIZATION/'-/FNAME/ * # Unix shells + tren.py -r =/$ORGANIZATION/-/FNAME/ * # Windows shells This prepends the organization's name to everything in the current directory. @@ -1662,15 +1688,16 @@ stripped from the results, since they don't belong in file names. Spaces, however, are preserved. - For instance, you might want to prepend the name - of the system to a all you shell scripts:: + For instance, you might want to prepend the name of the + system to all you shell scripts:: - tren.py -r =/`uname -n`/-/FNAME/ *.sh + tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # Unix shells + tren.py -r ="/`uname -n`/"-/FNAME/ *.sh # Windows shells This construct is more generally a way to synthesize renaming tokens that are not built into **tren**. You can write a script to do most anything you like, - execute it within the /\`cmd\`/ construct, and plug the + execute it within the ``/`cmd`/`` construct, and plug the results into your new file name. This effectively provides **tren** an unlimited number of renaming tokens. @@ -1963,7 +1990,7 @@ :: - $Id: tren.rst,v 1.165 2010/03/30 00:43:26 tundra Exp $ + $Id: tren.rst,v 1.166 2010/04/01 19:27:33 tundra Exp $ You can find the latest version of this program at: