diff --git a/tren.rst b/tren.rst index fc7deb0..7da6268 100644 --- a/tren.rst +++ b/tren.rst @@ -8,16 +8,32 @@ :: - 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 @@ -34,9 +50,17 @@ 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 @@ -59,6 +83,47 @@ 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. @@ -144,9 +209,6 @@ 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). @@ -159,6 +221,14 @@ -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. @@ -414,6 +484,42 @@ 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 --------------------------------- @@ -852,7 +958,7 @@ :: - $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: