diff --git a/tren.rst b/tren.rst index 6763785..a579b25 100644 --- a/tren.rst +++ b/tren.rst @@ -19,7 +19,7 @@ **tren** can do, the reference section will be handy to look up options and their arguments. -.. WARNING:: **tren** is very powerful and can easily and +.. DANGER:: **tren** is very powerful and can easily and automatically rename things in ways you didn't intend. It is ***strongly*** recommended that you try out new **tren** operations with the ``-t`` option on the command @@ -437,7 +437,7 @@ TUTORIAL AND DESCRIPTION ------------------------ -.. WARNING:: ONE MORE TIME: **tren** is a powerful file and directory +.. DANGER:: ONE MORE TIME: **tren** is a powerful file and directory renaming tool. Be **sure** you know what you're about to do. If you're not, run the program in test mode (invoke with the ``-t`` option) to see what would happen. You @@ -827,7 +827,7 @@ 2) Make sure the renaming requests operate on completely disjoint parts of the file name. -.. NOTE:: Similarly, **tren** remembers the last state of each option +.. TIP:: Similarly, **tren** remembers the last state of each option as you move from left to right on the command line. For instance:: tren.py -i1 -r f=F -r o=O foo1-foo2-foo3.foo4 @@ -941,7 +941,7 @@ Notice that we can drop the ``-f`` option because there is no longer a naming conflict (see the next section for more about forced renaming). -.. NOTE:: Always remember" **The Rightmost Renaming Request "Wins"!** +.. TIP:: Always remember" **The Rightmost Renaming Request "Wins"!** The point here, as we've said already, is that you have to be very careful when constructing command lines, keeping track of options, and @@ -1226,8 +1226,9 @@ ============================== **tren** implements the notion of *renaming tokens*. These can -appear in either the ``old`` or ``new`` string components of a ``-r`` -renaming argument. +be a bit complex to grasp at first, so we'll introduce them +"gently" in the next few sections and then dive into the detail +thereafter. 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, @@ -1245,6 +1246,34 @@ tren.py -ryear=/MYEAR/ My-year.txt # New name: My-2010.txt +Renaming tokens can appear in either the ``old`` or ``new`` string +components of a ``-r`` renaming argument. Wherever they appear, +they are "resolved" by **tren** before any renaming is attempted. +By "resolved", we mean that the renaming token will be *replaced +with a string that represents its meaning*. For example:: + + tren.py -i : -r boo=/SIZE/ boors-and-boots.txt + +This replaces all the instances of the literal string ``boo`` with +the *length* of the file ``boors-and-boots.txt``. When we're done +the file will be renamed something like:: + + 23rs-and-23ts.txt + +This is a silly example but it serves to illustrate the point - +all renaming tokens get turned into *strings* before any renaming +is attempted. + + .. NOTE:: Deep under the covers of it all, **tren** really only + knows how to do string replacement. That is, it can + replace some ``old`` string with some ``new`` string. + All the rest of the features you see are sort of + syntactic sugar to make it easy for you to express your + renaming intent. When **tren** runs, it must resolve all + that fancy syntax and boil it down to creating a new file + name the underling operating system knows how to produce + via its renaming services. + A really handy way to use renaming tokens is to name your files in a particular *order*. For example, suppose you and your friends pool your vacation photos but each of your cameras uses a slightly @@ -1258,7 +1287,7 @@ 032344.jpeg # Sid's camera, taken 1-3-2010 at 4pm It would be nice to get these in order somehow. We can, by combining -*file* renaming tokens (that know thing about the file being renamed) +*attribute* renaming tokens (that know thing about the file being renamed) and *sequence* renaming tokens (that know how to order all the files being renamed by some key like date, length, who owns it, and so on):: @@ -1266,7 +1295,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 attribute*-, *system*-, or +syntax is the same whether you're using an *attribute*-, *system*-, or *sequence* renaming token. This would rename all the files in the current directory ending with @@ -1291,7 +1320,8 @@ .. Note:: Notice that there is *no old string* in our example above. That is, there is nothing to the left of the ``=`` symbol in the ``-r`` option. This effectively means "replace - everything" in the existing file or directory name. + everything" in the existing file or directory name with our + newly concocted naming scheme. Of course, you don't *have* to replace the entire filename when using tokens. It's perfectly legitimate to replace only @@ -1519,7 +1549,7 @@ alphabetic, original name, length, and various time/date renaming tokens. -.. NOTE:: **tren** is portable across many operating systems because +.. TIP:: **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, Windows presents some problems because it does not quite @@ -1547,15 +1577,14 @@ command line, you may find the resulting sequence unexpected. Say you have three files, ``a``, ``b``, and ``c`` and you do this:: - tren.py -rb=/FNAME/-/+FNAME::001/ a b c + tren.py -rb=/FNAME/-/+FNAME::001/ b c a 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 so -that it applies to *all* the files- and directories named on the -command line. +file renamed. However, because it is second alphabetically *of all +the files named 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 so that it applies +to *all* the files- and directories named on the command line. General Attribute Renaming Tokens @@ -1627,7 +1656,8 @@ ``MTIME`` refers to the last time the file- or directory *itself was modified*. - This is updated whenever the file- or directory itself is modified. + This is updated whenever the file- or directory is closed after + modification. **tren** implements a set of time-related file attribute renaming tokens intended to provide full access to these various timestamps. They @@ -1775,7 +1805,7 @@ ``/RAND#/ Random Number Generator`` - This generates a (quasi) random number string ``#`` + This generates a (quasi) random number string, ``#`` digits wide. This can be useful when you want to guarantee that no @@ -1819,8 +1849,8 @@ Sometimes it's useful to rename files or directories based on some *property they possess* like the date or time of creation, the size of -the file, who owns it, and so on. That's the idea behind the ``/D/``, -``/L/``, and ``/T/`` renaming tokens described in the previous section. +the file, who owns it, and so on. That's the idea behind the +attribute renaming tokens described in the previous sections. An extension of this idea is to *order all the files being renamed* based on one of these parameters. For instance, instead of actually @@ -1840,6 +1870,23 @@ various ways to create sequences that can be embedded in the final file or directory name. + .. TIP:: Many sequence renaming tokens described below share the + same name with an attribute renaming token described in + the previous sections. That's because they are based on + the same property of the file- or directory being + renamed. However, it's easy to tell which is which: + Sequence renaming tokens always begin with either ``+`` + or ``-`` (to indicate ascending- and descending ordering + respectively). + + So, ``/GROUP/`` is an attribute renaming token that + returns the group *name* for the file. However, + ``/+GROUP.../`` is a sequence renaming token that returns + a number indicating what *position* the file is in when + all the files named on the command line are *ordered by + their group names*. + + General Format Of Sequence Renaming Tokens ========================================== @@ -1859,6 +1906,10 @@ FIX THISSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS +Let's Learn The Alphabet +======================== + + Count Pattern Format ==================== @@ -1965,6 +2016,26 @@ Explanation +COMMON TASKS AND IDIOMS +----------------------- + +With a program as feature dense as **tren**, it's not +possible to document every possible use case. The following +examples cover many common applictions of the program. + +- Literal String Replacement + +- Changing A File's "Extension" Suffix + +- Appending- Or Prepending Strings To An Existing File Name + +- Ordering File Names By Last Modification Time + +- Ordering File Names By Modification Time Within Date + +- Ordering File Names By Size + + BUGS, MISFEATURES, OTHER ------------------------ @@ -2031,7 +2102,7 @@ :: - $Id: tren.rst,v 1.168 2010/04/01 21:55:53 tundra Exp $ + $Id: tren.rst,v 1.169 2010/04/02 03:15:49 tundra Exp $ You can find the latest version of this program at: