diff --git a/tren.rst b/tren.rst index 07b65d9..2f8c6c0 100644 --- a/tren.rst +++ b/tren.rst @@ -1630,49 +1630,94 @@ -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:: + 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/ * + tren.py -r =/$ORGANIZATION/-/FNAME/ * This prepends the organization's name to everything in the current directory. -``/`cmd`/ Arbitrary command execution`` +``/`cmd`/ Arbitrary command execution`` - This token is replaced with the string - returned by executing the ``cmd`` command. + 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 + tren.py -r =/`uname -n`/-/FNAME/ *.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. + 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 renaming - context using this construct. + +.. 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 @@ -1707,7 +1752,7 @@ Sequence renaming tokens consist of three descriptive components and have the following general format:: - // + /:alphabet:/ where, ordering flag: @@ -1717,10 +1762,7 @@ 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 @@ -1741,12 +1783,9 @@ 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:: +As **tren** counts if it encounters characters in the padding string +that are *in* the alphabet. FIIXXXXXXXXXXXXXXXXX THISSSSSSSSSS - 000a -> 000a, 000b, 000c, ... zzzz, 000a, ... - ---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ... Notice that when a sequence "rolls over", the next value is the *initial sequence value you specified*. @@ -1917,7 +1956,7 @@ :: - $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: