Fork: 0
tundra / tren
Browse code
Completed options synopsis.
master
1 parent 0459937 commit c58a3a3ff4976f0f271abbd8a651e9841da4655d
@tundra tundra authored on 23 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
156
■■■■■
 tren.rst
HOW TO USE THIS DOCUMENT
------------------------
 
**tren** is a powerful command line file/directory renaming tool. It
implements multiple, sophisticated renaming features than can be a bit
implements a variety of sophisticated renaming features than can be a bit
complex to learn. For this reason, this document is split into two
general sections: `REFERENCE`_ and `TUTORIAL AND DESCRIPTION`_. If
you are new to **tren**, start by studying the latter section first.
It will take you from very simple- to the most complex renaming
operations the program supports. Once you've got a sense of what
It will take you from very simple- to highly complex **tren** renaming
operations. Once you've got a sense of what
**tren** can do, the reference section will be handy to look up
options and their arguments.
 
.. WARNING:: **tren** is very powerful and can easily and
Think of any options set in ``$TREN`` as the "leftmost command line
options".
 
All options must precede the list of files and/or directories being
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::
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::
 
tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
 
 
OPTIONS
=======
 
-A alphabet Install a user-defined "alphabet" to be used by
Sequence Renaming Tokens. The alphabet is
specified in the form::
Sequence Renaming Tokens.
 
(*Default*: Built-in alphabets only)
 
The alphabet is specified in the form::
 
name:characterset
 
Both the name and the characterset are case- and
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.
If you invoke this option, **tren** will prompt you before
renaming each file. The default (if you just hit '``Enter``')
is to *not* rename the file. Otherwise, you have the following
options::
 
n - Don't rename the current file
y - Rename the current file
! - Rename all the remaining files without further prompting
q - Quit the program
 
These options are all insensitive to case.
 
-C Do case-sensitive renaming
 
(*Default*: This is the program default)
When looking for a match on the old string to replace,
**tren** will ignore the case of the characters found
in the filename. For example::
 
tren.py -c -r Old:NEW Cold.txt fOlD.txt
tren.py -c -r Old=NEW Cold.txt fOlD.txt
 
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
-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
does not suppress warning and error messages.
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
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
to see what would happen. Using the quiet mode suppresses that
output.
 
 
-R char Use '``char``' as the separator symbol in renaming
specifications.
 
You can have multiple instances of this option on
your **tren** command line::
 
tren.py -r old:new -r txt:doc old-old.txt
tren.py -r old=new -r txt:doc old-old.txt
 
This renames the file to::
 
new-old.doc
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::
Each rename specification 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).
-S suffix Suffix to append when making backup copies of existing
targets.
 
(*Default*: .backup)
 
If you choose to force renaming if files when the new
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```
option.
 
-t Test mode, don't rename, just show what the program *would* do.
 
**tren** is very powerful and capable of doing nasty things to
your files (like making a file disappear when another one is
renamed over it). For this reason, it is helpful to test
your **tren** commands before actually using them. With this
option enabled, **tren** will print out diagnostic information
about what your command *would* do, *without actually doing it*.
 
-v Print detailed program version information and exit.
your file and directory names. For this reason, it is helpful
to test your **tren** commands before actually using them.
With this option enabled, **tren** will print out diagnostic
information about what your command *would* do, *without
actually doing it*.
 
-v Print detailed program version information and keep running.
 
This is handy if you're capturing **tren** output into a log
and you want a record of what version of the program was used.
 
-w length Set the length of diagnostic and error output.
 
(*Default*: 80)
 
**tren** limits output to this length when dumping
debug information, errors, warnings, and general
information as it runs. This option is especially
useful when you're capturing **tren** output into
a log and don't want lines wrapped::
 
tren.py -w999 ..... 2>&1 > tren.log
 
-X Treat the renaming strings literally
 
(*Default*: This is the program default)
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
'``-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
tren.py -x -r bb+=X *.txt
 
This renames the files to::
 
sXs-1.txt
 
This produces a sequence from shortest to longest
(or the reverse) of the renamed objects.
 
``tren.py -r /+L0002/ *.txt``
``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
tren.py -c -r bin=BIN Binary_bIN.txt # BINary_bIN.txt
 
Rename multiple strings at once::
 
tren.py -r log:txt -r New:old New.log # old.txt
tren.py -r log=txt -r New=old New.log # old.txt
 
Rename using regular expressions::
 
tren.py -x -r a+=a Saaaaaaaally.doc # Sally.doc
-----------------------------
 
::
 
$Id: tren.rst,v 1.139 2010/03/19 20:02:37 tundra Exp $
$Id: tren.rst,v 1.140 2010/03/23 19:38:51 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren