Fork: 0
tundra / tren
Browse code
Further cleanup of the Sequence Renaming Tokens section.
master
1 parent e920389 commit f6ac4a15a7a17c485466e00a6418e7aebee9b75d
@tundra tundra authored on 18 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
106
■■■■■
 tren.rst
.. NOTE:: Notice that there is no token for the *whole* filename
because you can always synthesize it with ``/F/./E/``
 
 
``/G/ File or directory primary group name``
 
This token is replaced with the name of the
primary group to which the file belongs.
 
``/I/ File or directory creation date``
 
This token is replaced with the date of creation of the
file or directory being renamed. It is similar to ``/D/``
This token is replaced with the time of creation
of the file or directory being renamed. It is
in ``HH:MM:SS`` format.
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
file or direcotry's owner.
 
 
Sequence Renaming Tokens
------------------------
 
Sometimes it's useful to rename files or directories not based on
their original names. Instead, it can be useful to rename them - in
whole or part, based on some *property they possess* like the date or
time of creation, the size of the file, who owns it, and so on. This
is the purpose of *sequence renaming tokens*.
 
The best way to think of sequence renaming tokens is as *unique
strings* designed to help organize the files or directories you're
renaming based on some *shared property*. The actual order of these
strings reflects something about that shared property.
Sometimes it's useful to rename files or directories based on some
*property they possess* like the date or time of creation, the size of
the file, who owns it, and so on. That's the idea behind the ``/D/``,
``/T/``, and ``/S/`` renaming tokens described in the previous section.
 
An extension of this idea is to *order all the files being renamed*
based on one of these parameters. For instance, instead of actually
embedding the date and time of creation in a file or directory name,
you might want to order the files from oldest to newest with a naming
convention like::
 
file-1.txt
file-2.txt
file-3.txt
 
This guarantees uniqueness in the final name and also sees to it that
a sorted directory listing will show you the files or directories in
the order you care about.
 
This is the purpose of *sequence renaming tokens*. They give you
various ways to create sequences that can be embedded in the final
file or directory name.
 
General Format Of Sequence Renaming Tokens
------------------------------------------
 
Sequence renaming tokens have the following general format::
 
/<optional ordering flag and type><counting pattern>/
Sequence renaming tokens consist of three descriptive components and
have the following general format::
 
/<ordering flag><type><counting pattern>/
where,
ordering flag:
- descending
type:
D sequence on file creation date
G sequence on file's group membership
D sequence on file creation date & time
O sequence on the command line file order
S sequence on file size
T sequence on file creation time within a given day
U sequence on file's owner
empty sequence on order of file renaming
 
 
Count Pattern Format
--------------------
 
In each of the cases below, the counting pattern is mandatory and
describes two things: The number of digits to use, and the starting
number in the sequence. Examples::
The counting pattern is used to specify two things: The width of the
sequence string, and the starting value for the sequence. Examples::
 
0001 -> 0001, 0002, 0003, ...
0000 -> 0000, 0001, 0002, ...
03 -> 03, 04, 05, ...
 
You do not have to use a ``0`` to indicate the number of digits to
use. 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, ...
-+8 -> -+8, -+9, -10, -11, ...
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, ...
 
You are not restricted to numbers in a counting pattern. Letters may
also be used. **tren** will preserve the case you specify in the
template when creating sequences like this.::
 
000a -> 000a, 000b, 000c, ...
---X -> ---X, ---Y, ---Z, --AA
template when creating sequences like this::
 
000a -> 000a, 000b, 000c, ... zzzz, 000a, ...
---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ...
 
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
 
 
 
System Related Renaming Tokens
-----------------------------
 
::
 
$Id: tren.rst,v 1.120 2010/01/16 20:53:08 tundra Exp $
$Id: tren.rst,v 1.121 2010/01/18 23:43:36 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren