Fork: 0
tundra / tren
Browse code
Editing and formatting cleanup.
Changed -m to -T.
Changed renaming token delimiters from <> to //.
master
1 parent 942b059 commit 1ed1f5fae5a401e10027d770f7b3e37fbcf27613
@tundra tundra authored on 16 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
154
■■■■■
 tren.rst
--------
 
::
 
tren.py [-cbeghqtvx] [-l string] [-m template] [-r old=new]... file|dir file|dir ...
tren.py [-cbeghqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ...
 
 
DESCRIPTION
-----------
 
would rename all files (or directories) whose names contained the string
``.Jpeg`` and replace it with ``.jpg``. 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).
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.
 
By default, only the first instance of the string is replaced in the
name, but you can use the ``-g`` option to replace *all* instances
of the old string with the new one.
There's a whole section later in this document on template
construction and the use of renaming tokens, but here's a simple
example to illustrate the general idea using the files above::
 
tren.py -m <D>-MyVacation-<0001>.jpeg *.jp*
tren.py -T /D/-MyVacation-/0001/.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 ``<0001>`` refers to a *starting sequence number* to
``.jp*``. The ``/D/`` would be replaced with the *date* the picture
was taken. The ``/0001/`` refers to a *starting sequence number* to
uniquely identify pictures taken on the same date. The other strings
in the template, ``-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::
20100105-MyVacation-0001.jpeg (Mary's)
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 "<0001>"
the time-of-day they were taken because we included the ``/0001/``
renaming token in our pattern.
 
There are many other renaming tokens and ways to construct
all manner of clever templates. These are discussed below in the
 
OPTIONS
-------
 
-b Exclude file/directory "extension" when doing string
substitution.
(*Default*: Substitute within the entire file/directory name)
 
Many applications use the suffix of a filename to indicate the
contents or type of file. By default, **tren** does string
substiution in the entire filename *including* the extension.
For example doing this::
 
tren.py -r eg=ug peg.jpeg
 
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 -b -r eg=ug peg.jpeg # Renames file to pug.jpeg
-T template Rename by template.
 
(*Default*: Rename via string replacement.)
 
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
 
-b Only perform string substitution within "name" portion of
or directory name.
 
(*Default*: Substitute within the entire file/directory name)
 
Many applications use the suffix of a filename to indicate the
contents or type of file. By default, **tren** does string
substiution in the entire filename *including* the extension.
For example doing this::
 
tren.py -r eg=ug peg.jpeg
 
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 -b -r eg=ug peg.jpeg # Renames file to pug.jpeg
-c Collapse case when doing string substitution.
 
(*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::
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
 
-e Only do string substitutions in the filename "extension".
(*Default*: Substitute within the entire file/directory name)
-e Only perform string substitution within "extension" portion of
or directory name.
 
(*Default*: Substitute within the entire file/directory name)
 
This option is the inverse of ``-b``. It instructs **tren**
to do the requested subsitution *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
 
-g Replace all instances (greedy replace) 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
-h Print help information.
 
 
-l string File "extension" delimiter string.
(*Default*: ".")
 
(*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
and extension components. Notice also that when you do
this, no renaming of characters *within* the separator
takes place.
 
-m template Rename by template. (*Default*: Rename via string replacement.)
 
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
 
 
-q Quiet mode, do not show progress.
(*Default*: Display 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
 
 
-v Print detailed program version information and exit.
 
-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)
 
String substitution arguments to the ``-r`` option are usually
understood to be taken literally. There are, however, instances
where this is tedius to do. Say you have a set of files
that are similar, but not idential in name, and you want to
rename them all::
-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)
 
String substitution arguments to the ``-r`` option are usually
understood to be taken literally. There are, however, instances
where this is tedius to do. Say you have a set of files
that are similar, but not idential in name, and you want to
rename them all::
 
sbbs-1.txt
sbbbs-2.txt
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
``-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
 
This renames the files to::
 
sXs-1.txt
sXs-2.txt
sXs-3.txt
 
**tren** only accepts Python style regular expressions. Anything
else will cause an error message to be displayed.
Suppose you want to rename them, replacing two or more instances
of ``b`` with ``X``. It is tedious to have to write a separate
``-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
 
This renames the files to::
 
sXs-1.txt
sXs-2.txt
sXs-3.txt
 
**tren** only accepts Python style regular expressions. Anything
else will cause an error message to be displayed.
 
 
TEMPLATE CONSTRUCTION
---------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.112 2010/01/16 00:04:27 tundra Exp $
$Id: tren.rst,v 1.113 2010/01/16 15:38:10 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren