Fork: 0
tundra / tren
Browse code
Finished section on command line pitfalls.
master
1 parent 062365e commit 832cf8c5ddccf62ce89d99047912ce9537c17b6d
@tundra tundra authored on 25 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
141
■■■■■
 tren.rst
tren.py -i 1: -r f=b foo1-foo2-foo3.foo4 # New Name: foo1-boo2-boo3.boo4
 
tren.py -i :-2 -r f=b foo1-foo2-foo3.foo4 # New Name: boo1-boo2-foo3.foo4
 
 
Note that you cannot specify individual, non-adjacent instances.
There is no way to use a single **tren** command to replace, say, the
only the 2nd and the 4th instance of an "old" string. Doing that
requires two renaming requests. The good news is that we can do them
 
tren.py -i1 -r foo=bar -i2 -r foo=bar foo1-foo2-foo3.foo4
 
 
More About Command Lines
========================
 
As we just saw, you can get surprising results as you process
the command line from left to right, as **tren** works its way
through the various renaming requests. There are other potential
pitfalls here, so it's helpful to understand just *how* **tren**
processes your command line, step-by-step:
More About Command Line Pitfalls
================================
 
As we just saw, you can get surprising results as **tren** works its
way through the command line from left to right. There are other
potential pitfalls here, so it's helpful to understand just *how*
**tren** processes your command line, step-by-step:
 
1) Prepend the contents of $TREN to the user-provided command line.
 
This allows you to configure your own default set of options
so you don't have to type them in every time.
This allows you to configure your own default set of options so
you don't have to type them in every time.
 
2) Resolve all references to include files.
 
This has to be done before anything that follows, because
include files add options to the command line.
 
3) Build a table of every file name to be renamed.
 
We'll need this information if any of the renaming
requests use renaming tokens.
 
4) Build a table containg each renaming request storing
the current state of every program option at that
point on the command line.
 
This allows **tren** to apply options differently
to different renaming requests on the same command
line. This came in handy in our example of the
previous section.
 
5) Process each file found on the command line in
left to right order, applying every each renaming
request, again as it appeared from left to right on
the command line.
 
Simple eh? Well, mostly it is ... until it isn't. As we
just saw, incrementally building up a new name with multiple
renaming requests can produce unexpected results and we have
to plan for them.
 
Similarly, you can inadvertently rename *the wrong file* ... this is
usually a Bad Thing. Say you have two files, ``x`` and ``y``.
You want to rename ``x`` to ``y`` and ``y`` to ``Y``. Well,
order matters here. Say you do this::
 
tren.py -frx=y -ry=Y x y
 
**tren** tries to rename ``x`` to ``y`` and spots the fact that ``y`` already
exists, so it makes a backup, ``y.backup``, and renames ``x`` to ``y`` as
requested. TO BE CONTINUED
 
We'll need this information if any of the renaming requests use
renaming tokens.
 
4) Build a table containg each renaming request storing the current
state of every program option at that point on the command line.
 
This allows **tren** to apply options differently to different
renaming requests on the same command line. This came in handy
in our example of the previous section.
 
5) Process each file found on the command line in left to right
order, applying each renaming request, in the order it appeared
from left to right on the command line.
 
Simple eh? Well, mostly it is ... until it isn't. As we just saw,
incrementally building up a new name with multiple renaming requests
can produce unexpected results and we have to plan for them.
 
Similarly, you can inadvertently accidentally give a file the *wrong
name entirely* ... this is usually a Bad Thing.
 
Say you have two files, ``x`` and ``y``. You want to rename ``x`` to
``y`` and ``y`` to ``z1``. Well, order matters here. Say you do
this::
 
tren.py -fr x=y -r y=z1 x y
 
Let's see what happens in order:
 
1) File ``x`` renaming::
 
x -> y
y -> z1
 
So, file ``x`` is renamed ``z1`` (!)
 
2) File ``y`` renaming::
 
y -> z1 .... oops, x1 exists, we need a backup
 
z1 -> z1.backup
 
y -> z1
 
Um ... not quite what we wanted. However, if we shuffle around the
order of renaming arguments AND the order in which to process the
files, we can get what we want::
 
tren.py -r y=z1 -r x=y y x
 
Notice that we can drop the ``-f`` option because there is no longer a
naming conflict (see the next section for more about forced renaming).
 
The point here, as we've said already, is that you have to be very
careful when constructing command lines, keeping track of options, and
*what order* you specify both renaming requests *and* the files- and
directories to be renamed. As always, the simple way around this is
to run multiple, separate **tren** commands, each with its own single
renaming request.
 
 
Forcing Renaming
================
-----------------------------
 
::
 
$Id: tren.rst,v 1.151 2010/03/26 00:57:04 tundra Exp $
$Id: tren.rst,v 1.152 2010/03/26 01:42:13 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren