diff --git a/tren.rst b/tren.rst index 24c4da5..0b78ca0 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 ``-`` character, +renamed. If one of your rename targets start with the '``-``' character, most command shells recognines 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.) @@ -101,7 +101,7 @@ (*Default*: off) This option is provided so you can toggle the program back to - its default behavior after a previous ``-b`` or ``-e`` on the + its default behavior after a previous '``-b``' or '``-e``' on the command line. -C Do case-sensitive renaming @@ -109,11 +109,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. @@ -130,7 +130,7 @@ is preserved. This option is observed both for literal and regular - expression-based renaming (``-x``). + expression-based renaming ('``-x``'). -d Dump debugging information @@ -151,7 +151,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. @@ -161,13 +161,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. - 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 @@ -199,83 +199,114 @@ to 1000. If you exceed this, you'll get an error message and the program will terminate. - .. NOTE:: Wilcard metacharcters like ``*`` and ``?`` that are - embedded in filenames included this way *are* expanded as - they would be from the command shell. + Note that wildcard metacharacters like ``*`` and ``?`` that are + embedded in filenames included this way are expanded as they + would be from the command shell. - -i num|range Specifies which "instances" of matching strings should - be replaced. (*Default*: 0 or leftmost) + -i instances Specifies which "instances" of matching strings should + be replaced. + (*Default*: 0 or leftmost) - An existing file may have multiple instances of the - "old" renaming string in it. The ``-i`` option lets - you specify which of these (one, several, all) you'd - like to have replaced. + A file may have multiple instances of the "old" + 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. - 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. + Suppose you have a file called + '``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:: + A "range" of instances is specified + using the '``:``' separator in the form:: - -i first-to-replace:stop-here + -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 - *all* instances. + All instances from the "first-to-replace" + up to, *but NOT including* "the stop-here" + are replaced. '``-i :``' means "replace + *all* instances. - Examples:: + Examples:: - tren.py -i 1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-foo3.foo4 - tren.py -i -1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-foo2-foo3.bar4 - tren.py -i 1:3 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-bar3.foo4 - tren.py -i -4:-2 -r foo=bar foo1-foo2-foo3.foo4 -> bar1-bar2-foo3.foo4 - tren.py -i : -r foo=bar foo1-foo2-foo3.foo4 -> bar-bar2-foo3.bar4 + tren.py -i 1 -r f=b foo1-foo2-foo3.foo4 + -> foo1-boo2-foo3.foo4 + + tren.py -i -1 -r f=b foo1-foo2-foo3.foo4 + -> foo1-foo2-foo3.boo4 + + tren.py -i 1:3 -r f=b foo1-foo2-foo3.foo4 + -> foo1-boo2-boo3.foo4 + + tren.py -i -4:-2 -r f=b foo1-foo2-foo3.foo4 + -> boo1-boo2-foo3.foo4 + + tren.py -i : -r f=b foo1-foo2-foo3.foo4 + -> boo1-boo2-boo3.boo4 + -P char Use '``char``' as the escape symbol. + (*Default*: '``\``') + -q Quiet mode, do not show progress. (*Default*: Display progress) 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 + "noisy" output, use the '``-q``' option. Note that this does not suppress warning and error messages. - This option is ignored when running in test mode (``-t``). + -R char Use '``char``' as the separator symbol in renaming + specifications. + (*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 - which 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 + 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. You can have multiple instances of this option on your **tren** command line:: - tren.py -e old:new -e txt:doc old-old.txt + tren.py -r old:new -r txt:doc old-old.txt This renames the file to:: new-old.doc - By default, **tren** only replaces the first + Remember that, by default, **tren** only replaces the first (leftmost) instance of the old string with the new. + Each rename specifiation on the command line "remembers" + the current state of all the program options and acts + accordingly. For example:: + + 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``'. + -t Test mode, don't rename, just show what the program *would* do (ignores -q). @@ -293,10 +324,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) @@ -308,11 +339,11 @@ .. 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`` + not, run the program in test mode (invoke with the '``-t``' option) to see what would 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 +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. @@ -323,7 +354,7 @@ 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). +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 @@ -333,7 +364,7 @@ tren.py -r old=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: ============================= ============================= @@ -362,39 +393,39 @@ 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 the ``-g`` option, *only the first -(leftmost) instance of ``old`` is replaced with ``new``*. +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. +"name" ('``-b``') or "extension" ('``-e``') portions of the filename. -You may specify multiple replacement operations (``-r``) on the **tren** +You may specify multiple replacement operations ('``-r``') 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``'. 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 +'``-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 @@ -409,10 +440,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:: @@ -426,20 +457,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 @@ -453,7 +484,7 @@ ------------------------------ **tren** implements the notion of *Renaming Tokens*. These can -appear in either the ``old`` or ``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 @@ -464,7 +495,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. @@ -489,10 +520,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:: @@ -501,20 +532,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". @@ -524,8 +555,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. @@ -536,14 +567,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*. @@ -565,16 +596,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*. @@ -584,14 +615,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 @@ -605,8 +636,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 @@ -619,26 +650,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 @@ -646,7 +677,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. @@ -663,10 +694,10 @@ - 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 @@ -684,17 +715,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`` @@ -708,7 +739,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`` @@ -719,13 +750,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`` @@ -736,28 +767,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`` @@ -767,7 +798,7 @@ ``/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. @@ -781,7 +812,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:: @@ -794,7 +825,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:: @@ -822,8 +853,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 @@ -875,7 +906,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.:: @@ -914,10 +945,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`` @@ -928,10 +959,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`` @@ -942,14 +973,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 @@ -959,7 +990,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 @@ -975,7 +1006,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:: @@ -1038,7 +1069,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 @@ -1064,7 +1095,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. @@ -1087,10 +1118,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 @@ -1108,7 +1139,7 @@ :: - $Id: tren.rst,v 1.138 2010/03/19 18:47:17 tundra Exp $ + $Id: tren.rst,v 1.139 2010/03/19 20:02:37 tundra Exp $ You can find the latest version of this program at: