diff --git a/tren.rst b/tren.rst index 811eaa9..ab48b7e 100644 --- a/tren.rst +++ b/tren.rst @@ -880,8 +880,8 @@ 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. @@ -1229,11 +1229,9 @@ 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 @@ -1268,7 +1266,7 @@ 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 @@ -1401,8 +1399,11 @@ - 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. @@ -1468,6 +1469,7 @@ 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 ================================ @@ -1515,11 +1517,7 @@ 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 @@ -1555,18 +1553,29 @@ 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. +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. -File Attribute Renaming Tokens -============================== +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`` @@ -1658,6 +1667,59 @@ 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 @@ -1665,8 +1727,8 @@ 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`` @@ -1703,56 +1765,107 @@ 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. + .. 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 ... -Quoting System Renaming Tokens -============================== +``/RAND#/ Random Number Generator`` -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:: + This generates a (quasi) random number string ``#`` + digits wide. - tren.py -r =/FNAME/-`uname -n`-$LOGNAME + This can be useful when you want to guarantee that no + renaming operation will generate a new name that + conflicts with an existing name:: -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=/MYEAR//MMON//MDAY/-/RAND10/ * - tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # This is correct - tren.py -r =/`uname -n`/-/FNAME/ *.sh # This will fail + This generates new file names with a 10 character + random number string suffix:: -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:: + 20100401-4708910871 - tren.py -r=/FNAME/-/`command option1 option2 argument`/ files ... + In this case, just make sure the random number string + is long enough to make a name collision unlikely by + picking a sufficiently large ``#``. -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:: + ``#`` 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. - tren.py -r=/FNAME/-"/`command option1 option2 argument`/" files ... + 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 ======================== @@ -1828,6 +1941,25 @@ 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 @@ -1990,7 +2122,7 @@ :: - $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: