Fork: 0
tundra / tren
Browse code
Cleaned up section on system renaming tokens.
Wrote new section on quoting system renaming tokens.
master
1 parent 7c92aac commit f26ff2b0c53df7a21712cd0a1eb09c1dd30ccc15
@tundra tundra authored on 29 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
172
■■■■■
 tren.rst
 
 
 
 
System Related renaming tokens
==============================
System 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 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 =/$ORGANIZATION/-/FNAME/ *
 
This prepends the organization's name to everything in
the current directory.
 
 
``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the string
returned by executing the ``cmd`` command.
``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the string returned by
executing the ``cmd`` command. Note that newlines are
stripped from the results, since they don't belong in
file names. Spaces, however, are preserved.
 
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.
tren.py -r =/`uname -n`/-/FNAME/ *.sh
 
This construct is more generally a way to synthesize
renaming tokens that are not built into **tren**. You
can write a script to do most anything you like,
execute it within the /\`cmd\`/ construct, and plug the
results into your new file name. 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 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 ...
 
 
 
Sequence Renaming Tokens
========================
 
Sequence renaming tokens consist of three descriptive components and
have the following general format::
 
/<ordering flag><type><counting pattern>/
/<ordering flag><type>:alphabet:<counting pattern>/
where,
ordering flag:
- descending
type:
D sequence on file creation date & time
L sequence on file length
R sequence on the command line file order
T sequence on file creation time within a given day
FIX THISSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
 
 
Count Pattern Format
====================
 
xxx3 -> xxx3, xxx4, xxx5, ... 9999, xxx3, xxx4, ...
-+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ...
 
You are not restricted to numbers in a counting pattern. Letters may
also be used. **tren** will preserve the case you specify in the
token when creating sequences like this::
 
000a -> 000a, 000b, 000c, ... zzzz, 000a, ...
---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ...
As **tren** counts if it encounters characters in the padding string
that are *in* the alphabet. FIIXXXXXXXXXXXXXXXXX THISSSSSSSSSS
 
 
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.162 2010/03/29 19:32:41 tundra Exp $
$Id: tren.rst,v 1.163 2010/03/29 21:41:13 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren