Fork: 0
tundra / tren
Browse code
Move OPTIONS up right below SHORT SYNOPSIS.
Settled on "renaming token" as correct terminology.
Lots of token-related editing.
master
1 parent c44b56d commit 614f9ddac471499cc65701b289e6f70b07164a21
@tundra tundra authored on 19 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
673
■■■■■
 tren.rst
 
::
 
tren.py [-cbefghqtvx] [-l string] [-r old=new]... file|dir file|dir ...
 
 
OPTIONS
-------
 
-b Only perform renaming within "name" portion of file
or directory name.
 
(*Default*: Substitute 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 -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::
 
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.
 
-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 (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
*all* instances of a particular string replaced, use this
option to enable "greedy" replacement::
 
tren.py -g -r p:P pop.txp # Renames file to: PoP.txP
 
-h Print help information.
 
 
-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 -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.
 
-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.
 
This option is ignored when running in test mode (``-t``).
 
 
-r <old=new> Replace "oldstring" with "newstring" in file names.
 
Use this option to specify which strings you
want to replace in each file name. These strings
are treated literally unless you also invoke
the ``-x`` option.
 
You can have multiple instances of this option on
your **tren** command line::
 
tren.py -e old:new -e txt:doc old-old.txt
 
This renames the file to::
 
new-old.doc
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.
 
If you need to use the ``=`` symbol *within* either
the old or new string, simply escape it: ``\=``
 
 
-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
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.
 
-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)
 
 
 
DESCRIPTION
-----------
 
**tren** supports a variety of renaming mechanisms. The one thing
they have in common is that you must specify an *old string* which
will be replaced by a *new string* when the file or directory is
renamed. Each of these can take on one of several forms:
 
---------- ----------
Old String New String
---------- ----------
 
Literal Text Literal Text
Regular Expression Literal Text With Templates
Literal Text With Templates
 
The sections below describe each of these mechanisms.
renamed. The general form is::
 
tren.py -r old=new <list of files, directories to rename>
 
 
The ``old`` and ``new`` string are built using a variety of
building blocks:
 
============================= =============================
*Old Strings Are Built With:* *New Strings Are Built With:*
----------------------------- -----------------------------
 
Literal Text Literal Text
Regular Expressions Renaming Tokens
Renaming Tokens
============================= =============================
 
 
You can use any of these building blocks alone or combine them
to create expressive and powerful renaming schemes.
 
 
Literal String Substitution
---------------------------
 
Literal String Substitution is just that - it replaces one literal
string with another to rename the target file or directory. This is
handy when you have files and directories that have a common set of
characters in them you'd like to change. For instance::
the most common, and simplest way to use **tren**. This is handy when
you have files and directories that have a common set of characters in
them you'd like to change. For instance::
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
would rename all files (or directories) whose names contained the
This 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).
You can limit the replacement to just the "name" (``-b``) or
Keep in mind that a literal string is a subset of a regular
expression. This effectively means that with ``-x`` processing
enabled you can include *both* regular expressions and literal text in
your "old string" specification. The only requirement is that the
string taken as a whole be a valid Python regular expression. If it
is not, **tren** will display an error message to that effect.
string taken as a whole must be a valid Python regular expression. If
it is not, **tren** will display an error message to that effect.
 
Because Python regular expressions can make use of the ``=`` symbol,
you need a way to distinguish between an ``=`` used in a regular
exression and the same symbol used to separate the old and new
operands for the ``-r`` option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: ``\=``.
 
 
An Overview Templates
---------------------
 
**tren** implements the notion of *Renaming Templates*. These can
An Overview Renaming Tokens
---------------------------
 
**tren** implements the notion of *Renaming Tokens*. These can
appear in either the old- or the new string components of a ``-r``
renaming argument.
 
It is sometimes useful to be able to take a group of files or
directories whose names have nothing in common and impose a common
naming scheme on them. For example, suppose you and your friends pool
your vacation photos but each of your cameras uses a slightly
different naming scheme. You might want to just reorder them by the
date and time each picture was taken, for example. That way you end
up with one coherent set of named and numbered files. You might have
something like this::
naming scheme on them. Another use for renaming tokens is to do the
renaming based on some property the file or directory possesses like
its creation date, size, owner's name, and so on.
 
In their simplest form, renaming tokens are nothing more than
"canned" information **tren** knows about a particular file or
directory. For instance, if you insert the ``/D/`` token into a
old- or new string definition, **tren** will replace it with *the
creation date of the file or directory being renamed* and use that
string in the renaming process.
 
There are also tokens that can be used to automatically renumber or
sequence a set of files or directories being renamed. Finally, there
are tokens that allow you to use system information in your renaming
strings.
 
For example, suppose you and your friends pool your vacation photos
but each of your cameras uses a slightly different naming scheme. You
might want to just reorder them by the date and time each picture was
taken, for example. That way you end up with one coherent set of
named and numbered files. You might have something like this::
 
DSC002.jpg (Bob's camera, taken 1-5-2010 at noon)
dc0234.Jpg (Mary's camera, taken 1-5-2010 at 8am)
032344.jpeg (Sid's camera, taken 1-3-2010 at 4pm)
 
It would be nice to get these in order somehow.
 
*Renaming Templates* provide this ability. Given a list of files,
you apply a "template" or pattern to be used when renaming them. This
template is nothing more than a string containing so-called *Renaming
Tokens* built into **tren**, and optionally, literal text, and even
regular expressions (old string only).
 
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::
It would be nice to get these in order somehow:
 
tren.py -r =/D/-MyVacation-/+T0001/.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 ``/+T0001/`` 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::
uniquely identify pictures taken on the same date. The other strings,
``-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::
 
20100103-MyVacation-0001.jpeg (Sid's)
20100105-MyVacation-0001.jpeg (Mary's)
20100105-MyVacation-0002.jpeg (Bob's)
renaming token in our pattern. The ``+`` here means to construct
the sequence in *ascending* order. A ``-`` would specify
*descending* order.
 
Notice that there is *no old string* in our example above.
That is, there is nothing to the left of the ``=`` symbol
in the ``-r`` option. This effectively means "match anything"
in the existing file or directory name. If you were using
regular expressions (``-x``) you could do the same thing
with::
 
-r *=/D/-MyVacation-/+T001/.jpeg *.jp*
 
Ordinarily the template text replaces the *entire* existing filename
when you do this. You can limit the replacement to either the "name"
(``-b``) or "extension" (``-e``) portions of the filename.
.. Note:: Notice that there is *no old string* in our example above.
That is, there is nothing to the left of the ``=`` symbol in
the ``-r`` option. This effectively means "match anything"
in the existing file or directory name. You can do
the same thing using a regular expression::
 
tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp*
 
Of course, you don't *have* to replace the entire filename when
using templates. It's perfectly legitimate to replace only
using tokens. It's perfectly legitimate to replace only
a portion of the existing name::
 
tren.py -r file=/D/-file file-1 file.2
 
This would rename our files to: ``20100101-file-1 and 20100101-file.2``
 
You can even use templates in your *old string* specification.
For instance, suppose you manage a number of different systems
that set their system name in an environment variable called SYSNAME.
You might then do something like this::
This would rename our files to: ``20100101-file-1 and
20100101-file.2`` Notice that we combined literal text and a renaming
token to do this.
 
You can even use renaming tokens in your *old string* specification.
For instance, suppose you manage a number of different systems that
set their system name in an environment variable called SYSNAME. You
might then do something like this::
 
tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old
 
If your system name were "matrix", then the command above would only
rename files in the form ``matrix<anytext>.bku``. If your system name
were "modar", then the command above would only rename files in the
form ``modar<anytext>.bku``.
If your system name was "matrix", then the command above would only
rename files whose names began with ``matrix`` and ended with ``.bku``.
If your system name were "morton", then the command above would only
rename files whose names began with ``morton`` and ended with ``.bku``.
 
There are a couple of things to keep in mind when doing things like
this:
 
explicit quoting of the renaming tokens used in the old
string specification.
 
 
There are many other renaming tokens and ways to construct
all manner of clever templates. These are discussed below in the
section entitled `TEMPLATE CONSTRUCTION`_.
 
 
OPTIONS
-------
 
-b Only perform renaming within "name" portion of file
or directory name.
 
(*Default*: Substitute 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 -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::
 
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.
 
-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 (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
*all* instances of a particular string replaced, use this
option to enable "greedy" replacement::
 
tren.py -g -r p:P pop.txp # Renames file to: PoP.txP
 
-h Print help information.
 
 
-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 -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.
 
-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.
 
This option is ignored when running in test mode (``-t``).
 
 
-r <old=new> Replace "oldstring" with "newstring" in file names.
 
Use this option to specify which strings you
want to replace in each file name. These strings
are treated literally unless you also invoke
the ``-x`` option.
 
You can have multiple instances of this option on
your **tren** command line::
 
tren.py -e old:new -e txt:doc old-old.txt
 
This renames the file to::
 
new-old.doc
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.
 
If you need to use the ``=`` symbol *within* either
the old or new string, simply escape it: ``\=``
 
 
-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
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.
 
-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)
 
 
 
TEMPLATE CONSTRUCTION
---------------------
 
Template based renaming is used when you want to impose a naming
**tren** has many other kinds of renaming tokens. Their
structure and use is described in some detail in the
section below entitled, `RENAMING TOKENS`_.
 
 
RENAMING TOKENS
---------------
 
Token based renaming is used when you want to impose a naming
"pattern" on a group of files or directories. This is most useful
when the existing filenames have little or nothing in common. In such
situations, there's often no direct way to use string substitutions to
order the names in some coherent way.
 
A "template" is built from literal text and *renaming tokens*. These
A "token" is built from literal text and *renaming tokens*. These
tokens are delimited by the ``/`` character. **tren** replaces these
tokens with corresponding information (see descriptions below) to
produce a final "template text". The template text is the actual
produce a final "token text". The token text is the actual
string used to either replace the existing file or directory name (or
just the "name" or "extension" portions, depending on which options
you've selected) or to be appended or prepended to the name.
 
Currently, **tren** defines a number of renaming tokens.
 
File Attribute Renaming Tokens
------------------------------
---------------------------------
 
These tokens are derived from information about the file or
directory being renamed.
 
file or direcotry's owner.
 
 
Sequence Renaming Tokens
------------------------
---------------------------
 
Sometimes it's useful to rename files or directories based on some
*property they possess* like the date or time of creation, the size of
the file, who owns it, and so on. That's the idea behind the ``/D/``,
-+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ...
 
You are not restricted to numbers in a counting pattern. Letters may
also be used. **tren** will preserve the case you specify in the
template when creating sequences like this::
token when creating sequences like this::
 
000a -> 000a, 000b, 000c, ... zzzz, 000a, ...
---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ...
 
 
 
 
System Related Renaming Tokens
------------------------------
---------------------------------
 
These tokens are derived from the underlying operating system
and runtime environment.
 
Rename a file containing the ``=`` symbol::
 
tren.py -r a\=b=c\=d a=b.txt # c=d.txt
 
Use template::
Use renaming token::
 
tren.py -T /I/ file.1 # 2010-01-12
 
Use template to change file "name"::
Use renaming token to change file "name"::
 
tren.py -b -T /I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2
 
Use template to change file "extension"::
Use renaming token to change file "extension"::
 
tren.py -e -T /D/ file.1 # file.20100112
 
Get help::
-----------------------------
 
::
 
$Id: tren.rst,v 1.124 2010/01/19 20:52:14 tundra Exp $
$Id: tren.rst,v 1.125 2010/01/20 00:26:22 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren