diff --git a/tren.rst b/tren.rst index 0dfe308..02b94ea 100644 --- a/tren.rst +++ b/tren.rst @@ -1549,27 +1549,6 @@ alphabetic, original name, length, and various time/date renaming tokens. -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/ b c a - -Only file ``b`` has a matching ``old`` string and thus is the only -file renamed. However, because it is second alphabetically *of all -the files named 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 so that it applies -to *all* the files- and directories named on the command line. - General Attribute Renaming Tokens ================================= @@ -2360,86 +2339,205 @@ ================================= Sequence renaming tokens are thus a way to generate an ordering *based -on some property common to everything being renamed*. Keep in mind -that for purposes of sequencing, **tren** *makes no distinction -between a file and directory*. It merely sequences based on the -property you requested. +on some property common to everything being renamed*. That property +is used to return a string representing just where in that order a +particular file- or directory appears. This string is formatted +according to the counting alphabet and counting pattern embedded in +the sequence renaming token as described in the previous sections. -NOTE HERE ABOUT COMMAND LINE LIST V. FILES ACTUALLY PROCESSED +Keep in mind that for purposes of sequencing, **tren** *makes no +distinction between a file and directory*. It merely sequences based +on the property you requested. -NOTE HERE ABOUT WHAT HAPPENS WHEN MORE THAN ONE FILE/DIR MAPS -TO SAME PROPERTY. +.. NOTE:: There is one *very* 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/ b c a + + Only file ``b`` has a matching ``old`` string and thus is + the only file renamed. However, because it is second + alphabetically *of all the files named 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 so that it applies to + *all* the files- and directories named on the command line. + +Sometimes, more than one file- or directory named on the command line +maps to the same sequencing key. For example, when using the +``/+GROUP.../`` sequence renaming token, dozens of files in a given +directory may only map to a few group names. In this situation, all +the names that map to the same key *will be sequenced alphabetically +within the key*. So if ``a`` and ``b`` are in group ``foo`` and +``c`` and ``d`` are in group ``baz``:: + + tren.py -r=/+GROUP/::/-/FNAME/ a b c d + +Will create the new names:: + + 0-c + 1-d + 2-a + 3-b + +**tren** currently supports a variety of sequence renaming tokens. +Note that those associated with the various OS timestamps begin with +the corresponding first letter: -**tren** currently supports the following kinds of sequencing: +``/+-ADATE:Alphabet:FormatField/ Sequence based on atime timestamp WITHIN the same date`` -``/+-ADATE:Alphabet:FormatField/ Sequence based on`` +``/+-CDATE:Alphabet:FormatField/ Sequence based on ctime timestamp WITHIN the same date`` - Explanation +``/+-MDATE:Alphabet:FormatField/ Sequence based on mtime timestamp WITHIN the same date`` + +These return sequences *within* a given day. This enables +renaming constructs like:: + + tren.py -r=/MYEAR//MMON/MDAY/-/+MDATE::001/ * + +Yielding files named:: + + 20100305-001 + 20100305-002 + 20100305-003 + 20100316-001 + 20100316-002 + 20100316-003 + ... -``/+-ATIME:Alphabet:FormatField/ Sequence based on`` - Explanation +``/+-ATIME:Alphabet:FormatField/ Sequence based on atime timestamp`` -``/+-CDATE:Alphabet:FormatField/ Sequence based on`` +``/+-CTIME:Alphabet:FormatField/ Sequence based on ctime timestamp`` - Explanation +``/+-MTIME:Alphabet:FormatField/ Sequence based on mtime timestamp`` -``/+-CMDLINE:Alphabet:FormatField/ Sequence based on`` +These return sequences in absolute timestamp order. For example:: - Explanation + touch foo + touch bar + touch baz + tren.py -r =/+MTIME::/-/FNAME -``/+-CTIME:Alphabet:FormatField/ Sequence based on`` +Yields:: - Explanation + foo-0 + bar-1 + baz-2 -``/+-DEV:Alphabet:FormatField/ Sequence based on`` - Explanation +``/+-CMDLINE:Alphabet:FormatField/ Sequence based on the order of appearance on the command line`` -``/+-FNAME:Alphabet:FormatField/ Sequence based on`` +This is nothing more than the command line order:: - Explanation + tren.py -r=/+CMDLINE/-/FNAME::01/-/FNAME/ z b a -``/+-GID:Alphabet:FormatField/ Sequence based on`` +Yields:: - Explanation + 01-z + 02-b + 03-a -``/+-GROUP:Alphabet:FormatField/ Sequence based on`` - Explanation +``/+-DEV:Alphabet:FormatField/ Sequence based on the device ID number on which the file- or directory resides`` -``/+-INODE:Alphabet:FormatField/ Sequence based on`` +This is the a sequence ordered by which device ID contains the file- +or directory to be renamed. - Explanation +This is not supported on Windows and defaults to an alphabetic +sequence equivalent to ``/+-FNAME.../``. -``/+-MDATE:Alphabet:FormatField/ Sequence based on`` - Explanation +``/+-FNAME:Alphabet:FormatField/ Sequence based on alphabetic order of all targets on the command line`` -``/+-MODE:Alphabet:FormatField/ Sequence based on`` +This returns a sequence based on the alphabetic order of everything +you've named for renaming. Note that this is done on *the fully +qualified path name for each argument*, not just the file- or +directory name itself:: - Explanation + tren.py -r=/+FNAME::/-/FNAME/ a/z b/b -``/+-MTIME:Alphabet:FormatField/ Sequence based on`` +Yields:: - Explanation + a/0-z + b/1-b -``/+-NLINK:Alphabet:FormatField/ Sequence based on`` +This is because the original file name ``a/z`` sorts alphabetically +before ``b/b``. - Explanation -``/+-SIZE:Alphabet:FormatField/ Sequence based on`` +``/+-GID:Alphabet:FormatField/ Sequence based on the group ID number`` - Explanation +This returns a sequence ordered by the ID number of the group to which +the file- or directory belongs. -``/+-UID :Alphabet:FormatField/ Sequence based on`` +This is not supported on Windows and defaults to an alphabetic +sequence equivalent to ``/+-FNAME.../``. - Explanation -``/+-USER:Alphabet:FormatField/ Sequence based on`` +``/+-GROUP:Alphabet:FormatField/ Sequence based on the group name`` - Explanation +This returns a sequence ordered by the name of the group to which the +file- or directory belongs. + +This is only supported on Windows if the ``win32all`` Python extensions +are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``. + +``/+-INODE:Alphabet:FormatField/ Sequence based on the inode number`` + +This returns a sequence ordered by the file- or directory inode numbers. + +This is not supported on Windows and defaults to an alphabetic +sequence equivalent to ``/+-FNAME.../``. + + +``/+-MODE:Alphabet:FormatField/ Sequence based on permissions`` + +This returns a sequence ordered by the file- or directories permissions +value. + + +``/+-NLINK:Alphabet:FormatField/ Sequence based on the nlink count`` + +This returns a sequence ordered by the number of links associated +with the file- or directory. + +This is not supported on Windows and defaults to an alphabetic +sequence equivalent to ``/+-FNAME.../``. + + +``/+-SIZE:Alphabet:FormatField/ Sequence based on size`` + +This returns a sequence ordered by the size of each file- or +directory. + +``/+-UID :Alphabet:FormatField/ Sequence based on the user ID number`` + +This returns a sequence ordered by the ID number of the user that +owns the file- or directory. + +This is not supported on Windows and defaults to an alphabetic +sequence equivalent to ``/+-FNAME.../``. + + +``/+-USER:Alphabet:FormatField/ Sequence based on user name`` + +This returns a sequence ordered by the name of the user that own +the file- or directory. + +This is only supported on Windows if the ``win32all`` Python extensions +are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``. COMMON TASKS AND IDIOMS @@ -2643,7 +2741,7 @@ :: - $Id: tren.rst,v 1.180 2010/04/07 21:45:29 tundra Exp $ + $Id: tren.rst,v 1.181 2010/04/07 23:00:56 tundra Exp $ You can find the latest version of this program at: