diff --git a/tren.rst b/tren.rst index 07cf870..735040f 100644 --- a/tren.rst +++ b/tren.rst @@ -11,240 +11,6 @@ tren.py [-cbefghqtvx] [-l string] [-r old=new]... file|dir file|dir ... -DESCRIPTION ------------ - -.. WARNING:: **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 could happen. You have been warned! - -**tren** is a general purpose file and directory renaming tool. Unlike -commands like ``mv``, **tren** is particularly well suited for -renaming *batches* of files and/or directories with a single command -line invocation. **tren** eliminates the tedium of having to script -simpler tools to provide higher-level renaming capabilities. - -**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 -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 -the removal of such existing files or directories (``-f`` option). - -**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. - - -Literal String Substitution ---------------------------- - -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. - -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. - -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``. - - -Using Regular Expressions -------------------------- - -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) - 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. - -*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 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 -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 ``/+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 -files above would end up with these names:: - - 20100103-MyVacation-0001.jpeg (Sid's) - 20100105-MyVacation-0001.jpeg (Mary's) - 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 ``/+T0001/`` -renaming token in our pattern. The ``+`` here means to construct -the sequence in *ascending* order. A ``-`` would specify -*descending* order. - -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 ``matrix.bku``. If your system name -were "modar", then the command above would only rename files in the -form ``modar.bku``. - -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. - - -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`_. - - OPTIONS ------- @@ -396,19 +162,265 @@ -TEMPLATE CONSTRUCTION ---------------------- +DESCRIPTION +----------- -Template based renaming is used when you want to impose a naming +.. WARNING:: **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 could happen. You have been warned! + +**tren** is a general purpose file and directory renaming tool. Unlike +commands like ``mv``, **tren** is particularly well suited for +renaming *batches* of files and/or directories with a single command +line invocation. **tren** eliminates the tedium of having to script +simpler tools to provide higher-level renaming capabilities. + +**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 +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 +the removal of such existing files or directories (``-f`` option). + +**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. The general form is:: + + tren.py -r old=new + + +The ``old`` and ``new`` string are built using a variety of +building blocks: + + ============================= ============================= + *Old Strings Are Built With:* *New Strings Are Built With:* + ----------------------------- ----------------------------- + + Literal Text Literal Text + Regular Expressions Renaming Tokens + Renaming Tokens + ============================= ============================= + + +You can use any of these building blocks alone or combine them +to create expressive and powerful renaming schemes. + + +Literal String Substitution +--------------------------- + +Literal String Substitution is just that - it replaces one literal +string with another to rename the target file or directory. This is +the most common, and simplest way to use **tren**. 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 + +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. + +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. + +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``. + + +Using Regular Expressions +------------------------- + +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 must 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 Renaming Tokens +--------------------------- + +**tren** implements the notion of *Renaming Tokens*. 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. 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. + +In their simplest form, renaming tokens are nothing more than +"canned" information **tren** knows about a particular file or +directory. For instance, if you insert the ``/D/`` token into a +old- or new string definition, **tren** will replace it with *the +creation date of the file or directory being renamed* and use that +string in the renaming process. + +There are also tokens that can be used to automatically renumber or +sequence a set of files or directories being renamed. Finally, there +are tokens that allow you to use system information in your renaming +strings. + +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) + 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: + + 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 ``/+T0001/`` refers to a *starting sequence number* to +uniquely identify pictures taken on the same date. The other strings, +``-MyVacation-`` and ``.jpeg``, are inserted *literally* in the final +file names. After we ran this command, the files above would end up +with these names:: + + 20100103-MyVacation-0001.jpeg (Sid's) + 20100105-MyVacation-0001.jpeg (Mary's) + 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 ``/+T0001/`` +renaming token in our pattern. The ``+`` here means to construct +the sequence in *ascending* order. A ``-`` would specify +*descending* order. + +.. 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 "match anything" + in the existing file or directory name. You can do + the same thing using a regular expression:: + + tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp* + +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:: + + tren.py -r file=/D/-file file-1 file.2 + +This would rename our files to: ``20100101-file-1 and +20100101-file.2`` Notice that we combined literal text and a renaming +token to do this. + +You can even use renaming tokens 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 was "matrix", then the command above would only +rename files whose names began with ``matrix`` and ended with ``.bku``. +If your system name were "morton", then the command above would only +rename files whose names began with ``morton`` and ended with ``.bku``. + +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. + + +**tren** has many other kinds of renaming tokens. Their +structure and use is described in some detail in the +section below entitled, `RENAMING TOKENS`_. + + +RENAMING TOKENS +--------------- + +Token based renaming is used when you want to impose a naming "pattern" on a group of files or directories. This is most useful when the existing filenames have little or nothing in common. In such situations, there's often no direct way to use string substitutions to order the names in some coherent way. -A "template" is built from literal text and *renaming tokens*. These +A "token" is built from literal text and *renaming tokens*. These tokens are delimited by the ``/`` character. **tren** replaces these tokens with corresponding information (see descriptions below) to -produce a final "template text". The template text is the actual +produce a final "token text". The token text is the actual string used to either replace the existing file or directory name (or just the "name" or "extension" portions, depending on which options you've selected) or to be appended or prepended to the name. @@ -416,7 +428,7 @@ Currently, **tren** defines a number of renaming tokens. File Attribute Renaming Tokens ------------------------------- +--------------------------------- These tokens are derived from information about the file or directory being renamed. @@ -474,7 +486,7 @@ Sequence Renaming Tokens ------------------------- +--------------------------- 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 @@ -541,7 +553,7 @@ You are not restricted to numbers in a counting pattern. Letters may also be used. **tren** will preserve the case you specify in the -template when creating sequences like this:: +token when creating sequences like this:: 000a -> 000a, 000b, 000c, ... zzzz, 000a, ... ---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ... @@ -552,7 +564,7 @@ System Related Renaming Tokens ------------------------------- +--------------------------------- These tokens are derived from the underlying operating system and runtime environment. @@ -612,15 +624,15 @@ tren.py -r a\=b=c\=d a=b.txt # c=d.txt - Use template:: + Use renaming token:: tren.py -T /I/ file.1 # 2010-01-12 - Use template to change file "name":: + Use renaming token to change file "name":: tren.py -b -T /I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2 - Use template to change file "extension":: + Use renaming token to change file "extension":: tren.py -e -T /D/ file.1 # file.20100112 @@ -671,7 +683,7 @@ :: - $Id: tren.rst,v 1.124 2010/01/19 20:52:14 tundra Exp $ + $Id: tren.rst,v 1.125 2010/01/20 00:26:22 tundra Exp $ You can find the latest version of this program at: