diff --git a/tren.rst b/tren.rst index 18704c1..9758623 100644 --- a/tren.rst +++ b/tren.rst @@ -2102,8 +2102,8 @@ tren.py -A Foo:s2X -r=/+MTIME:Foo:/ * -This will rename all the files in the current directory in "mtime" timestamp -ascending order using the following counting scheme:: +This will rename all the files in the current directory in ascending +``mtime`` timestamp order using the following counting scheme:: s 2 @@ -2144,31 +2144,216 @@ alphabets so they don't end up getting embedded in a name (or trying to, anyway). +- If you use non-numerical counting schemes, your sorted directory + list will not reflect that order. For example, suppose you have + a bunch of files in a directory, and you do this:: + + tren.py -r=/-MTIME:LowerUpper:/ * + + Your files will get renamed in descending ``mtime`` timestamp order + as:: + + a + b + ... + A + B + ... + aa + + And so on, where ``a`` is the oldest file- or directory. However, + when you do a sorted directory listing, the names beginning with + *upper case* characters will be listed first. Why? Because directory + sorting is typically based on ASCII order wherein ``A-Z`` appear before + ``a-Z``. + Counting Pattern Format ======================= -The counting pattern is used to specify two things: The width of the -sequence string, and the starting value for the sequence. Examples:: + +When using sequence renaming tokens, it's nice to be able to layout +the resulting counting string in some consistent way. You can use an +optional "counting pattern" in your sequence renaming token to do +this. The renaming pattern is used to specify two things: The width +of the sequence string, and, optionally, the starting value for the +sequence. For instance:: + + Pattern Results + ------- ------- 0001 -> 0001, 0002, 0003, ... 0000 -> 0000, 0001, 0002, ... 03 -> 03, 04, 05, ... -You do not have to use a ``0`` to indicate the sequence width. You -can use *any* padding characters you like. **tren** only cares about -the width of the field and will "consume" your padding characters as -the count increases.:: +To understand counting patterns, you have to understand a few +basic rules **tren** uses to interpret them: - xxx3 -> xxx3, xxx4, xxx5, ... 9999, xxx3, xxx4, ... - -+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ... + - The number of characters (of any kind) in the pattern fix the + *width* of the counting string. These characters need not even be + in the counting alphabet:: -As **tren** counts if it encounters characters in the padding string -that are *in* the alphabet. FIIXXXXXXXXXXXXXXXXX THISSSSSSSSSS + tren.py -r=/+CTIME::abcde/ * + + This produces files renamed in ascending ``ctime`` timestamp order + like this:: + + abcd0 + abcd1 + ... + abc10 + + And so on. + + - When a count increments such that it would exceed the width of the + pattern, it "rolls over" and **tren** issues a warning message to + that effect. Using the example above, we'd get:: + + 9998 + 9999 + 0000 # Count rolls over and warning issued! + + Notice that the count rolls over *in the selected counting + alphabet*, it does not restart from the original counting pattern. + In almost every case, you should avoid roll over and make your + counting pattern wide enough to hold a full count for all the + files- and directories you've named on the command line. One + issue here is that rolling over is possibly going to create a name + collision and the renaming will either be skipped or have to be + forced (with backup) using the ``-f`` option. + + - As we've seen, **tren** treats each position of the counting + pattern as a placeholder and "eats" characters as the count goes + up. This allows you great flexibility in creating renaming + patterns that embed both a count and *a literal* string via + a single sequence renaming token. You just have to make the + counting pattern wide enough so that the highest count never + consumes your literal string:: + + tren.py -r=/+MTIME:HexLower:InHexMtimeOrder-0x00000/ * + + This yields new file names like this:: + + InHexMtimeOrder-0x00000 + InHexMtimeOrder-0x00001 + InHexMtimeOrder-0x00002 + ... + + Notice that the ``0x`` string may mean "this is a hex number" to + the human reader, but it is completely insignificant to **tren**. + If the count were to get large enough - bigger than 5 digits, the + ``0x`` string itself would get overwritten. Larger still, and + ``InHexMtimeOrder-`` would start to get consumed. + + .. TIP:: We could avoid the possibility of having the count ever + consume our literal text, by taking it *out of the + sequence renaming token* and putting it in as a literal + argument to the ``-r`` option:: + + tren.py -r=InHexMtimeOrder-0x/+MTIME:HexLower:00000/ * + + + In short, **tren** treats *every character in a counting pattern + the same* - with complete indifference. + + - Well ... *almost* "complete indifference". When **tren** finds + characters that are *in* the selected counting alphabet, it + *adds them to the count*. In this way we start counting at + some predermined initial value. Note that **tren** always + produces sequence number *starting with 0* and, unless the + pattern indicates otherwise:: + + tren.py -r=/+CMDLINE::/ a b c + + Produces:: + + 0 # Formerly a, the 1st command line argument + 1 # Formerly b, the 2nd command line argument + 2 # Formerly c, the 3nd command line argument + + But say we wanted to start counting from 1 instead:: + + tren.py -r=/+CMDLINE::1/ a b c + + Produces:: + + 1 # Formerly a, the 1st command line argument + 2 # Formerly b, the 2nd command line argument + 3 # Formerly c, the 3nd command line argument + + Similarly, ``/+CMDLINE::101/`` would produce:: + + 101 # Formerly a, the 1st command line argument + 102 # Formerly b, the 2nd command line argument + 103 # Formerly c, the 3nd command line argument + + Because **tren** is insensitive to characters *outside* + the counting alphabet, you can produce really interesting + counting patterns like this:: -Notice that when a sequence "rolls over", the next value is the -*initial sequence value you specified*. + tren.py -r=/+CMDLINE::1x0/ a b c + + Produces:: + + 1x0 # Formerly a, the 1st command line argument + 1x1 # Formerly b, the 2nd command line argument + 1x2 # Formerly c, the 3nd command line argument + + If you had enough files named on the command line, the + count would eventually consume the out-of-alphabet + characters:: + + 1x0 + ... + 1x9 + 110 + 111 + ... + + + So, by mixing characters that are both in- and out of the counting + alphabet in a counting pattern, you "prime" the sequence renaming + token to start counting with a certain string. This works for all + alphabets, any base, and any symbol set:: + + tren.py -r=/+FNAME/:Upper:+0S/ * + + Yields new file names:: + + +0S + +0T + ... + +0Z + +BA + +BB + ... + + - There is no notion of starting the count from a "negative number" + and counting up. You can sort of synthesize this by sticking a + ``-`` in front of a sequence renaming token (or at the left end of + its counting pattern). Keep in mind, though, that **tren** only + knows how to *increment* a count so you will always get an + "increasing negative number" when you do this:: + + tren.py -r=-/+CMDLINE::5/-/FNAME/ a b c + + Will produce new file names:: + + -5-a + -6-b + -7-c + + If you want the reverse order, specify a descending sequence + renaming token:: + + tren.py -r=-/-CMDLINE::5/-/FNAME/ a b c + + Will produce new file names:: + + -5-c + -6-b + -7-a Types Of Sequence Renaming Tokens @@ -2279,11 +2464,19 @@ - Ordering File Names By Size +ODDS AND ENDS +------------- + +- Quoting your command line arguments properly for the shell you + use is critical. Things like spaces, ``\``, + BUGS, MISFEATURES, OTHER ------------------------ You must be running Python 2.6.x or later. **tren** makes use of -features not supported in releases prior to this. +features not supported in releases prior to this. **tren** has not +been tested with Python 3.x and is presumed not to work with it +until/unless otherwise demonstrated. As a general matter, **tren** should run on any POSIX-compliant OS that has this version (or later) of Python on it. It will also run on @@ -2346,7 +2539,7 @@ :: - $Id: tren.rst,v 1.177 2010/04/07 18:25:24 tundra Exp $ + $Id: tren.rst,v 1.178 2010/04/07 21:04:11 tundra Exp $ You can find the latest version of this program at: