diff --git a/tren.rst b/tren.rst index e9fc809..4a54cb8 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - tren.py [-1aCcbefghqtvXx] [-F file] [-l string] [-r old=new]... file|dir file|dir ... + tren.py [-1aCcbEefghqtvXx] [-F file] [-l string] [-r old=new]... file|dir file|dir ... OPTIONS @@ -22,6 +22,9 @@ its default behavior after a previous ``-g`` on the command line. + This option is ignored during regular expression processing + (``-x``). + -a Rename within the entire file or directory name (*Default*: This is the program default) @@ -40,7 +43,7 @@ in the entire filename *including* the extension. For example doing this:: - tren.py -g -r eg=ug peg.jpeg + tren.py -g -r e=u peg.jpeg # -g = "rename all" Renames the file to ``pug.jpug`` .. probably not what you want. @@ -48,7 +51,7 @@ in the actual "name portion" of the filename thereby cirumventing problems like this:: - tren.py -g -b -r eg=ug peg.jpeg # Renames file to pug.jpeg + tren.py -g -b -r e=u peg.jpeg # Renames file to pug.jpeg -C Do case-sensitive renaming @@ -58,6 +61,9 @@ its default behavior after a previous ``-c`` on the command line. + This option is ignored during regular expression processing + (``-x``). + -c Collapse case when doing string substitution. (*Default*: Search for string to replace is case sensitive) @@ -72,6 +78,9 @@ respectively. Notice that the new (replacement) string's case is preserved. + This option is ignored during regular expression processing + (``-x``). + -e Only perform renaming within "extension" portion of or directory name. @@ -83,6 +92,10 @@ tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg + -E Continue renaming even after an error is encountered + + (*Default*: Stop processing after any error) + -F file Read command line arguments from ``file`` It is possible to perform multiple renaming operations in one @@ -107,7 +120,6 @@ # Each line appended sequentially # to the command line - -x -r t[ext]+=txt # Appended first -c -g my=Mine -X @@ -119,10 +131,10 @@ .. NOTE:: There is one important difference between an actual command line and keeping the arguments in a file like this. *Filename wildcards are not expanded within the - file.* ``*.txt`` will typicaly create a list of files - ending in ``.txt`` when given on the command line. - However, the ``*`` metacharacter has no meaning like this - when used inside an arguments file. + file.* ``*.txt`` will typically be expanded by a command + shell to create a list of files ending in ``.txt``. + However, the ``*`` metacharacter has no such meaning when + used inside an arguments file. -f Force renaming even if target file or directory name already exists. @@ -130,7 +142,7 @@ (*Default*: Skip renaming if a file or directory already exists by the same name as the target.) - -g Replace all instances (greedy replace) of the old string + -g Replace all instances (global rename) of the old string with the new. (*Default*: Only the first matching string is replaced.) @@ -139,10 +151,13 @@ instance of a string in the entire filename (default), the name portion (``-b``) or the extension (``-e``). If you want *all* instances of a particular string replaced, use this - option to enable "greedy" replacement:: + option to enable "global" renaming:: tren.py -g -r p:P pop.txp # Renames file to: PoP.txP + This option is ignored during regular expression processing + (``-x``). + -h Print help information. @@ -157,7 +172,7 @@ for renaming purposes, using any string you like. This is particularly helpful with ``-b`` and ``-e`` options:: - tren.py -b -l .long.txt -r long:short long.long.txt.long.txt.foo + tren.py -g -b -l .long.txt -r long:short long.long.txt.long.txt.foo This would rename the file to:: @@ -252,7 +267,7 @@ **tren** will not allow you to rename a file or directory if one with the new name already exists. Such attempts will cause no change to the -file or directory being processed and a warning message will be +file or directory being processed and an error message will be displayed. This is intentional to force you to manually rename or remove the file or directory that would have been clobbered by a rename. You can override this default and *force* a renaming and thus @@ -266,7 +281,7 @@ tren.py -r old=new -The ``old`` and ``new`` string are built using a variety of +The ``old`` and ``new`` renaming strings are built using a variety of building blocks: ============================= ============================= @@ -295,25 +310,24 @@ tren.py -r .Jpeg=.jpg *.Jpeg This would rename all files (or directories) whose names contained the -string ``.Jpeg`` and replace it with ``.jpg``. It's important to -realize that such a substitution takes place *anywhere* in the file -name, not just at the end or "extension" (as it is called in Windows). -You can limit the replacement to just the "name" (``-b``) or -"extension" (``-e``) portions of the filename. +string ``.Jpeg`` and replace it with ``.jpg``. Well ... that's not +quite right. Unless you specify the ``-g`` option, *only the first +(leftmost) instance of ``old`` is replaced with ``new``*. + +It's important to realize that such a substitution takes place +*anywhere* in the file name, not just at the end or "extension" (as it +is called in Windows). You can limit the replacement to just the +"name" (``-b``) or "extension" (``-e``) portions of the filename. You may specify multiple replacement operations (``-r``) on the **tren** command line:: - tren.py -r .Jpeg=.jpg -r old=ReallyOld * + tren.py -g -r .Jpeg=.jpg -r old=ReallyOld * This would rename all the files in the current directory, replacing ``.Jpeg`` with ``.jpg`` and ``old`` with ``ReallyOld`` anywhere these strings appeared in any of the file or directory names. -By default, only the first instance of the string is replaced in the -name, but you can use the ``-g`` option to replace *all* instances of -the old string with the new one. - If you need to include the equals sign as part of the old string or the new string literal text, you have to escape it (``\=``):: @@ -372,12 +386,22 @@ operands for the ``-r`` option. Where this symbol needs to appear in a regular expression, it has to be escaped like this: ``\=``. +Regular expression processing is unaffected by the ``-g / -1`` (global +rename) and ``-c / -C`` (ignore case) options. That's because there +are regular expression mechanisms for achieving the same thing. More +importantly, if you've selected regular expression matching, it's +probably because you want very fine grained control of the renaming +defined by the regex. In short, regular expression matching always +takes place on the *original characters* of the target portion of the +name and does replacement as called for in the regex itself. + + An Overview Of Renaming Tokens ------------------------------ **tren** implements the notion of *Renaming Tokens*. These can -appear in either the old- or the new string components of a ``-r`` +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 @@ -481,13 +505,13 @@ **tren** has many other kinds of renaming tokens. Their structure and use is described in some detail in the -next section. +section below entitled `RENAMING TOKENS: THE GORY DETAILS`_. COMMAND LINE TOGGLES -------------------- -**tren** defaults a specific set of behaviors: +**tren** defaults to a specific set of behaviors: - ``old`` and ``new`` renaming text is treated *literally* - Renaming takes place within *the entire filename* @@ -525,19 +549,16 @@ works, particularly if you intend to create complex, multi-replacement command lines: - - Command line processing is from left to right. As we saw in the + - Command line processing is from left to right. As we saw in the `COMMAND LINE TOGGLES`_ above, this means the options can be different for each renaming operating you specify. - Regular expression processing is unaffected by the ``-g / -1`` - (greedy replace) and ``-c / -C`` (ignore case) options. That's - because there are regular expression mechanisms for achieving the - same thing. More importantly, if you've selected regular - expression matching, it's probably because you want very fine - grained control of the renaming defined by the regex. In short, - regular expression matching always takes place on the *original - characters* of the target portion of the name and does replacement - as called for in the regex itself. + (global rename) and ``-c / -C`` (ignore case) options. + + - Filenames may be absolute, relative, or implict (to the current + working directory). **tren** keeps track of this and can do + renaming in directories other than the current one. - **tren** processes each renaming string in the following manner: @@ -548,19 +569,43 @@ 2) Replace all renaming tokens with their equivalent text in both the ``old`` and ``new`` renaming strings. - 3) If ``-c`` is in effect, collapse the target and the ``old`` - renaming string to *lower case* before checking for a match. + 3) If doing literal string replacement: - 4) Replace the first- (default and ``-1``) or all (``-g``) instances - of ``old`` with ``new``. + - If ``-c`` is in effect, collapse the target and the ``old`` + renaming string to *lower case* before checking for a match. + + - Replace the first- (default and ``-1``) or all (``-g``) + instances of ``old`` with ``new``. 4) + + 4) If doing regular expression processing, replace any regex + matches with the corresponding ``new`` string. Keep in mind + that if ``-x`` is selected the *entire* ``old`` string is + treated as a Python regular expression. Pay particular + attention to this if you're combing literal text and/or + renaming templates with regular expression metacharacters. + + - When all the renaming operations are complete - and thus a new filename + has been constructed - **tren** checks to see if a file or directory + by that name already exists. Unless the ``-f`` flag is in force, + **tren** will refuse to do a renaming *over an existing filename*. + If the new filename does not exist, **tren** will attempt the + renaming. If the rename fails for some reason - say you don't + have permission to rename a particular file or directory - you'll + see an error message to that effect. + + - By default, **tren** will stop processing on any error. You + can override this with the ``-E`` option. In that case, + an error message will be displayed. No matter what caused + the error, **tren** will skip the file currently being processed + and go on to the next one. RENAMING TOKENS: THE GORY DETAILS --------------------------------- As we've just seen, a *Renaming Token* is nothing more than -a string representing something **tren** knows about one of -three things: +a string representing something **tren** knows about. These +fit in one of three categories: - An attribute of the file or directory being renamed - An attribute of the underling operating system environment @@ -589,6 +634,16 @@ of the file or directory being renamed. It is in ``yyyymmdd`` format. +``/dd/ File or directory day of creation`` + + This token is replaced with the the day of the month the + file was created in ``dd`` format. + +``/dy/ File or directory day of creation`` + + This token is replaced with the the name of the day the + file was created in ``Ddd`` format. + ``/E/ Original File Extension`` This token is replaced the "extension" portion of the file @@ -609,11 +664,16 @@ This token is replaced with the name of the primary group to which the file belongs. +``/hh/ File or directory hour of creation`` + + This token is replaced with the hour the file was + created in ``hh`` format. + ``/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``. + except it is in ISO format, ``YYYY-MM-DD``. ``/L/ File or directory length`` @@ -621,48 +681,38 @@ that indicates the length of the file or directory in bytes. +``/mm/ File or directory minutes of creation`` + + This token is replaced with the minutes the file was + created in ``mm`` format. + +``/mo/ File or directory month of creation`` + + This token is replaced with the numeric month the file was + created in ``mm`` format. + +``/my/ File or directory month of creation`` + + This token is replaced with the abbreviated name of the + month the file was created in ``Mmm`` format. + +``/ss/ File or directory seconds of creation`` + + This token is replaced with the seconds the file was + created in ``ss`` format. + ``/T/ File or directory creation time`` - This token is replaced with the time of creation - of the file or directory being renamed. It is - in ``hh:mm:ss`` format. + This token is replaced with the time of creation of the + file or directory being renamed. It is in ``hh:mm:ss`` + format. This is equivalent to ``/hh/:/mm/:/ss/``. ``/U/ File or directory owner name`` This token is replaced with the name of the 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`` +``/yyyy/ File or directory year of creation`` This token is replaced with the year the file was created in ``yyyy`` format. @@ -691,7 +741,7 @@ ``/`cmd`/ Arbitrary command execution`` - This token is replaced with the text + This token is replaced with the string returned by executing the ``cmd`` command. For instance, you might want to prepend the name @@ -721,7 +771,7 @@ 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/``, -``/T/``, and ``/S/`` renaming tokens described in the previous section. +``/L/``, and ``/T/`` renaming tokens described in the previous section. An extension of this idea is to *order all the files being renamed* based on one of these parameters. For instance, instead of actually @@ -962,10 +1012,9 @@ BUGS AND MISFEATURES -------------------- -On windows platforms, the ``/U/`` and ``/G/`` renaming tokens return -``winuser`` and ``wingroup`` respectively. They do not return the -underlying operating system ownership information. - +On windows platforms, the ``/U/`` and ``/G/`` do not return the +underlying operating system ownership information.. They return +``winuser`` and ``wingroup`` respectively. COPYRIGHT AND LICENSING ----------------------- @@ -993,7 +1042,7 @@ :: - $Id: tren.rst,v 1.130 2010/01/20 22:26:26 tundra Exp $ + $Id: tren.rst,v 1.131 2010/01/20 23:50:20 tundra Exp $ You can find the latest version of this program at: