Fork: 0
tundra / tren
Browse code
Began working on tutorial section.
master
1 parent 4ac1267 commit 58df5a36ba2d40c85c120982cb608c9c22c64c96
@tundra tundra authored on 23 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
136
■■■■■
 tren.rst
do. If you're not, run the program in test mode (invoke
with the '``-t``' option) to see what would happen. You
have been warned!
 
Overview
========
 
**tren** is a general purpose file and directory renaming tool. Unlike
commands like '``mv``', **tren** is particularly well suited for
renaming *batches* of files and/or directories with a single command
line invocation. **tren** eliminates the tedium of having to script
simpler tools to provide higher-level renaming capabilities.
simpler tools to provide higher-level renaming capabilities.
 
**tren** is also adept at renaming only *part of an existing file
or directory name* either based on a literal string or a regular
expression pattern. You can replace any single, group, or all
instances of a given string in a file or directory name.
 
**tren** implements the idea of a "Renaming Token" which is
a symbolic variable that is resolved at runtime to create a new
file name. Renaming Tokens allow you to embed information about
the file's time or length, the contents of an environment variable,
and even the output of an arbitrary command line program into the new
name of a file.
 
**tren** can automatically generate *sequences* of file names based on
their dates, lengths, times within a given date, and so on. In fact,
sequences can be generated on the basis of any of the file's
'``stat``' information. Sequence "numbers" can be ascending or
descending and the count can start at any initial value. Counting can
take place in one of several internally defined counting "alphabets"
(decimal, hex, octal, alpha, etc.) OR you can define your own counting
alphabet. This allows you to create sequences in any base (2 or
higher please :) using any symbol set for the count.
 
**tren** will not allow you to rename a file or directory if one with
the new name already exists. Such attempts will cause no change to the
file or directory being processed and an error message will be
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
This would rename all files (or directories) whose names contained the
string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's not
quite right. Unless you specify the '``-g``' option, *only the first
(leftmost) instance of '``old``' is replaced with '``new``'*.
 
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 "extension" ('``-e``') portions of the filename.
 
You may specify multiple replacement operations ('``-r``') on the **tren**
string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's
not quite right. Unless you specify otherwise with the '``-i``'
option, *only the first (leftmost) instance of '``old``' is replaced
with '``new``'*. So, for example, if you started out with the file,
'``My.Jpeg.Jpeg``' and ran the command above, you'd end up with a
new file name of '``My.jpg.Jpeg``'
 
 
Substitution Instances
======================
 
 
Multiple Substitutions
======================
 
You may specify multiple '``-r``' replacement operations on the **tren**
command line::
 
tren.py -g -r .Jpeg=.jpg -r old=ReallyOld *
 
 
tren.py -r name\=bob=name\=sally name=bob.dbms
 
This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'.
 
Forcing Renaming
================
 
Ignoring Case
=============
 
The Strange Case Of Mac OS X And Windows
========================================
 
Mac OS X and Windows have an "interesting" property that makes case
handling a bit tricky. Both of these operating systems *preserve*
case in file and directory names, but they do not *observe* it. (It
is possible to change this behavior in OS X when you first prepare a
drive, and make the filesystem case sensitive. This is rarely done in
practice, however.)
 
These OSs show upper- and lower- case in file names as you request,
but they do not *distinguish* names on the basis of case. For
instance, the files '``Foo``', `''foo``', and '``FOO``', are all the
same name in these operating systems, and only one of these can exist
in a given directory. This can cause **tren** to do the unexpected
when your renaming command is doing nothing more than changing case.
Suppose you start with a file called '``Aa.txt``' and run this
command::
 
tren.py -rA=a Aa.txt
 
**tren** will immediately complain and tell you that the file
'``aa.txt``' already exists and it is skipping the renaming. Why?
Because from the point-of-view of OS X or Windows, '``aa.txt``' (your
new file name) is the same as '``Aa.txt``' (your original file name).
you attempt to force the renaming::
 
tren.py -frA=a Aa.txt
 
Guess what happens? Since **tren** thinks the new file name already
exists, it backs it up to '``aa.txt.backup``'. But now, when it goes
to rename the original file ... the file is *gone* (thanks to the
backup renaming operation)! **tren** declares an error and
terminates.
 
This is not a limitation of **tren** but a consequence of a silly
design decision in these two operating systems. As a practical
matter, the way to avoid this issue is to never do a renaming
operation in OS X or Windows *that only converts case*. Try
to include some other change to the filename to keep the
distinction between "old name" and "new name" clear to the
OS. In the worst case, you'll have to resort to something like::
 
tren.py -rA=X Aa.txt
tren.py -rX=a Xa.txt
 
 
 
Using Regular Expressions
-------------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.141 2010/03/23 20:19:17 tundra Exp $
$Id: tren.rst,v 1.142 2010/03/23 21:01:12 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren