diff --git a/tren.rst b/tren.rst index 080acfe..c06808d 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - tren.py [-acbeghpqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ... + tren.py [-cbefghqtvx] [-l string] [-r old=new]... file|dir file|dir ... DESCRIPTION @@ -30,53 +30,128 @@ file or directory being processed and a warning 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. +rename. You can override this default and *force* a renaming and thus +the removal of such existing files or directories (``-f`` option). -**tren** supports two kinds of renaming operations, *String Substitution* -and *Rename By Template*. +**tren** supports a variety of renaming mechanisms. The one thing +they have in common is that you must specify an *old string* which +will be replaced by a *new string* when the file or directory is +renamed. Each of these can take on one of several forms: + + ---------- ---------- + Old String New String + ---------- ---------- + + Literal Text Literal Text + Regular Expression Literal Text With Templates + Literal Text With Templates + +The sections below describe each of these mechanisms. -String Substition ------------------ +Literal String Substitution +--------------------------- -String substitution is handy when you have files and directories -that have a common set of characters in them you'd like to change. -For instance:: +Literal String Substitution is just that - it replaces one literal +string with another to rename the target file or directory. This is +handy when you have files and directories that have a common set of +characters in them you'd like to change. For instance:: tren.py -r .Jpeg=.jpg *.Jpeg -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. +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. + +You may specify multiple replacement operations (``-r``) on the **tren** +command line:: + + tren.py -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. +name, but you can use the ``-g`` option to replace *all* instances of +the old string with the new one. -Ordinarily **tren** treats both the old string you specify with -the ``-r`` option *literally*. However, it is sometimes handy -to be able to write a regular expression to specify what you -want replaced. If you specify the ``-x`` option, **tren** will -treat your old string as a Python style regex, compile it (or -try to anyway!) and use it to select which strings to replace. -This makes it much easier to rename files that have repeated -characters or patterns, and groups of files that have similar, -but not idential strings in their names you'd like to replace. +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 (``\=``):: + + tren.py -r name\=bob=name\=sally name=bob.dbms + +This renames the file ``name=bob.dbms`` to ``name=sally.dbms``. -Rename By Template ------------------- +Using Regular Expressions +------------------------- -It is sometimes useful to be able to take a group of files/directories -whose names have nothing in common and impose a common naming scheme -on them. For example, suppose you and your friends pool your vacation -photos but each of your cameras uses a slightly different naming -scheme. You might want to just reorder them by the date and time each -picture was taken, for example. That way you end up with one -coherent set of named and numbered files. You might have +Ordinarily **tren** treats both the old string you specify with the +``-r`` option *literally*. However, it is sometimes handy to be able +to write a regular expression to specify what you want replaced. If +you specify the ``-x`` option, **tren** will treat your old string as +a Python style regex, compile it (or try to anyway!) and use it to +select which strings to replace. This makes it much easier to rename +files that have repeated characters or patterns, and groups of files +that have similar, but not idential strings in their names you'd like +to replace. + +Say you have a set of files that are similar, but not idential in +name, and you want to rename them all:: + + sbbs-1.txt + sbbbs-2.txt + sbbbbbbbbs-3.txt + +Suppose you want to rename them, replacing two or more instances of +``b`` with ``X``. It is tedious to have to write a separate literal +``-r old:new`` string substitution for each instance above. This is +where regular expressions can come in handy. When you invoke the +``-x`` option, **tren** understands this to mean that the ``old`` +portion of the replacement option is to be treated as a *Python style +regular expression*. That way, a single string can be used to match +many cases:: + + tren.py -x -r bb+:X *.txt + +This renames the files to:: + + sXs-1.txt + sXs-2.txt + sXs-3.txt + +Keep in mind that a literal string is a subset of a regular +expression. This effectively means that with ``-x`` processing +enabled you can include *both* regular expressions and literal text in +your "old string" specification. The only requirement is that the +string taken as a whole be a valid Python regular expression. If it +is not, **tren** will display an error message to that effect. + +Because Python regular expressions can make use of the ``=`` symbol, +you need a way to distinguish between an ``=`` used in a regular +exression and the same symbol used to separate the old and new +operands for the ``-r`` option. Where this symbol needs to appear in +a regular expression, it has to be escaped like this: ``\=``. + + +An Overview Templates +--------------------- + +**tren** implements the notion of *Renaming Templates*. These can +appear in either the old- or the 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. For example, suppose you and your friends pool +your vacation photos but each of your cameras uses a slightly +different naming scheme. You might want to just reorder them by the +date and time each picture was taken, for example. That way you end +up with one coherent set of named and numbered files. You might have something like this:: DSC002.jpg (Bob's camera, taken 1-5-2010 at noon) @@ -85,20 +160,21 @@ It would be nice to get these in order somehow. -*Rename By Template* provides this ability. Given a list of files, +*Renaming Templates* provide this ability. Given a list of files, you apply a "template" or pattern to be used when renaming them. This -template is nothing more than a string containing both literal -text and so-called *renaming tokens* built into **tren**. +template is nothing more than a string containing so-called *Renaming +Tokens* built into **tren**, and optionally, literal text, and even +regular expressions (old string only). There's a whole section later in this document on template construction and the use of renaming tokens, but here's a simple example to illustrate the general idea using the files above:: - tren.py -T /D/-MyVacation-/0001/.jpeg *.jp* + tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp* This would rename all the files in the current directory ending with ``.jp*``. The ``/D/`` would be replaced with the *date* the picture -was taken. The ``/0001/`` refers to a *starting sequence number* to +was taken. The ``/+T0001/`` refers to a *starting sequence number* to uniquely identify pictures taken on the same date. The other strings in the template, ``-MyVacation-`` and ``.jpeg``, are inserted *literally* in the final file names. After we ran this command, the @@ -109,37 +185,70 @@ 20100105-MyVacation-0002.jpeg (Bob's) Notice that the files taken on the same date have been sequenced by -the time-of-day they were taken because we included the ``/0001/`` -renaming token in our pattern. +the time-of-day they were taken because we included the ``/+T0001/`` +renaming token in our pattern. The ``+`` here means to construct +the sequence in *ascending* order. A ``-`` would specify +*descending* order. There are many other renaming tokens and ways to construct all manner of clever templates. These are discussed below in the section entitled `TEMPLATE CONSTRUCTION`_. -Ordinarily the template text *replaces* the *entire* existing -filename. You can limit the replacement to either the "name" (``-b``) -or "extension" (``-e``) portions of the filename. Instead of -replacing the existing name, extension, or both, you can also choose -to append (``-a``) or prepend ``-p`` the template text. + +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 "match anything" +in the existing file or directory name. If you were using +regular expressions (``-x``) you could do the same thing +with:: + + -r *=/D/-MyVacation-/+T001/.jpeg *.jp* + +Ordinarily the template text replaces the *entire* existing filename +when you do this. You can limit the replacement to either the "name" +(``-b``) or "extension" (``-e``) portions of the filename. + +Of course, you don't *have* to replace the entire filename when +using templates. It's perfectly legitimate to replace only +a portion of the existing name:: + + tren.py -r file=/D/-file file-1 file.2 + +This would rename our files to: ``20100101-file-1 and 20100101-file.2 + +You can even use templates in your *old string* specification. +For instance, suppose you manage a number of different systems +that set their system name in an environment variable called SYSNAME. +You might then do something like this:: + + tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old + +If your system name were "matrix", then the command above would only +rename files in the form ``matrixbku``. If your system name +were "modar", then the command above would only rename files in the +form ``modarbku``. + +There are a couple of things to keep in mind when doing things like +this: + + 1) The ``/$SYSNAME/`` in the old string is used to *find the + text to rename*, whereas the same renaming token in the + new string means *insert the contents of that environment + variable here*. + + 2) Renaming tokens are always evaluated *before* any regular + expression processing takes place. It's up to you to + make sure that when you combine the two (as we have in + the example above), *that the final result is still a + valid Python regular expression*. This may involve + explicit quoting of the renaming tokens used in the old + string specification. + OPTIONS ------- - -T template Rename by template. - - (*Default*: Rename via string replacement.) - - Use a template to rename the file. This is discussed in - detail in the `TEMPLATE CONSTRUCTION`_ section below. - - -a Append the template text to the existing file or directory - name. - - (*Default*: Replace the file or directory name with the - template text.) - - -b Only perform renaming within "name" portion of file or directory name. @@ -185,6 +294,12 @@ tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg + -f Force renaming even if target file or directory name already + exists. + + (*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 with the new. @@ -224,13 +339,6 @@ this, no renaming of characters *within* the separator takes place. - -p Prepend the template text to the existing file or directory - name. - - (*Default*: Replace the file or directory name with the - template text.) - - -q Quiet mode, do not show progress. (*Default*: Display progress) @@ -287,42 +395,6 @@ (*Default*: Treat the old string as literal text) - String substitution arguments to the ``-r`` option are usually - understood to be taken literally. There are, however, instances - where this is tedius to do. Say you have a set of files - that are similar, but not idential in name, and you want to - rename them all:: - - sbbs-1.txt - sbbbs-2.txt - sbbbbbbbbs-3.txt - - Suppose you want to rename them, replacing two or more instances - of ``b`` with ``X``. It is tedious to have to write a separate - ``-r old:new`` string substitution for each instance above. - This is where regular expressions can come in handy. When you - invoke the ``-x`` option, **tren** understands this to mean that - the ``old`` portion of the replacement option is to be treated as - a *Python style regular expression*. That way, a single string - can be used to match many cases:: - - tren.py -x -r bb+:X *.txt - - This renames the files to:: - - sXs-1.txt - sXs-2.txt - sXs-3.txt - - **tren** only accepts Python style regular expressions. Anything - else will cause an error message to be displayed. - - Because Python regular expressions can make use of the ``=`` - symbol, you need a way to distinguish between an ``=`` used in a - regular exression and the same symbol used to separate the old - and new operands for the ``-r`` option. Where this symbol needs to - appear in a regular expression, it has to be escaped like this: - ``\=``. TEMPLATE CONSTRUCTION @@ -445,7 +517,7 @@ type: D sequence on file creation date & time - O sequence on the command line file order + R sequence on the command line file order S sequence on file size T sequence on file creation time within a given day @@ -553,14 +625,6 @@ tren.py -e -T /D/ file.1 # file.20100112 - Append template text:: - - tren.py -a -T ./D/ file.1 # file.1.20100112 - - Prepend template text:: - - tren.py -p -T /D/- file.1 # 20100112-file.1 - Get help:: tren.py -h @@ -608,7 +672,7 @@ :: - $Id: tren.rst,v 1.121 2010/01/18 23:43:36 tundra Exp $ + $Id: tren.rst,v 1.122 2010/01/19 20:48:10 tundra Exp $ You can find the latest version of this program at: