Fork: 0
tundra / tren
Browse code
Documented /RAND#/
Further cleanup of RT documentation.
Put in basic scaffolding for all RT detail documentation.
master
1 parent bfbd55c commit 17b9942329b2427751be6b5f8c2788d3ad31f5dc
@tundra tundra authored on 1 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
342
■■■■■
 tren.rst
 
3) Build a table of every file name to be renamed.
 
We'll need this information if any of the renaming requests use
the file- or sequence renaming tokens (discussed later in this
document).
the file attribute- or sequence renaming tokens (discussed
later in this document).
 
4) Build a table containg each renaming request storing the current
state of every program option at that point on the command line.
 
**tren** implements the notion of *renaming tokens*. These can
appear in either the ``old`` or ``new`` string components of a ``-r``
renaming argument.
 
It is sometimes useful to be able to take a group of files or
directories whose names have nothing in common and impose a common
naming scheme on them. Another use for renaming tokens is to do the
renaming based on some property the file or directory possesses like
its creation date, size, owner's name, and so on.
It is sometimes useful to be able to take a group of files or rename
them using some property they possess like creation date, size,
owner's name, and so on. This is the purpose of renaming tokens.
 
Renaming tokens are nothing more than special symbols that represent
"canned" information **tren** knows about the file- or directory
being renamed, information from the OS itself, and information used to
tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp*
 
Every place you see something in the form ``/.../``, think, "That is a
renaming token whose value will be filled in by **tren**." This
syntax is the same whether you're using a *file*-, *system*-, or
syntax is the same whether you're using a *file attribute*-, *system*-, or
*sequence* renaming token.
 
This would rename all the files in the current directory ending with
``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the
- 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
Renaming tokens are delimited by ``/`` characters, in the form::
 
/RenTokenName/
 
**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
is a sequence renaming token that returns the *position* (order) of
the file name in alphabetic order starting counting from ``003``.
Although they are both based on the file name (hence the common
renaming token symbol), they do very different things.
 
 
How **tren** Uses File Metadata
================================
 
command line and makes it available in the form of renaming tokens.
 
Most commonly, you'll find yourself using the command line,
alphabetic, original name, length, and various time/date renaming
tokens. Since there are actually three different kinds of date stamps
maintained in modern filesystems, it's worth knowing the difference
between them. A good tutorial can be found here:
 
http://chandynasty.blogspot.com/2007/01/difference-between-unix-mtime-ctime.html
tokens.
 
.. NOTE:: **tren** is portable across many operating systems because
it is written in the Python programming language. Python
*mostly* works the exact same way everywhere. However,
Only file ``b`` has a matching ``old`` string and thus is the only
file renamed. However, because it is second alphabetically *in the
list of files passed 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 in
such a way so that it applies to *all* the files- and directories
named on the command line.
 
 
File Attribute Renaming Tokens
==============================
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
=================================
 
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 year the file was
created in ``yyyy`` format.
 
 
Time-Related Attribute Renaming Tokens
======================================
 
Modern operating system actually maintain three different kinds of
such timestamps, ``ATIME``, ``CTIME``, ``MTIME``:
 
``ATIME`` refers to the last time the file- or directory was
*accessed*.
 
This is updated every time the file is read.
 
``CTIME`` refers to the last time the file- or directory's *inode
(directory entry) was modified*.
 
This is updated whenever a file- or directory's permissions or
ownership are changed. It will also be updated when the file- or
directory itself is modified.
 
``MTIME`` refers to the last time the file- or directory *itself was
modified*.
 
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
 
 
System Renaming Tokens
======================
 
These tokens are derived from the underlying operating system and
runtime environment. Notice that, because command interpreters
(shells) on various systems work differently, these tokens have to be
quoted in different ways.
(shells) on various systems work differently, the first two of these
have to be quoted in different ways.
 
``/$ENV/ Environment variable``
 
This token is replaced with the value of the
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 file name using this
token. Moreover, if you attempt to insert characters
that don't belong in a file- or directory name (like a
path separator), construct a file name that is too long
(or too short), or just generally violate something
about the filesystem's naming rules, this will cause
**tren** to abort and spit out an error. *However*, you
will not be prevented from creating file names that are
legal but undesirable, such as file names that begin
with the ``-`` character. In other words, be careful
and be sure you know what you're doing with this
renaming token.
 
 
Quoting System Renaming Tokens
==============================
 
Both of these constructs are supported directly from most Unix command
shells. That is, most Unix shells will themselves dereference
constructs like ``$ENV`` and ```command```. There's no need to pass
them as renaming tokens, you can just use the shell's capabilities::
 
tren.py -r =/FNAME/-`uname -n`-$LOGNAME
 
If you do want to use the renaming token form in a Unix shell, you
*must* single quote them to prevent the shell from "interpolating" the
variables before **tren** is called. If you don't do this, **tren**
will complain about encountering unknown renaming tokens::
 
tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # This is correct
tren.py -r =/`uname -n`/-/FNAME/ *.sh # This will fail
 
The real reason for providing these renaming tokens at all is because
the Windows command interpreter does not have an equivalent function.
The *only* way to achieve what these do on Windows is via renaming
tokens. In Windows, you also have to pay attention to quoting,
particularly when there are spaces in a ```cmd``` renaming token::
 
tren.py -r=/FNAME/-/`command option1 option2 argument`/ files ...
 
This is causes **tren** to complain mightily because it thinks
``/`command``, ``option``, ``option2``, are all separate (invalid)
command line arguments. To avoid this problem, you need to pass
the renaming token as a single command line entity via quotes::
 
tren.py -r=/FNAME/-"/`command option1 option2 argument`/" files ...
 
 
.. 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 file name using this
token. Moreover, if you attempt to
insert characters that don't belong
in a file- or directory name (like a
path separator), construct a file
name that is too long (or too
short), or just generally violate
something about the filesystem's
naming rules, this will cause
**tren** to abort and spit out an
error. *However*, you will not be
prevented from creating file names
that are legal but undesirable, such
as file names that begin with the
``-`` character. In other words, be
careful and be sure you know what
you're doing with this renaming
token.
.. Note:: **MORE ABOUT QUOTING** ``/$ENV/`` **AND** ``/`cmd`/`` **SYSTEM RENAMING TOKENS**
 
Both of these constructs are supported directly from most
Unix command shells. That is, most Unix shells will
themselves dereference constructs like ``$ENV`` and
```command```. There's no need to pass them as renaming
tokens, you can just use the shell's capabilities::
 
tren.py -r =/FNAME/-`uname -n`-$LOGNAME
 
If you do want to use the renaming token form in a Unix
shell, you *must* single quote them to prevent the shell
from "interpolating" the variables before **tren** is
called. If you don't do this, **tren** will complain about
encountering unknown renaming tokens::
 
tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # This is correct
tren.py -r =/`uname -n`/-/FNAME/ *.sh # This will fail
 
The real reason for providing these renaming tokens at all
is because the Windows command interpreter does not have an
equivalent function. The *only* way to achieve what these
do on Windows is via renaming tokens. In Windows, you also
have to pay attention to quoting, particularly when there
are spaces in a ```cmd``` renaming token::
 
tren.py -r=/FNAME/-/`command option1 option2 argument`/ files ...
 
This causes **tren** to complain mightily because it thinks
``/`command``, ``option``, ``option2``, are all separate
(invalid) command line arguments. To avoid this problem,
you need to pass the renaming token as a single command line
entity via quotes::
 
tren.py -r=/FNAME/-"/`command option1 option2 argument`/" files ...
 
 
``/RAND#/ Random Number Generator``
 
This generates a (quasi) random number string ``#``
digits wide.
 
This can be useful when you want to guarantee that no
renaming operation will generate a new name that
conflicts with an existing name::
 
tren.py -r=/MYEAR//MMON//MDAY/-/RAND10/ *
 
This generates new file names with a 10 character
random number string suffix::
 
20100401-4708910871
 
In this case, just make sure the random number string
is long enough to make a name collision unlikely by
picking a sufficiently large ``#``.
 
``#`` must be a positive integer greater than 0. The
random number generator is reinitialized each time the
program runs, so test mode operations will only show
you the "shape" of the names with the embedded random
number strings, not the actual strings you'll end up
with.
 
Another nice use of this feature is to "mask" the
actual file names. Say you have a bunch of encrypted
files, but you don't want a casual viewer to even know
what they are or what's in them. You might do this::
 
tren.py -r=/RAND25/ * 2>&1 >tren.log
 
Now you can encrypt ``tren.log`` and send it along with
the files themselves over a non-secure channel. The
recipient can decrypt the log, and figure out what the
original file names were, decrypt them, and store them
accordingly.
 
Sequence 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
-----------------------------
 
::
 
$Id: tren.rst,v 1.166 2010/04/01 19:27:33 tundra Exp $
$Id: tren.rst,v 1.167 2010/04/01 21:14:44 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren