Fork: 0
tundra / tren
Browse code
Began editing command line option details.
master
1 parent b8a3a89 commit 22c566a1d7bd7301ff3156a232c1ef85f015710a
@tundra tundra authored on 19 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
253
■■■■■
 tren.rst
 
tren.py [-aCcdfhqtvXx] [-A alphabet] [-I file] [-i range] [-P esc] [-R sep] [-r old=new] [-S suffix] [-w width] file|dir ...
 
 
OPTIONS
-------
SPECIFYING OPTIONS
------------------
 
You may specify *tren* options in one of three ways:
 
1) On the command line
"end of options" delimiter::
 
tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
 
This allows you to rename different files and directories with
different options. *However*, keep in mind that all the options to
the left of the file or directory being renamed are in force. That
is, options are *cumulative*. In the example above, the rightmost
files and directory would be renamed with all the options 1-6 in
force. This is why there are "toggles" in the options below - they
allow you to selectively turn features on- and off as you move to the
right on the command line.
 
-1 Rename only the first instance of the specified string
 
(*Default*: This is the program default)
 
This option is provided so you can toggle the program back to
its default behavior after a previous ``-g`` on the command
line.
 
This option is ignored during regular expression processing
(``-x``).
 
-a Rename within the entire file or directory name
 
(*Default*: This is the program default)
 
Some options below are "global" - they change the state of the entire
program permanently and cannot be undone by subsequent options. Some
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
dump. Among many other things, the **tren** debugger dumps the state
of each renaming request, and what options are in effect for that
request.)
 
 
OPTIONS
=======
 
-A alphabet Install a user-defined "alphabet" to be used by
Sequence Renaming Tokens. The alphabet is
specified in the form::
 
name:characterset
 
Both the name and the characterset are case- and
whitespace-sensitive (if your shell permits passing
spaces on the command line). The "0th" element
of the alphabet is the leftmost character. The
counting base is the length of ``characterset``.
So, for instance, the following alphabet is
named ``Foo``, counts in base 5 in the
sequence, ``a, b, c, d, e, ba, bb, ...``::
 
-A Foo:abcde
 
-a Ask interactively before renaming each selected file or
directory.
 
(*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
command line.
 
-b Only perform renaming within "name" portion of file
or directory name.
 
(*Default*: Rename within the entire file or directory name)
 
Many applications use the suffix of a filename to indicate the
contents or type of file. By default, **tren** does renaming
in the entire filename *including* the extension. For example
doing this::
 
tren.py -g -r e=u peg.jpeg # -g = "rename all"
 
Renames the file to ``pug.jpug`` .. probably not what you want.
 
The ``-b`` option tells **tren** to only perform string renaming
in the actual "name portion" of the filename thereby
cirumventing problems like this::
 
tren.py -g -b -r e=u peg.jpeg # Renames file to pug.jpeg
-C Do case-sensitive renaming
 
(*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
line.
 
This option is ignored during regular expression processing
(``-x``).
This option is observed both for literal and regular
expression-based renaming (``-x``). .
 
-c Collapse case when doing string substitution.
 
(*Default*: Search for string to replace is case sensitive)
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
 
This option is ignored during regular expression processing
(``-x``).
This option is observed both for literal and regular
expression-based renaming (``-x``).
 
 
-d Dump debugging information
 
(*Default*: Off)
 
Dumps all manner of information about **tren** internals -
of interest only to program developers and maintainers.
 
-E Continue renaming even after an error is encountered
 
(*Default*: Stop processing after any error)
 
-e Only perform renaming within "extension" portion of
or directory name.
 
(*Default*: Substitute within the entire file or directory name)
 
This option is the inverse of ``-b``. It instructs **tren**
to do the requested renaming *only* in the filename
"extension" not on the file name portion. For example::
 
tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg
 
-f Force renaming even if target file or directory name already
exists.
 
(*Default*: Skip renaming if a file or directory already
exists by the same name as the target.)
 
-g Replace all instances (global rename) of the old string
with the new.
 
(*Default*: Only the first matching string is replaced.)
 
Ordinarily, **tren** only replaces the single *leftmost*
instance of a string in the entire filename (default), the name
portion (``-b``) or the extension (``-e``). If you want
*all* instances of a particular string replaced, use this
option to enable "global" renaming::
 
tren.py -g -r p:P pop.txp # Renames file to: PoP.txP
 
This option is ignored during regular expression processing
(``-x``).
(*Default*: Skip renaming if a file or directory already
exists by the same name as the target.)
 
By default, **tren** will not rename something to a name that
is already in use by another file or directory. This option
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
way even forced renames don't clobber existing files or
directories.
 
-h Print help information.
 
 
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
templates, or if you make heavy use of command line toggles.
tokens, or if you make heavy use of command line toggles.
 
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
# Example replacement string file
# Each line appended sequentially
# to the command line
 
-r t[ext]+=txt # Appended first
-c -g my=Mine
-xr t[ext]+=txt # Appended first
-X
-r =/L/ -r foo=bar
-r =/MYEAR/ -r foo=bar
my.file
your.file # Appended last
 
However, its easy to introduce a "circular reference" when you
do this. Suppose file ``z`` tried to include file ``x`` in
this example? You'd be specifying an infinite inclusion loop.
To avoid this, **tren** limits the total number of inclusions
to 50. If you exceed this, you'll get an error message and the
program will terminate.
 
.. NOTE:: There is one important difference between an actual
command line and keeping the arguments in a file like
this. *Filename wildcards are not expanded within the
file.* ``*.txt`` will typically be expanded by a command
shell to create a list of files ending in ``.txt``.
However, the ``*`` metacharacter has no such meaning when
used inside an arguments file.
 
-l string File "extension" delimiter string.
 
(*Default*: ".")
 
**tren** has to know what separates the "name" from the
"extension" in a filename. By default, it uses the
rightmost ``.`` character. You can change it with this
option to "divide" the filename into name and extension
for renaming purposes, using any string you like. This
is particularly helpful with ``-b`` and ``-e`` options::
 
tren.py -g -b -l .long.txt -r long:short long.long.txt.long.txt.foo
 
This would rename the file to::
 
short.short.txt.long.txt.foo
 
Notice that **tren** looks for the *rightmost* instance
of the separator to split the whole filename into name
and extension components. Notice also that when you do
this, no renaming of characters *within* the separator
takes place.
 
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.
 
-i num|range 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.
 
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::
 
-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.
 
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
-q Quiet mode, do not show progress.
 
(*Default*: Display progress)
 
matches with the corresponding ``new`` string. Keep in mind
that if ``-x`` is selected the *entire* ``old`` string is
treated as a Python regular expression. Pay particular
attention to this if you're combing literal text and/or
renaming templates with regular expression metacharacters.
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,
BUGS, MISFEATURES, OTHER
------------------------
 
You must be running Python 2.6.x or later. **tren** makes use of
features not supported in released prior to this.
features not supported in releases prior to this.
 
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
-----------------------------
 
::
 
$Id: tren.rst,v 1.137 2010/03/19 17:19:14 tundra Exp $
$Id: tren.rst,v 1.138 2010/03/19 18:47:17 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren