Fork: 0
tundra / tren
Browse code
Completed section on types of SRTs.
First complete doc.
master
1 parent 3bb0a6c commit 4c77e2720399724c61ab365573b006fd165bd983
@tundra tundra authored on 7 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
419
■■■■■
 tren.rst
Most commonly, you'll find yourself using the command line,
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
=================================
 
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.
 
NOTE HERE ABOUT COMMAND LINE LIST V. FILES ACTUALLY PROCESSED
 
NOTE HERE ABOUT WHAT HAPPENS WHEN MORE THAN ONE FILE/DIR MAPS
TO SAME PROPERTY.
 
 
**tren** currently supports the following kinds of sequencing:
 
``/+-ADATE:Alphabet:FormatField/ Sequence based on``
 
Explanation
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.
 
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:: 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:
 
 
``/+-ADATE:Alphabet:FormatField/ Sequence based on atime timestamp WITHIN the same date``
 
``/+-CDATE:Alphabet:FormatField/ Sequence based on ctime timestamp WITHIN the same date``
 
``/+-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
 
``/+-CDATE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-CMDLINE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-CTIME:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-DEV:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-FNAME:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-GID:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-GROUP:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-INODE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-MDATE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-MODE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-MTIME:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-NLINK:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-SIZE:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-UID :Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-USER:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
``/+-ATIME:Alphabet:FormatField/ Sequence based on atime timestamp``
 
``/+-CTIME:Alphabet:FormatField/ Sequence based on ctime timestamp``
 
``/+-MTIME:Alphabet:FormatField/ Sequence based on mtime timestamp``
 
These return sequences in absolute timestamp order. For example::
 
touch foo
touch bar
touch baz
tren.py -r =/+MTIME::/-/FNAME
 
Yields::
 
foo-0
bar-1
baz-2
 
 
``/+-CMDLINE:Alphabet:FormatField/ Sequence based on the order of appearance on the command line``
 
This is nothing more than the command line order::
 
tren.py -r=/+CMDLINE/-/FNAME::01/-/FNAME/ z b a
 
Yields::
 
01-z
02-b
03-a
 
 
``/+-DEV:Alphabet:FormatField/ Sequence based on the device ID number on which the file- or directory resides``
 
This is the a sequence ordered by which device ID contains the file-
or directory to be renamed.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-FNAME:Alphabet:FormatField/ Sequence based on alphabetic order of all targets on the command line``
 
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::
 
tren.py -r=/+FNAME::/-/FNAME/ a/z b/b
 
Yields::
 
a/0-z
b/1-b
 
This is because the original file name ``a/z`` sorts alphabetically
before ``b/b``.
 
 
``/+-GID:Alphabet:FormatField/ Sequence based on the group ID number``
 
This returns a sequence ordered by the ID number of the group to which
the file- or directory belongs.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-GROUP:Alphabet:FormatField/ Sequence based on the group name``
 
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
-----------------------
-----------------------------
 
::
 
$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:
 
http://www.tundraware.com/Software/tren