Fork: 0
tundra / tren
Browse code
Added -F option.
Added default toggles.
Added section explaining toggle use.
master
1 parent 190cc8e commit 62a5c2c982fa5d7dfd82f46e2a7472cb50c65fe0
@tundra tundra authored on 20 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
120
■■■■■
 tren.rst
--------
 
::
 
tren.py [-cbefghqtvx] [-l string] [-r old=new]... file|dir file|dir ...
tren.py [-1aCcbefghqtvXx] [-F file] [-l string] [-r old=new]... file|dir file|dir ...
 
 
OPTIONS
-------
 
-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.
 
-a Rename within the entire file or directory name
 
(*Default*: This is the program default)
 
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*: Substitute within the entire 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
cirumventing problems like this::
 
tren.py -b -r eg=ug 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.
 
-c Collapse case when doing string substitution.
 
(*Default*: Search for string to replace is case sensitive.)
(*Default*: Search for string to replace is case sensitive)
 
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::
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 file Read 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
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.
 
The ``-F`` option allows you to place any command line
arguments in a separate *file* in place of- or in addition to
the **tren** command line itself. This file is read one line
at a time and the contents appended to any existing command
line. You can even name the files you want renamed in the
file, but they must appear as the last lines of that file
(because they must appear last on the command line).
 
Whitespace is ignored as is anything from a ``#`` to the end of
a line::
 
# Example replacement string file
# Each line appended sequentially
# to the command line
 
-x
-r t[ext]+=txt # Appended first
-c -g my=Mine
-X
-r =/L/ -r foo=bar
my.file
your.file # Appended last
 
.. 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 typicaly create a list of files
ending in ``.txt`` when given on the command line.
However, the ``*`` metacharacter has no meaning like this
when used inside an arguments file.
 
-f Force renaming even if target file or directory name already
exists.
 
By default, **tren** only replaces the first
(leftmost) instance of the old string with the new.
 
This option's behavior is modified by the ``-b``,
``-c``, ``-e``, ``g``, ``l``, and ``x`` options.
 
-t Test mode, don't rename, just show what the program *would* do
(ignores -q).
 
**tren** is very powerful and capable of doing nasty things to
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.
 
-X Treat the renaming strings literally
 
(*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
line.
 
-x Treat the old string in a ``-r`` replacement as a Python
style regular expression for matching purposes.
 
 
**tren** has many other kinds of renaming tokens. Their
structure and use is described in some detail in the
next section.
 
 
COMMAND LINE TOGGLES
--------------------
 
**tren** defaults a specific set of behaviors:
 
- ``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``
- Renaming is *case sensitive*
 
There are command line "switches" to override each of these defaults
(``-x``, ``-b``, ``-e``, ``-g``, and ``-c``).
 
There are additional "switches" to return the program to its
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*.
For instance::
 
tren.py -e -r txt=TXT -g -a -c -r M=0 -C -x -r [ss]+=S filelist
 
This would rename the files as follows:
 
- 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
anywhere they were found in the filename.
 
- All instances of one or more strings in the form ``ss`` would
be replaced with ``S``.
 
 
 
 
RENAMING TOKENS: THE GORY DETAILS
---------------------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.128 2010/01/20 18:19:42 tundra Exp $
$Id: tren.rst,v 1.129 2010/01/20 21:35:07 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren