Fork: 0
tundra / tren
Browse code
Integrated DML's edits.
master
1 parent c7fbe37 commit 430bae4cf0affd634eff30ffb55c474bbc080f33
@tundra tundra authored on 23 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
62
■■■■■
 tren.rst
 
Both of these refer to the last instance of old string
``foo`` (found at ``foo4`` in our example name).
 
Sometimes, you'd like to replae a whole *range* of
Sometimes, you'd like to replace a whole *range* of
instances. An "instance range" is specified using the
``:`` separator in the form::
 
-i first-to-replace:stop-here
targets.
 
(*Default*: .backup)
 
If you choose to force renaming if files when the new
If you choose to force file renaming when the new
name already exists (``-f``), **tren** simply renames
the existing file or directory by appending a suffix to
it. By default, this suffix is ``.backup``, but you
can change it to any string you like with the ``-S```
have been warned!
 
The following sections are designed for the new- or occasional
**tren** user. They begin with the simplest of **tren** operations
and incrementally build more- and more complex examples, eventually
and incrementally build more and more complex examples, eventually
describing all of **tren**'s capabilities.
 
 
Overview
 
tren.py -r foo=bar -r foo=baz foo1-foo2-foo3.foo4
 
Produces ... wait a second ... why on earth are there two renaming
requests with idential ``old`` strings on the same command line?
requests with identical ``old`` strings on the same command line?
Shouldn't this produce a final name of ``baz1-foo2-foo3.foo4``?
 
Nope. After the leftmost renaming request has been processed,
the new name is ``bar1-foo2-foo3.foo4``. Remember that, by
We'll need this information if any of the renaming requests use
the file attribute- or sequence renaming tokens (discussed
later in this document).
 
4) Build a table containg each renaming request storing the current
state of every program option at that point on the command line.
4) Build a table containing 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.
 
Changing The Renaming Separator & Escape Characters
===================================================
 
There may be times when the default renaming separator (``=``)
and/or escape character (``\``) make it clumsy to construct a
renaming request. This can happen if, say, either the old- or new
string in a literal renaming needs to use the ``=`` symbol many
times. Another case where this may be helpful is when constructing
complex regular expressions than need to make use of these characters.
There may be times when the default renaming separator (``=``) and/or
escape character (``\``) make it clumsy to construct a renaming
request. This can happen if, say, either the old- or new string in a
literal renaming needs to use the ``=`` symbol many times. Another
case where this may be helpful is when constructing complex regular
expressions that need to make use of these characters.
 
The ``-R`` and ``-P`` options can be used to change the character
used for renaming separator and escape character respectively. You
can use any character you like (these must be a single character
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. We can, by combining
*attribute* renaming tokens (that know thing about the file being renamed)
and *sequence* renaming tokens (that know how to order all the files
being renamed by some key like date, length, who owns it, and so on)::
*attribute* renaming tokens (that know things about the file being
renamed) and *sequence* renaming tokens (that know how to order all
the files being renamed by some key like date, length, who owns it,
and so on)::
 
tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp*
 
Every place you see something in the form ``/.../``, think, "That is a
=======================
 
As we saw in earlier sections, **tren** command line option and file
name interaction can be tricky. It can depend on order and on whether
the various renaming request "collide" with each other as a new file
the various renaming requests "collide" with each other as a new file
name is computed. A similar potential collision exists between
renaming tokens and renaming requests. Recall from `More About
Command Line Pitfalls`_ that renaming tokens are resolved *before* a
renaming request is processed. This means that the string
a string representing something **tren** knows about. These
fit in one of three categories:
 
- An attribute of the file or directory being renamed
- An attribute of the underling operating system environment
- An attribute of the underlying operating system environment
- A sequence that reflects some ordering principle
 
Renaming tokens are delimited by ``/`` characters, in the form::
 
 
original_name-YYYY-length # Example: myfile-2010-4099
 
In short, attributes are just string substitutions wherein the string
tells you someting about the file or system on which you're working.
tells you something about the file or system on which you're working.
 
"Sequences", on the other hand, are just *numbers that represent some
ordering principle*. Say you use the sequence renaming token ordered
by size, ``/+SIZE::001/`` to rename 10 files of different sizes::
- The order the file appears *alphabetically*
- The *original name* of the file before any renaming took place
- The date/time it was last *accessed*
- The date/time it was last *modified*
- The date/time it's directory entry (inode) was last *modified*
- The date/time its directory entry (inode) was last *modified*
- The *inode number* for the file
- The *device number* where the directory entry (inode) lives
- The *numeric group ID* the file belongs to
- The *name of the group* the file belongs to
 
``/NLINK/ Returns Number Of Links To File- Or Directory Being Renamed``
 
Most operating systems allow a single file to have
multiple names. These names are "linked" to the an
instance of the file. This replacement token is a
numeric string representing the number of such links.
multiple names. These names are "linked" to the instance
of the file. This replacement token is a numeric string
representing the number of such links.
 
``/SIZE/ Returns File- Or Directory's Length In Bytes``
 
This is handy if you want a sorted directory listing to
stripped from the results, since they don't belong in
file names. Spaces, however, are preserved.
 
For instance, you might want to prepend the name of the
system to all you shell scripts::
system to all your shell scripts::
 
tren.py -r ='/`uname -n`/'-/FNAME/ *.sh # Unix shells
tren.py -r ="/`uname -n`/"-/FNAME/ *.sh # Windows shells
 
 
 
``/+-USER:Alphabet:FormatField/ Sequence based on user name``
 
This returns a sequence ordered by the name of the user that own
This returns a sequence ordered by the name of the user that owns
the file- or directory.
 
This is only supported on Windows if the ``win32all`` Python extensions
are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``.
This can be undone by::
 
tren.py -r '/$LOGNAME/'-= *
 
Generally, if you can isolate the newly introduced text of the
renaming and place use it as the ``old`` string in a renaming
request, this will work.
Generally, if you can isolate the text introduced by the previous
renaming operation, and use it as the ``old`` string in another
renaming request, this will work.
 
 
ODDS AND ENDS
-------------
is still backleveled to 2.5.x. When and if the
**cygwin** team upgrades to 2.6.x, **tren** is expected
to work there as well.
 
This program is **EXPERIMENTAL** (see the license). This means it's
This program is **EXPERIMENTAL** (see the license). This means its
had some testing but is certainly not guaranteed to be perfect. As of
this writing, it has been run on FreeBSD, Linux, Windows XP, and Mac
OS X. It has not, however, been run on 64-bit versions of those OSs.
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.181 2010/04/07 23:00:56 tundra Exp $
$Id: tren.rst,v 1.182 2010/04/23 16:13:45 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren