Fork: 0
tundra / tren
Browse code
Began cleanup of renaming token details.
master
1 parent 44d5077 commit 160fe4b079a354582e53c93ab1bdbe8856e8fcc8
@tundra tundra authored on 20 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
243
■■■■■
 tren.rst
old- or new string definition, **tren** will replace it with *the
creation date of the file or directory being renamed* and use that
string in the renaming process.
 
There are also tokens that can be used to automatically renumber or
sequence a set of files or directories being renamed. Finally, there
are tokens that allow you to use system information in your renaming
strings.
There are also tokens that allow you to use system information in your
renaming strings. Finally, there are tokens that can be used to
automatically renumber or sequence (order) a set of files or
directories being renamed.
 
For example, suppose you and your friends pool your vacation photos
but each of your cameras uses a slightly different naming scheme. You
might want to just reorder them by the date and time each picture was
 
RENAMING TOKENS: THE GORY DETAILS
---------------------------------
 
Token based renaming is used when you want to impose a naming
"pattern" on a group of files or directories. This is most useful
when the existing filenames have little or nothing in common. In such
situations, there's often no direct way to use string substitutions to
order the names in some coherent way.
 
A "token" is built from literal text and *renaming tokens*. These
tokens are delimited by the ``/`` character. **tren** replaces these
tokens with corresponding information (see descriptions below) to
produce a final "token text". The token text is the actual
string used to either replace the existing file or directory name (or
just the "name" or "extension" portions, depending on which options
you've selected) or to be appended or prepended to the name.
 
Currently, **tren** defines a number of renaming tokens.
As we've just seen, a *Renaming Token* is nothing more than
a string representing something **tren** knows about one of
three things:
 
- An attribute of the file or directory being renamed
- An attribute of the underling operating system environment
- A sequence that reflects some ordering principle
 
Renaming tokens are delimited by the ``/`` character. **tren**
replaces these tokens with the corresponding information (see
descriptions below) wherever you indicated in either the ``old`` or
``new`` strings of a ``-r`` rename command.
 
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.
 
File Attribute Renaming Tokens
---------------------------------
 
``/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 ``YYYMMDD`` format.
in ``yyyymmdd`` format.
 
``/E/ Original File Extension``
 
This token is replaced the "extension" portion of the file
 
This token is replaced with the name of the
primary group to which the file belongs.
 
``/I/ File or directory creation date``
``/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-YY``.
 
``/S/ File or directory size``
``/L/ File or directory length``
 
This token is replaced with a numeric string
that indicates the size of the file or directory
that indicates the length of the file or directory
in bytes.
 
``/T/ File or directory creation time``
 
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
file or direcotry's owner.
file or directory's owner.
 
``/d/ File or directory day of creation``
 
This token is replaced with the the day of the month the
file was created in ``dd`` format.
 
``/h / File or directory hour of creation``
 
This token is replaced with the hour the file was
created in ``hh`` format.
 
``/m/ File or directory minutes of creation``
 
This token is replaced with the minutes the file was
created in ``mm`` format.
 
``/o/ File or directory month of creation``
 
This token is replaced with the numeric month the file was
created in ``mm`` format.
 
``/ooo/ File or directory month of creation``
 
This token is replaced with the abbreviated name of the
month the file was created in ``Mmm`` format.
 
``/s/ File or directory seconds of creation``
 
This token is replaced with the seconds the file was
created in ``ss`` format.
 
``/y/ File or directory year of creation``
 
This token is replaced with the year the file was
created in ``yyyy`` format.
 
 
 
 
System Related Renaming Tokens
---------------------------------
 
These tokens are derived from the underlying operating system
and runtime environment.
 
``/$ENV/ Environment variable``
 
This token is replaced with the value of
the environment variable ``$ENV``. If
that variable does not exist, the token
is replaced with an empty string::
 
tren.py -r =/$ORGANZATION/-/F/./E/ *
 
This prepends the organization's name to everything in
the current directory.
 
 
``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the text
returned by executing the ``cmd`` command.
 
For instance, you might want to prepend the name
of the system to a all you shell scripts::
 
tren.py -r =/`uname -n`/-/F/./E/ *.sh
 
This construct is more generally a way to synthesize
renaming tokens that are not built into **tren**. For
instance, the built-in tokens only provide information
about file and directory *creation* dates. You might
want to use the date of *last access*. You do this by
writing the appropriate script or program and then
executing it within the /\`cmd\`/ construct. This
effectively provides **tren** an unlimited number of
renaming tokens.
 
.. WARNING:: Be *very* careful using this. It's possible to
construct bizzarre, overly long, and just plain
chowder-headed strings that make no sense in a renaming
context using this construct.
 
 
Sequence Renaming Tokens
---------------------------
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
 
 
 
System Related Renaming Tokens
---------------------------------
 
These tokens are derived from the underlying operating system
and runtime environment.
 
``/$ENV/ Environment variable``
 
This token is replaced with the value of
the environment variable ``$ENV``. If
that variable does not exist, the token
is replaced with an empty string.
 
 
``/\cmd\`/`` Arbitrary command execution``
 
This token is replaced with the text
returned by executing the ``cmd`` command.
 
 
EXAMPLES
--------
 
Here are some common examples of **tren** in action - the resulting
 
BUGS AND MISFEATURES
--------------------
 
None known as of this release.
On windows platforms, the ``/U/`` and ``/G/`` renaming tokens return
``winuser`` and ``wingroup`` respectively. They do not return the
underlying operating system ownership information.
 
 
COPYRIGHT AND LICENSING
-----------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.126 2010/01/20 16:20:39 tundra Exp $
$Id: tren.rst,v 1.127 2010/01/20 17:19:23 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren