| |
---|
| | operations. Once you've got a sense of what |
---|
| | **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 |
---|
| | line. This turns on the "test mode" and will show you |
---|
| |
---|
| | |
---|
| | 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 |
---|
| | have been warned! |
---|
| |
---|
| | |
---|
| | 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 |
---|
| | |
---|
| |
---|
| | |
---|
| | 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 |
---|
| | *what order* you specify both renaming requests *and* the files- and |
---|
| |
---|
| | An Overview Of Renaming Tokens |
---|
| | ============================== |
---|
| | |
---|
| | **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, |
---|
| | owner's name, and so on. This is the purpose of renaming tokens. |
---|
| |
---|
| | directory being renamed was last modified* and use that string in the |
---|
| | renaming process:: |
---|
| | |
---|
| | 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 |
---|
| |
---|
| | dc0234.Jpg # Mary's camera, taken 1-5-2010 at 8am |
---|
| | 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):: |
---|
| | |
---|
| | tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp* |
---|
| | |
---|
| | 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 |
---|
| | ``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the |
---|
| |
---|
| | |
---|
| | .. 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 |
---|
| | a portion of the existing name:: |
---|
| |
---|
| | Most commonly, you'll find yourself using the command line, |
---|
| | 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 |
---|
| | work the same way as Unix-derived OSs do. In particular, if |
---|
| |
---|
| | requests only apply to some of the file names you passed on the |
---|
| | 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 |
---|
| | ================================= |
---|
| |
---|
| | |
---|
| | ``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 |
---|
| | are identically named, except that the first letter of each of the |
---|
| |
---|
| | |
---|
| | |
---|
| | ``/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 |
---|
| | renaming operation will generate a new name that |
---|
| |
---|
| | ======================== |
---|
| | |
---|
| | 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 |
---|
| | embedding the date and time of creation in a file or directory name, |
---|
| |
---|
| | |
---|
| | This is the purpose of *sequence renaming tokens*. They give you |
---|
| | 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 |
---|
| | ========================================== |
---|
| | |
---|
| |
---|
| | |
---|
| | FIX THISSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS |
---|
| | |
---|
| | |
---|
| | Let's Learn The Alphabet |
---|
| | ======================== |
---|
| | |
---|
| | |
---|
| | Count Pattern Format |
---|
| | ==================== |
---|
| | |
---|
| | The counting pattern is used to specify two things: The width of the |
---|
| |
---|
| | |
---|
| | ``/+-USER:Alphabet:FormatField/ Sequence based on`` |
---|
| | |
---|
| | 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 |
---|
| | ------------------------ |
---|
| |
---|
| | ----------------------------- |
---|
| | |
---|
| | :: |
---|
| | |
---|
| | $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: |
---|
| | |
---|
| | http://www.tundraware.com/Software/tren |
---|
| |
---|
| | |