Fork: 0
tundra / tren
Browse code
First complete document.
master
1 parent 160fe4b commit 190cc8e5fcb634ad50317dff64cf1940ec773abf
@tundra tundra authored on 20 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
109
■■■■■
 tren.rst
operands for the ``-r`` option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: ``\=``.
 
 
An Overview Renaming Tokens
---------------------------
An Overview Of Renaming Tokens
------------------------------
 
**tren** implements the notion of *Renaming Tokens*. These can
appear in either the old- or the new string components of a ``-r``
renaming argument.
``/T/ File or directory creation time``
 
This token is replaced with the time of creation
of the file or directory being renamed. It is
in ``HH:MM:SS`` format.
in ``hh:mm:ss`` format.
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
type:
D sequence on file creation date & time
L sequence on file length
R sequence on the command line file order
S sequence on file size
T sequence on file creation time within a given day
 
 
Count Pattern Format
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
 
 
Types Of Sequence Renaming Tokens
---------------------------------
 
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.
 
**tren** currently supports the following kinds of sequencing:
 
 
``/+D0001/ Sequence based on the creation date/time``
 
This produces a sequence from oldest to newest
(or the reverse) of the renamed objects.
 
``tren.py -b -r =/+D0002/ *.txt``
 
This would rename all the files in the current
directory into the form, ``0002.txt``, ``0003.txt``,
... ``9999.txt`` with ``0002.txt`` being the oldest
file and ``9999.txt`` being the newest. If you
used the token ``/-D0002/``, you'd get the same
thing, but in reverse order.
 
``/+L0001/ Sequence based on the size of the files being renamed``
 
This produces a sequence from shortest to longest
(or the reverse) of the renamed objects.
 
``tren.py -r /+L0002/ *.txt``
 
This would rename all the files in the current
directory into the form, ``0002.txt``, ``0003.txt``,
... ``9999.txt`` with ``0002.txt`` being the shortest
file and ``9999.txt`` being the longest. If you
used the token ``/-L0002/``, you'd get the same
thing, but in reverse order.
 
``/+R0001/ Sequence based on the file order on the command line``
 
This produces a sequence based on the order (or the
reverse) of renaming - i.e., The order of the names
on the command line.
 
``tren.py -e -r =/+R0000/ MyFile.txt AFile.jpg me.log``
 
This would rename all the files to, ``MyFile.0``,
``AFile.1``, and ``me.2``. If you used ``/-R0000/``,
you'd get ``MyFile.2``, ``AFile.1```, and ``me.0``.
 
``/+T0001/ Sequence based on creation time within date``
 
This produces a sequence based on the creation date
and time similar to the ``/+D.../`` sequence renaming
token above. However, the sequence *resets* at the
beginning of each new date. This allows you to
create unique sequences *within a date* like our
example of renaming photo files from different
cameras. (See: `An Overview Of Renaming Tokens`_)::
tren.py -b -r =/D/-/+T0100/ *.txt
 
This would rename all the ``.txt`` files in the current
directory into the form::
 
200103010-0100.txt
200103010-0101.txt
200103010-0102.txt
200104010-0100.txt
200104010-0101.txt
200104010-0102.txt
200104011-0100.txt
200104011-0101.txt
200104011-0102.txt
...
 
In other words, instead of sequence just on the creation date,
this allows us to sequence *within* the date. As always, the
``-`` flag will reverse this order within the date.
 
Notice that you can get something similar using just
file attribute renaming tokens::
 
tren.py -b -r =/D/-/T/ *.txt
 
This would produce names in the form::
 
200103010-03:01:23.txt
200103010-03:01:24.txt
200103010-03:01:25.txt
...
 
For most purposes, though, the order, rather than the
absolute time is both more useful and more readable.
 
 
EXAMPLES
--------
 
Here are some common examples of **tren** in action - the resulting
-----------------------------
 
::
 
$Id: tren.rst,v 1.127 2010/01/20 17:19:23 tundra Exp $
$Id: tren.rst,v 1.128 2010/01/20 18:19:42 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren