Fork: 0
tundra / tren
Browse code
Further scaffolding for documenting the renaming tokens.
master
1 parent 17b9942 commit 72d3fb897781bdf0daacb4e1007b64718f293721
@tundra tundra authored on 1 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
467
■■■■■
 tren.rst
These tokens are derived from information about the file or
directory being renamed.
 
 
DEV
FNAME
GID
GROUP
INODE
MODE
NLINK
SIZE
UID
USER
 
 
``/D/ File or directory creation date``
 
This token is replaced with the date of creation
of the file or directory being renamed. It is
in ``yyyymmdd`` format.
 
``/dd/ File or directory day of creation``
 
This token is replaced with the the day of the month the
file was created in ``dd`` format.
 
``/dy/ File or directory day of creation``
 
This token is replaced with the the name of the day the
file was created in ``Ddd`` format.
 
``/E/ Original File Extension``
 
This token is replaced the "extension" portion of the file
or directory before renaming. This does not include the
extension separator string.
 
``/F/ Original File Name``
 
This token is replaced the "name" portion of the file or
directory before renaming.
 
.. 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.
 
``/hh/ File or directory hour of creation``
 
This token is replaced with the hour the file was
created in ``hh`` format.
 
``/I/ File or directory creation date in ISO format``
 
This token is replaced with the date of creation of the
file or directory being renamed. It is similar to ``/D/``
except it is in ISO format, ``YYYY-MM-DD``.
 
``/L/ File or directory length``
 
This token is replaced with a numeric string
that indicates the length of the file or directory
in bytes.
 
``/mm/ File or directory minutes of creation``
 
This token is replaced with the minutes the file was
created in ``mm`` format.
 
``/mo/ File or directory month of creation``
 
This token is replaced with the numeric month the file was
created in ``mm`` format.
 
``/my/ File or directory month of creation``
 
This token is replaced with the abbreviated name of the
month the file was created in ``Mmm`` format.
 
``/ss/ File or directory seconds of creation``
 
This token is replaced with the seconds the file was
created in ``ss`` format.
 
``/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. This is equivalent to ``/hh/:/mm/:/ss/``.
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
file or directory's owner.
 
``/yyyy/ File or directory year of creation``
 
This token is replaced with the year the file was
created in ``yyyy`` format.
``/DEV/ What This Is``
 
Explanation
 
``/FNAME/ What This Is``
 
Explanation
 
``/GID/ What This Is``
 
Explanation
 
``/GROUP/ What This Is``
 
Explanation
 
``/INODE/ What This Is``
 
Explanation
 
``/MODE/ What This Is``
 
Explanation
 
``/NLINK/ What This Is``
 
Explanation
 
``/SIZE/ What This Is``
 
Explanation
 
``/UID/ What This Is``
 
Explanation
 
``/USER/ What This Is``
 
Explanation
 
 
Time-Related Attribute Renaming Tokens
======================================
 
This is updated whenever the file- or directory itself is modified.
 
**tren** implements a set of time-related file attribute renaming
tokens intended to provide full access to these various timestamps.
 
 
 
 
ADAY
AHOUR
AMIN
AMON
AMONTH
ASEC
AWDAY
AYEAR
CDAY
CHOUR
CMIN
CMON
CMONTH
CSEC
CWDAY
CYEAR
MDAY
MHOUR
MMIN
MMON
MMONTH
MSEC
MWDAY
MYEAR
tokens intended to provide full access to these various timestamps. They
are identically named, except that the first letter of each of the
time-related attribute tokens indicates which of the three timestamps
above is used to compute the value:
 
 
``/ADAY/, /CDAY/, /MDAY/ What This Is``
 
Explanation
 
``/AHOUR, /CHOUR/, /MHOUR/ What This Is``
 
Explanation
 
``/AMIN/, /CMIN/, /MMIN/ What This Is``
 
Explanation
 
``/AMON/, /CMON/, /MMON/ What This Is``
 
Explanation
 
``/AMONT, /CMONTH/, /MMONTH/ What This Is``
 
Explanation
 
``/ASEC/, /CSEC/, /MSEC/ What This Is``
 
Explanation
 
``/AWDAY, /CWDAY/, /MWDAY/ What This Is``
 
Explanation
 
``/AYEAR, /CYEAR/, /MYEAR/ What This Is``
 
Explanation
 
 
System Renaming Tokens
======================
 
Types Of Sequence Renaming Tokens
=================================
 
 
ADATE
ATIME
CDATE
CMDLINE
CTIME
DEV
FNAME
GID
GROUP
INODE
MDATE
MODE
MTIME
NLINK
SIZE
UID
USER
 
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.
``/+-ADATE:Alphabet:FormatField/ Sequence based on``
 
Explanation
``/+-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
 
 
BUGS, MISFEATURES, OTHER
------------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.167 2010/04/01 21:14:44 tundra Exp $
$Id: tren.rst,v 1.168 2010/04/01 21:55:53 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren