diff --git a/tren.rst b/tren.rst index 1f60ac3..3480d19 100644 --- a/tren.rst +++ b/tren.rst @@ -20,7 +20,7 @@ .. WARNING:: **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 + **tren** operations with the ``-t`` option on the command line. This turns on the "test mode" and will show you what the program *would* do without actually doing it. It goes without saying that you should be even more @@ -47,7 +47,7 @@ You may specify *tren* options in one of three ways: 1) On the command line - 2) In an "include" file specified with '``-I filename``' on the command line + 2) In an "include" file specified with ``-I filename`` on the command line 3) Via the ``$TREN`` environment variable Options specified on the command line are evaluated from left to right @@ -56,7 +56,7 @@ options". All options must precede the list of files and/or directories being -renamed. If one of your rename targets start with the '``-``' +renamed. If one of your rename targets start with the ``-`` character, most command shells recognize the double dash as an explicit "end of options" delimiter:: @@ -68,8 +68,8 @@ options are "toggles", they can be turned on- and off as you move from left- to right on the command line. In this way, certain options (like case sensitivity, regular expression handling, and so on) can be -set differently for each individual renaming request ('``-r``'). (If -you're very brave, you can select the '``-d``' option to do a debug +set differently for each individual renaming request (``-r``). (If +you're very brave, you can select the ``-d`` option to do a debug dump. Among many other things, the **tren** debugger dumps the state of each renaming request, and what options are in effect for that request.) @@ -79,7 +79,7 @@ ======= -A alphabet Install a user-defined "alphabet" to be used by - Sequence Renaming Tokens. + sequence renaming tokens. (*Default*: Built-in alphabets only) @@ -104,7 +104,7 @@ (*Default*: off) If you invoke this option, **tren** will prompt you before - renaming each file. The default (if you just hit '``Enter``') + renaming each file. The default (if you just hit ``Enter``) is to *not* rename the file. Otherwise, you have the following options:: @@ -115,7 +115,7 @@ These options are all insensitive to case. - If you're doing forced renaming ('``-f``'), this option will + If you're doing forced renaming (``-f``), this option will interactively ask you first about making any necessary backups and then renaming the original target. *If you decline to do the backup renaming, but accept the renaming of the original @@ -127,11 +127,11 @@ (*Default*: This is the program default) This option is provided so you can toggle the program back to - its default behavior after a previous '``-c``' on the command + its default behavior after a previous ``-c`` on the command line. This option is observed both for literal and regular - expression-based renaming ('``-x``'). . + expression-based renaming (``-x``). . -c Collapse case when doing string substitution. @@ -148,7 +148,7 @@ is preserved. This option is observed both for literal and regular - expression-based renaming ('``-x``'). + expression-based renaming (``-x``). -d Dump debugging information @@ -161,7 +161,7 @@ encountered on the command line*. For maximum debug output, place this as the last (rightmost) option on the command line, right before the list of files and directories to rename. You - can also place multiple '``-d``' options on the command line to + can also place multiple ``-d`` options on the command line to see how the internal tables of the program change as various options are parsed. @@ -176,7 +176,7 @@ forces the renaming to take place. However, the old file or directory is not lost. It is merely renamed itself first, by appending a suffix to the original file name. (*Default*: - .backup, but you can change it via the '``-S``' option.) This + .backup, but you can change it via the ``-S`` option.) This way even forced renames don't clobber existing files or directories. @@ -186,13 +186,13 @@ -I file "Include" command line arguments from ``file`` It is possible to perform multiple renaming operations in one - step using more than one '``-r``' option on the **tren** command + step using more than one ``-r`` option on the **tren** command line. However, this can make the command line very long and hard to read. This is especially true if the renaming strings - are complex, contain regular expressions or renaming - tokens, or if you make heavy use of command line toggles. + are complex, contain regular expressions or Renaming + Tokens, or if you make heavy use of command line toggles. - The '``-I``' option allows you to place any command line + The ``-I`` option allows you to place any command line arguments in a separate *file* in place of- or in addition to the **tren** command line and/or the ``$TREN`` environment variable. This file is read one line at a time and the @@ -233,25 +233,25 @@ (*Default*: 0 or leftmost) A file may have multiple instances of the "old" - renaming string in it. The '``-i``' option lets you + renaming string in it. The ``-i`` option lets you specify which of these (one, several, all) you'd like to have replaced. Suppose you have a file called - '``foo1-foo2-foo3.foo4``'. The leftmost ``foo`` is - instance 0. The rightmost '``foo``' is instance 3. + ``foo1-foo2-foo3.foo4``. The leftmost ``foo`` is + instance 0. The rightmost ``foo`` is instance 3. You can also refer to instances relative to the right. So the -1 instance is the last (rightmost), -2, second from the last, and so forth. A "range" of instances is specified - using the '``:``' separator in the form:: + using the ``:`` separator in the form:: -i first-to-replace:stop-here All instances from the "first-to-replace" up to, *but NOT including* "the stop-here" - are replaced. '``-i :``' means "replace + are replaced. ``-i :`` means "replace *all* instances. Examples:: @@ -271,8 +271,8 @@ tren.py -i : -r f=b foo1-foo2-foo3.foo4 -> boo1-boo2-boo3.boo4 - -P char Use '``char``' as the escape symbol. - (*Default*: '``\``') + -P char Use ``char`` as the escape symbol. + (*Default*: ``\``) -q Quiet mode, do not show progress. @@ -280,39 +280,39 @@ Ordinarily, **tren** displays what it is doing as it processes each file. If you prefer to not see this "noisy" output, use - the '``-q``' option. Note that this does not suppress warning + the ``-q`` option. Note that this does not suppress warning and error messages. It doesn't make much sense to use this option in test mode - ('``-t``'), although you can. The whole point of test mode is + (``-t``), although you can. The whole point of test mode is to see what would happen. Using the quiet mode suppresses that output. - -R char Use '``char``' as the separator symbol in renaming + -R char Use ``char`` as the separator symbol in renaming specifications. - (*Default*: '``=``') + (*Default*: ``=``) - -r Replace '``old``' with '``new``' in file or directory + -r Replace ``old`` with ``new`` in file or directory names. Use this option to specify which strings you want to replace in each file name. These strings are treated - literally unless you also invoke the '``-x``' option. In - that case, '``old``' is treated as a Python style + literally unless you also invoke the ``-x`` option. In + that case, ``old`` is treated as a Python style regular expression. - Both '``old``' and '``new``' may optionally contain - *Renaming Tokens* described later in this document. + Both ``old`` and ``new`` may optionally contain + *renaming tokens* described later in this document. - If you need to use the '``=``' symbol *within* either - the old or new string, simply escape it: '``\=``' + If you need to use the ``=`` symbol *within* either + the old or new string, simply escape it: ``\=`` If it is convenient, you can change the separator - character to something other than '``=``' via the - '``-R``' option. Similarly, you can change the - escape character via the '``-P`` option. + character to something other than ``=`` via the + ``-R`` option. Similarly, you can change the + escape character via the ``-P`` option. You can have multiple instances of this option on your **tren** command line:: @@ -332,10 +332,10 @@ tren.py -cr A=bb -Cr B=cc ... - The '``A=bb``' replacement would be done without - regard to case (both '``A``' and '``a``' would match), - where as the '``B=cc``' request would only replace - '``B``'. + The ``A=bb`` replacement would be done without + regard to case (both ``A`` and ``a`` would match), + where as the ``B=cc`` request would only replace + ``B``. -S suffix Suffix to append when making backup copies of existing targets. @@ -343,10 +343,10 @@ (*Default*: .backup) If you choose to force renaming if files when the new - name already exists ('``-f``'), **tren** simply renames + name already exists (``-f``), **tren** simply renames the existing file or directory by appending a suffix to - it. By default, this suffix is '``.backup``, but you - can change it to any string you like with the '``-S``` + it. By default, this suffix is ``.backup``, but you + can change it to any string you like with the ``-S``` option. -t Test mode, don't rename, just show what the program *would* do. @@ -390,10 +390,10 @@ (*Default*: This is the program default) This option is provided so you can toggle the program back to - its default behavior after a previous '``-x``' on the command + its default behavior after a previous ``-x`` on the command line. - -x Treat the old string in a '``-r``' replacement as a Python + -x Treat the old string in a ``-r`` replacement as a Python style regular expression for matching purposes. (*Default*: Treat the old string as literal text) @@ -406,14 +406,20 @@ .. WARNING:: 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 + with the ``-t`` option) to see what would happen. You have been warned! +The following sections are designed for the new- or occasional +**tren** user. They begin with the simplest of **tren** operations +and incrementally build more- and more complex examples, eventually +describing all of **tren**'s capabilities. + + Overview ======== **tren** is a general purpose file and directory renaming tool. Unlike -commands like '``mv``', **tren** is particularly well suited for +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. @@ -423,32 +429,56 @@ expression pattern. You can replace any single, group, or all instances of a given string in a file or directory name. -**tren** implements the idea of a "Renaming Token" which is -a symbolic variable that is resolved at runtime to create a new -file name. Renaming Tokens allow you to embed information about -the file's time or length, the contents of an environment variable, -and even the output of an arbitrary command line program into the new -name of a file. +**tren** implements the idea of a "renaming token". These are special +names you can embed in your renaming requests that represent things +like the file's original name, its length, date of creation, and so +on. There are even renaming tokens that will substitute the content +of any environment variable or the results of running a program from a +shell back into the new file name. **tren** can automatically generate *sequences* of file names based on their dates, lengths, times within a given date, and so on. In fact, sequences can be generated on the basis of any of the file's -'``stat``' information. Sequence "numbers" can be ascending or +``stat`` information. Sequence "numbers" can be ascending or descending and the count can start at any initial value. Counting can take place in one of several internally defined counting "alphabets" (decimal, hex, octal, alpha, etc.) OR you can define your own counting alphabet. This allows you to create sequences in any base (2 or higher please :) using any symbol set for the count. -**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 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 via the -'``-f``' option. This will cause the orginal file or directory itself -to be renamed with a '``.backup``' suffix. You can change this -suffix via the '``-S``' option. + +A Word About Program Defaults +============================= + +**tren** has many options, but its defaults are designed to do +two things: a) Simplify the most common operations by making +them the default (no options required on the command line), and +2) Reduce the risk of accidentally modifying more of the file name +than you intented. So, by default: + + **tren** treats renaming requests *literally*. That is, the "old + string" you specify for replacement is treated as literal text. It + requires a command line option (``-x``) to treat it as a regular + expression. *However*, any renaming tokens found in either the old- + or new strings of a renaming request *are* interpreted before the + renaming takes place. + + **tren** renaming is *case sensitive*. If you want to ignore case, + use the ``-c`` option. + + **tren** will only replace the *first (leftmost) instance* of "old + string" with "new string". If you want more- or different instances + replaced, use the ``-i`` option. + + **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 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 via the ``-f`` option. This will cause the orginal file or + directory itself to be renamed with a ``.backup`` suffix. You can + change this suffix via the ``-S`` option. Getting Help @@ -464,7 +494,7 @@ intended as a debugging tool for people maintaining **tren** but it does provide considerable information on the internal state of the program that advanced - users may like. + users may find useful. -h Prints a summary of the program invocation syntax and all the available options and then exits. @@ -482,31 +512,87 @@ -q Set's "quiet" mode and suppresses everthing except error messages. - -w # Tells **tren** to wrap lines after '``#``' characters - have been printed. If you're capturing output to - a log, set this to a very high number like 999 to - inhibit line wrapping. + -w # Tells **tren** to wrap lines after ``#`` characters have been + printed. If you're capturing output to a log, set this to a + very high number like 999 to inhibit line wrapping. -Error and debug messages are sent to '``stderr``'. Normal -informational messages are sent to '``stdout``'. If you -want to capture them both in a log, try something like -this (depending on your OS and/or shell):: +Error and debug messages are sent to ``stderr``. Normal informational +messages are sent to ``stdout``. If you want to capture them both in +a log, try something like this (depending on your OS and/or shell):: tren.py ..... 2>&1 >tren.log +Managing Complexity +=================== -Renaming Building Blocks -======================== +As you learn more of the program features, the **tren** command line +can get long, complex, and easy to goof up. It's also hard to +remember all the various options, how they work exactly, and which +specific one you need. For this reason, it is *highly* recommended +that - once you have a renaming request working the way you like - if +you plan to use it again, save it as an "include" file. That +way you can reuse it easily without having to keep track of the +details over and over. Instead of this:: + + tren.pu -c -i -1 -r .jpeg=.jpg file ... + +Do this:: + + tren.py -I jpeg-to-jpg.tren file... + +What's in the ``jpeg-to-jpg.tren`` file? Just this:: + + # tren Command Line + # Converts '.jpeg' (in any case mixture) file name suffix to '.jpg' + + # Make the replacement case-insensitive + -c # Reset this later on the command line with -C + + # Only replace the rightmost instance + -i -1 + + # The actual replacement request + -r .jpeg=.jpg + + +Notice that you can stick comments in the file anywhere you like and +that they begin with ``#``. Notice also that the various options +can be entered on separate lines so it's simpler to read the include +file. + +If you find yourself using certain options most- or every time you use +the program, you can put them in the **$TREN** environment variable. +**tren** picks this up every time it starts. This minimizes errors +and reduces typing tedium. Just keep in mind that some options can be +overriden later on a command line, and some cannot. For instance, +suppose you do this:: + + export TREN=-f -c + +The ``-c`` option to ignore case can be undone on the command line +with a ``-C`` option. However, the ``-f`` option cannot be undone. + +So ... choose the options you want to make permanent in the +environment variable wisely. + + +Renaming Basics +=============== **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:: +they have in common is that they're built with one or more *renaming +requests* that will be applied to one or more file- or directory +names. Renaming requests look like this on the **tren** command +line:: - tren.py -r old=new + tren.py ... -r old=new ... -r old=new ... list of files/directories +No matter how complicated they look, the basic logic of the +renaming request stays the same: "When you find the string +``old`` in the file- or directory name, change it to the string +``new``. -The '``old``' and '``new``' renaming strings are built using a variety of +The ``old`` and ``new`` renaming strings are built using a variety of building blocks: ============================= ============================= @@ -535,12 +621,12 @@ tren.py -r .Jpeg=.jpg *.Jpeg This would rename all files (or directories) whose names contained the -string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's -not quite right. Unless you specify otherwise with the '``-i``' -option, *only the first (leftmost) instance of '``old``' is replaced -with '``new``'*. So, for example, if you started out with the file, -'``My.Jpeg.Jpeg``' and ran the command above, you'd end up with a -new file name of '``My.jpg.Jpeg``' +string ``.Jpeg`` and replace it with ``.jpg``. Well ... that's +not quite right. Unless you specify otherwise with the ``-i`` +option, *only the first (leftmost) instance of ``old`` is replaced +with ``new``*. So, for example, if you started out with the file, +``My.Jpeg.Jpeg`` and ran the command above, you'd end up with a +new file name of ``My.jpg.Jpeg`` Substitution Instances @@ -550,21 +636,21 @@ Multiple Substitutions ====================== -You may specify multiple '``-r``' replacement operations on the **tren** +You may specify multiple ``-r`` replacement operations on the **tren** command line:: 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 +``.Jpeg`` with ``.jpg`` and ``old`` with ``ReallyOld`` anywhere these strings appeared in any of the file or directory names. 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 ('``\=``'):: +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``'. +This renames the file ``name=bob.dbms`` to ``name=sally.dbms``. @@ -586,25 +672,25 @@ These OSs show upper- and lower- case in file names as you request, but they do not *distinguish* names on the basis of case. For -instance, the files '``Foo``', '``foo``', and '``FOO``', are all the +instance, the files ``Foo``, ``foo``, and ``FOO``, are all the same name in these operating systems, and only one of these can exist in a given directory. This can cause **tren** to do the unexpected when your renaming command is doing nothing more than changing case. -Suppose you start with a file called '``Aa.txt``' and run this +Suppose you start with a file called ``Aa.txt`` and run this command:: tren.py -rA=a Aa.txt **tren** will immediately complain and tell you that the file -'``aa.txt``' already exists and it is skipping the renaming. Why? -Because from the point-of-view of OS X or Windows, '``aa.txt``' (your -new file name) is the same as '``Aa.txt``' (your original file name). +``aa.txt`` already exists and it is skipping the renaming. Why? +Because from the point-of-view of OS X or Windows, ``aa.txt`` (your +new file name) is the same as ``Aa.txt`` (your original file name). You can attempt to force the renaming:: tren.py -frA=a Aa.txt Guess what happens? Since **tren** thinks the new file name already -exists, it backs it up to '``aa.txt.backup``'. But now, when it goes +exists, it backs it up to ``aa.txt.backup``. But now, when it goes to rename the original file ... the file is *gone* (thanks to the backup renaming operation)! **tren** declares an error and terminates. @@ -626,9 +712,9 @@ ========================= Ordinarily **tren** treats both the old string you specify with the -'``-r``' option *literally*. However, it is sometimes handy to be able +``-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 +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 @@ -643,10 +729,10 @@ 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 +``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``' +``-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:: @@ -660,20 +746,20 @@ sXs-3.txt Keep in mind that a literal string is a subset of a regular -expression. This effectively means that with '``-x``' processing +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 +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: '``\=``'. +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 +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 @@ -685,20 +771,20 @@ Changing The Renaming Separator & Escape Characters =================================================== -There may be times when the default renaming separator ('``=``') -and/or escape character ('``\``') make it clumsy to construct a +There may be times when the default renaming separator (``=``) +and/or escape character (``\``) make it clumsy to construct a renaming request. This can happen if, say, either the old- or new -string in a literal renaming needs to use the '``=``' symbol many +string in a literal renaming needs to use the ``=`` symbol many times. Another case where this may be helpful is when constructing complex regular expressions than need to make use of these characters. -The '``-R``' and '``-P``' options can be used to change the character +The ``-R`` and ``-P`` options can be used to change the character used for renaming separator and escape character respectively. You can use any character you like (these must be a single character each), but bear in mind that the underlying operating system understands certain characters as being special. Trying to use them here will undoubtedly deeply confuse your command shell, and possibly -your file system. For example, the '``/``' character is used as a +your file system. For example, the ``/`` character is used as a path separator in Unix-derived systems. It's therefore a Really Bad Idea to try and use it as a renaming separator or escape character. @@ -709,8 +795,8 @@ 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``' +**tren** implements the notion of *renaming tokens*. These can +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 @@ -721,7 +807,7 @@ 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 +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. @@ -746,10 +832,10 @@ 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 +``.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 +``-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:: @@ -758,20 +844,20 @@ 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 +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 "replace + 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. You can do the same thing using a regular expression:: tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp* - Of course, if you use the '``-b``' or '``-e``' flags, you limit + Of course, if you use the ``-b`` or ``-e`` flags, you limit just what portion of the filename is considered "everything". @@ -781,8 +867,8 @@ 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 +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. @@ -793,14 +879,14 @@ 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``'. +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``'. +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 + 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*. @@ -822,16 +908,16 @@ **tren** defaults to a specific set of behaviors: - - '``old``' and '``new``' renaming text is treated *literally* + - ``old`` and ``new`` renaming text is treated *literally* - Renaming takes place within *the entire filename* - - *Only the first instance* of '``old``' is replaced with '``new``' + - *Only the first instance* of ``old`` is replaced with ``new`` - Renaming is *case sensitive* There are command line "switches" to override each of these defaults -('``-x``', '``-b``', '``-e``', '``-g``', and '``-c``'). +(``-x``, ``-b``, ``-e``, ``-g``, and ``-c``). There are additional "switches" to return the program to its -default behavior ('``-X``', '``-a``', '``-1``', and '``-C``'). +default behavior (``-X``, ``-a``, ``-1``, and ``-C``). The idea is that you can specify what kind of replacement behavior you want *for each different renaming operation*. @@ -841,14 +927,14 @@ This would rename the files as follows: - - The first instance of '``txt``' would be replaced with - '``TXT``' in each of the file extensions. + - The first instance of ``txt`` would be replaced with + ``TXT`` in each of the file extensions. - - All instances of '``m``' or '``M``' would be replaced + - All instances of ``m`` or ``M`` would be replaced anywhere they were found in the filename. - - All instances of one or more strings in the form '``ss``' would - be replaced with '``S``'. + - All instances of one or more strings in the form ``ss`` would + be replaced with ``S``. OTHER PROGRAM SEMANTICS @@ -862,8 +948,8 @@ `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``' - (global rename) and '``-c / -C``' (ignore case) options. + - Regular expression processing is unaffected by the ``-g / -1`` + (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 @@ -876,26 +962,26 @@ renaming (all, name only, extension only). 2) Replace all renaming tokens with their equivalent - text in both the '``old``' and '``new``' renaming strings. + text in both the ``old`` and ``new`` renaming strings. 3) If doing literal string replacement: - - If '``-c``' is in effect, collapse the target and the '``old``' + - 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) + - 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 + 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 tokens 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, + 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 @@ -903,7 +989,7 @@ 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, + 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. @@ -912,7 +998,7 @@ RENAMING TOKENS: THE GORY DETAILS ================================= -As we've just seen, a *Renaming Token* is nothing more than +As we've just seen, a *renaming token* is nothing more than a string representing something **tren** knows about. These fit in one of three categories: @@ -920,16 +1006,16 @@ - An attribute of the underling operating system environment - A sequence that reflects some ordering principle -Renaming tokens are delimited by the '``/``' character. **tren** +Renaming tokens are delimited by the ``/`` character. **tren** replaces these tokens with the corresponding information (see -descriptions below) wherever you indicated in either the '``old``' or -'``new``' strings of a '``-r``' rename command. +descriptions below) wherever you indicated in either the ``old`` or +``new`` strings of a ``-r`` rename command. Currently, **tren** defines a number of renaming tokens. Future releases of **tren** may add more of these, so it's good to periodically reread this material. -File Attribute Renaming Tokens +File Attribute renaming tokens ============================== These tokens are derived from information about the file or @@ -941,17 +1027,17 @@ This token is replaced with the date of creation of the file or directory being renamed. It is - in '``yyyymmdd``' format. + 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. + 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. + file was created in ``Ddd`` format. ``/E/ Original File Extension`` @@ -965,7 +1051,7 @@ directory before renaming. .. NOTE:: Notice that there is no token for the *whole* filename - because you can always synthesize it with '``/F/./E/``' + because you can always synthesize it with ``/F/./E/`` ``/G/ File or directory primary group name`` @@ -976,13 +1062,13 @@ ``/hh/ File or directory hour of creation`` This token is replaced with the hour the file was - created in '``hh``' format. + 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-DD``'. + file or directory being renamed. It is similar to ``/D/`` + except it is in ISO format, ``YYYY-MM-DD``. ``/L/ File or directory length`` @@ -993,28 +1079,28 @@ ``/mm/ File or directory minutes of creation`` This token is replaced with the minutes the file was - created in '``mm``' format. + 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. + 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. + 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. + 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 is equivalent to '``/hh/:/mm/:/ss/``'. + 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`` @@ -1024,12 +1110,12 @@ ``/yyyy/ File or directory year of creation`` This token is replaced with the year the file was - created in '``yyyy``' format. + created in ``yyyy`` format. -System Related Renaming Tokens +System Related renaming tokens ============================== These tokens are derived from the underlying operating system @@ -1038,7 +1124,7 @@ ``/$ENV/ Environment variable`` This token is replaced with the value of - the environment variable '``$ENV``'. If + the environment variable ``$ENV``. If that variable does not exist, the token is replaced with an empty string:: @@ -1051,7 +1137,7 @@ ``/`cmd`/ Arbitrary command execution`` This token is replaced with the string - returned by executing the '``cmd``' command. + returned by executing the ``cmd`` command. For instance, you might want to prepend the name of the system to a all you shell scripts:: @@ -1079,8 +1165,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 ``/D/``, +``/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 @@ -1132,7 +1218,7 @@ 0000 -> 0000, 0001, 0002, ... 03 -> 03, 04, 05, ... -You do not have to use a '``0``' to indicate the sequence width. You +You do not have to use a ``0`` to indicate the sequence width. You can use *any* padding characters you like. **tren** only cares about the width of the field and will "consume" your padding characters as the count increases.:: @@ -1171,10 +1257,10 @@ ``tren.py -b -r =/+D0002/ *.txt`` This would rename all the files in the current - directory into the form, '``0002.txt``', '``0003.txt``', - ... '``9999.txt``' with '``0002.txt``' being the oldest - file and '``9999.txt``' being the newest. If you - used the token '``/-D0002/``', you'd get the same + directory into the form, ``0002.txt``, ``0003.txt``, + ... ``9999.txt`` with ``0002.txt`` being the oldest + file and ``9999.txt`` being the newest. If you + used the token ``/-D0002/``, you'd get the same thing, but in reverse order. ``/+L0001/ Sequence based on the size of the files being renamed`` @@ -1185,10 +1271,10 @@ ``tren.py -r =/+L0002/ *.txt`` This would rename all the files in the current - directory into the form, '``0002.txt``', '``0003.txt``', - ... '``9999.txt``' with '``0002.txt``' being the shortest - file and '``9999.txt``' being the longest. If you - used the token '``/-L0002/``', you'd get the same + directory into the form, ``0002.txt``, ``0003.txt``, + ... ``9999.txt`` with ``0002.txt`` being the shortest + file and ``9999.txt`` being the longest. If you + used the token ``/-L0002/``, you'd get the same thing, but in reverse order. ``/+R0001/ Sequence based on the file order on the command line`` @@ -1199,14 +1285,14 @@ ``tren.py -e -r =/+R0000/ MyFile.txt AFile.jpg me.log`` - This would rename all the files to, '``MyFile.0``', - '``AFile.1``', and '``me.2``'. If you used '``/-R0000/``', - you'd get '``MyFile.2``', '``AFile.1``'`, and '``me.0``'. + This would rename all the files to, ``MyFile.0``, + ``AFile.1``, and ``me.2``. If you used ``/-R0000/``, + you'd get ``MyFile.2``, ``AFile.1```, and ``me.0``. ``/+T0001/ Sequence based on creation time within date`` This produces a sequence based on the creation date - and time similar to the '``/+D.../``' sequence renaming + and time similar to the ``/+D.../`` sequence renaming token above. However, the sequence *resets* at the beginning of each new date. This allows you to create unique sequences *within a date* like our @@ -1216,7 +1302,7 @@ tren.py -b -r =/D/-/+T0100/ *.txt - This would rename all the '``.txt``' files in the current + This would rename all the ``.txt`` files in the current directory into the form:: 200103010-0100.txt @@ -1232,7 +1318,7 @@ In other words, instead of sequence just on the creation date, this allows us to sequence *within* the date. As always, the - '``-``' flag will reverse this order within the date. + ``-`` flag will reverse this order within the date. Notice that you can get something similar using just file attribute renaming tokens:: @@ -1295,7 +1381,7 @@ tren.py -x -r a+=a Saaaaaaaally.doc # Sally.doc - Rename a file containing the '``=``' symbol:: + Rename a file containing the ``=`` symbol:: tren.py -r a\=b=c\=d a=b.txt # c=d.txt @@ -1321,7 +1407,7 @@ As a general matter, **tren** should run on any POSIX-compliant OS that has this version (or later) of Python on it. It will also run on many Microsoft Windows systems. If the Windows system has the -'``win32all``' Python extensions installed, **tren** will take advantage +``win32all`` Python extensions installed, **tren** will take advantage of them for purposes of deriving the names of the user and group that own the file or directory being renamed. @@ -1357,10 +1443,10 @@ **tren** is Copyright (c) 2010 TundraWare Inc. -For terms of use, see the '``tren-license.txt``' file in the +For terms of use, see the ``tren-license.txt`` file in the program distribution. If you install **tren** on a FreeBSD system using the 'ports' mechanism, you will also find this file in -'``/usr/local/share/doc/tren``'. +``/usr/local/share/doc/tren``. AUTHOR @@ -1378,7 +1464,7 @@ :: - $Id: tren.rst,v 1.147 2010/03/23 22:37:59 tundra Exp $ + $Id: tren.rst,v 1.148 2010/03/25 22:39:58 tundra Exp $ You can find the latest version of this program at: