Fork: 0
tundra / tren
Browse code
Added TOC.
master
1 parent 1e8cc26 commit 2301f6ce44ad4f46c3e2040a5999adb0460a5853
@tundra tundra authored on 29 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
83
■■■■■
 tren.rst
.. contents::
 
NAME
----
 
**tren** - Advanced File Renaming
Currently, **tren** defines a number of renaming tokens. Future
releases of **tren** may add more of these, so it's good to
periodically reread this material.
 
 
What's The Difference Between An "Attribute" And A "Sequence"?
==============================================================
 
Some renaming tokens return *attributes* (of either a file or
the underling operating system). Some return *sequences*. So,
what's the difference?
 
An "attribute" is a *value* associated with the file- or
directory being renamed (or something about the underlying
operating system). It could be the length of the file, the
last year it was modified, and so on. For example, ``/MYEAR/``
returns the year the file being renamed was last modified,
``/SIZE/`` returns the length of the file, and ``/FNAME/``
returns the original name of the file before renaming.
So, if we do this::
 
tren.py -r=/FNAME/-/MYEAR/-/SIZE/ file, file ...
 
Every file will be renamed in the form of::
 
original_name-YYYY-length # Example: myfile-2010-4099
 
In short, attributes are just string substitutions wherein the string
tells you someting about the file or system on which you're working.
 
"Sequences", on the other hand, are just *numbers that represent some
ordering principle*. Say you use the sequence renaming token ordered
by size, ``/+SIZE::001/`` to rename 10 files of different sizes::
 
tren.py -r=/+SIZE::01/-/FNAME/ file, file, ...
 
This will produce a new set of files named like this::
 
01-original_name
02-original_name
03-original_name
...
10-original_name
 
Where, ``01-original_name`` will be the *shortest length* file
and ``10-original_name`` will be the *longest length* file.
 
In short, sequences are just strings of numbers used to put
things in some order.
 
You can always tell the difference between an attribute-
and sequence renaming token, because sequence renaming tokens
always start with either a ``+`` or ``-`` sign (to indicate
ascending or descending counting respectively).
 
 
How **tren** Uses File Metadata
================================
 
Files and directories have so-called "metadata" associated with them
like who owns them, how long they are, what date they were modified,
and so on. (This information is commonly described in a data structure
called ``stat``. Even non-Unix systems like Windows have some version
of this data structure.)
To keep track of all these attributes and/or to compute sequences,
**tren** needs the so-called "metadata" associated with the files- and
directories you've named on the command line. This metadata includes
information like who owns them, how long they are, what date they were
modified, and so on. (This information is commonly described in a
data structure called ``stat``. Even non-Unix systems like Windows
have some version of this data structure.)
 
The file attribute- and sequence renaming tokens are built on this
metadata, so it's worth taking a moment to understand just *how*
it is used. **tren** keeps track of the following information
- The *number of links* to the file
- The *size* of the file
 
 
**tren** uses this information to resolve file attribute renaming
tokens, compute the value of a particular sequence renaming token and
so on. For example, a sequence renaming token based on group *name*
will order the sequence *alphabetically by group name* whereas one
based on *group ID* will order it numerically.
**tren** then later uses this information to resolve file attribute
renaming tokens, compute the value of a particular sequence renaming
token and so on as it finds them in your renaming requests. For
example, a sequence renaming token based on group *name* will order
the sequence *alphabetically by group name* whereas one based on
*group ID* will order it numerically.
 
It is likely that you'll only be interested in a small subset of
these. For completness, though, **tren** keeps track of all the
metadata available about the files- or directories named on the
-----------------------------
 
::
 
$Id: tren.rst,v 1.161 2010/03/29 18:58:55 tundra Exp $
$Id: tren.rst,v 1.162 2010/03/29 19:32:41 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren
This document was produced using reStructuredText:
 
http://docutils.sourceforge.net/rst.html