Fork: 0
tundra / tren
Browse code
Completed section on renaming patterns.
Added odds and ends section.
master
1 parent 5f1259d commit 5d4fd6d732aef7b1594918e96c8cd76959753b92
@tundra tundra authored on 7 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
397
■■■■■
 tren.rst
Say we do this::
 
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
X
or undesirable characters like ``/``, ``\``, and ``-`` in your
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.::
 
xxx3 -> xxx3, xxx4, xxx5, ... 9999, xxx3, xxx4, ...
-+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ...
 
As **tren** counts if it encounters characters in the padding string
that are *in* the alphabet. FIIXXXXXXXXXXXXXXXXX THISSSSSSSSSS
 
 
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
To understand counting patterns, you have to understand a few
basic rules **tren** uses to interpret them:
 
- 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::
 
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::
 
 
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
=================================
 
- 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
many Microsoft Windows systems. If the Windows system has the
-----------------------------
 
::
 
$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:
 
http://www.tundraware.com/Software/tren