diff --git a/tren.rst b/tren.rst index 86ee970..2c96ebd 100644 --- a/tren.rst +++ b/tren.rst @@ -323,10 +323,10 @@ 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 @@ -417,21 +417,22 @@ 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. +As we've just seen, a *Renaming Token* is nothing more than +a string representing something **tren** knows about one of +three things: -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. + - An attribute of the file or directory being renamed + - An attribute of the underling operating system environment + - A sequence that reflects some ordering principle -Currently, **tren** defines a number of renaming tokens. +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 --------------------------------- @@ -445,7 +446,7 @@ 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`` @@ -467,16 +468,16 @@ 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`` @@ -488,7 +489,89 @@ ``/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 @@ -568,27 +651,6 @@ *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 -------- @@ -660,7 +722,9 @@ 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 @@ -689,7 +753,7 @@ :: - $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: