Many small edits and cleanup of the renaming tokens material.
1 parent 72d3fb8 commit 9bd9a5953e242c3de630eac02c4d4a46ba9f3aae
@tundra tundra authored on 1 Apr 2010
Showing 1 changed file
View
119
tren.rst
operations. Once you've got a sense of what
**tren** can do, the reference section will be handy to look up
options and their arguments.
 
.. WARNING:: **tren** is very powerful and can easily and
.. DANGER:: **tren** is very powerful and can easily and
automatically rename things in ways you didn't intend.
It is ***strongly*** recommended that you try out new
**tren** operations with the ``-t`` option on the command
line. This turns on the "test mode" and will show you
 
TUTORIAL AND DESCRIPTION
------------------------
 
.. WARNING:: ONE MORE TIME: **tren** is a powerful file and directory
.. DANGER:: ONE MORE TIME: **tren** is a powerful file and directory
renaming tool. Be **sure** you know what you're about to
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!
 
2) Make sure the renaming requests operate on completely
disjoint parts of the file name.
 
.. NOTE:: Similarly, **tren** remembers the last state of each option
.. TIP:: Similarly, **tren** remembers the last state of each option
as you move from left to right on the command line. For instance::
 
tren.py -i1 -r f=F -r o=O foo1-foo2-foo3.foo4
 
 
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).
 
.. NOTE:: Always remember" **The Rightmost Renaming Request "Wins"!**
.. TIP:: Always remember" **The Rightmost Renaming Request "Wins"!**
 
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
An Overview Of Renaming Tokens
==============================
 
**tren** implements the notion of *renaming tokens*. These can
appear in either the ``old`` or ``new`` string components of a ``-r``
renaming argument.
be a bit complex to grasp at first, so we'll introduce them
"gently" in the next few sections and then dive into the detail
thereafter.
 
It is sometimes useful to be able to take a group of files or rename
them using some property they possess like creation date, size,
owner's name, and so on. This is the purpose of renaming tokens.
directory being renamed was last modified* and use that string in the
renaming process::
 
tren.py -ryear=/MYEAR/ My-year.txt # New name: My-2010.txt
 
Renaming tokens can appear in either the ``old`` or ``new`` string
components of a ``-r`` renaming argument. Wherever they appear,
they are "resolved" by **tren** before any renaming is attempted.
By "resolved", we mean that the renaming token will be *replaced
with a string that represents its meaning*. For example::
 
tren.py -i : -r boo=/SIZE/ boors-and-boots.txt
 
This replaces all the instances of the literal string ``boo`` with
the *length* of the file ``boors-and-boots.txt``. When we're done
the file will be renamed something like::
 
23rs-and-23ts.txt
 
This is a silly example but it serves to illustrate the point -
all renaming tokens get turned into *strings* before any renaming
is attempted.
 
.. NOTE:: Deep under the covers of it all, **tren** really only
knows how to do string replacement. That is, it can
replace some ``old`` string with some ``new`` string.
All the rest of the features you see are sort of
syntactic sugar to make it easy for you to express your
renaming intent. When **tren** runs, it must resolve all
that fancy syntax and boil it down to creating a new file
name the underling operating system knows how to produce
via its renaming services.
 
A really handy way to use renaming tokens is to name your files in a
particular *order*. For example, suppose you and your friends pool
your vacation photos but each of your cameras uses a slightly
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
*file* renaming tokens (that know thing about the file being renamed)
*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)::
 
tren.py -r =/MYEAR//MMON//MDAY/-MyVacation-/+MDATE::0001/.jpeg *.jp*
 
Every place you see something in the form ``/.../``, think, "That is a
renaming token whose value will be filled in by **tren**." This
syntax is the same whether you're using a *file attribute*-, *system*-, or
syntax is the same whether you're using an *attribute*-, *system*-, or
*sequence* renaming token.
 
This would rename all the files in the current directory ending with
``.jp*``. The ``/MYEAR/...`` would be replaced with the *date* the
 
.. 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 "replace
everything" in the existing file or directory name.
everything" in the existing file or directory name with our
newly concocted naming scheme.
 
Of course, you don't *have* to replace the entire filename when
using tokens. It's perfectly legitimate to replace only
a portion of the existing name::
Most commonly, you'll find yourself using the command line,
alphabetic, original name, length, and various time/date renaming
tokens.
 
.. NOTE:: **tren** is portable across many operating systems because
.. TIP:: **tren** is portable across many operating systems because
it is written in the Python programming language. Python
*mostly* works the exact same way everywhere. However,
Windows presents some problems because it does not quite
work the same way as Unix-derived OSs do. In particular, if
requests only apply to some of the file names you passed on the
command line, you may find the resulting sequence unexpected. Say you
have three files, ``a``, ``b``, and ``c`` and you do this::
 
tren.py -rb=/FNAME/-/+FNAME::001/ a b c
tren.py -rb=/FNAME/-/+FNAME::001/ b c a
 
Only file ``b`` has a matching ``old`` string and thus is the only
file renamed. However, because it is second alphabetically *in the
list of files passed on the command line*, it gets renamed to
``b-002``. The way to avoid this surprise is to make sure any
renaming request with sequence renaming tokens in it is constructed so
that it applies to *all* the files- and directories named on the
command line.
file renamed. However, because it is second alphabetically *of all
the files named on the command line*, it gets renamed to ``b-002``.
The way to avoid this surprise is to make sure any renaming request
with sequence renaming tokens in it is constructed so that it applies
to *all* the files- and directories named on the command line.
 
 
General Attribute Renaming Tokens
=================================
 
``MTIME`` refers to the last time the file- or directory *itself was
modified*.
 
This is updated whenever the file- or directory itself is modified.
This is updated whenever the file- or directory is closed after
modification.
 
**tren** implements a set of time-related file attribute renaming
tokens intended to provide full access to these various timestamps. They
are identically named, except that the first letter of each of the
 
 
``/RAND#/ Random Number Generator``
 
This generates a (quasi) random number string ``#``
This generates a (quasi) random number string, ``#``
digits wide.
 
This can be useful when you want to guarantee that no
renaming operation will generate a new name that
========================
 
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/``,
``/L/``, and ``/T/`` renaming tokens described in the previous section.
the file, who owns it, and so on. That's the idea behind the
attribute renaming tokens described in the previous sections.
 
An extension of this idea is to *order all the files being renamed*
based on one of these parameters. For instance, instead of actually
embedding the date and time of creation in a file or directory name,
 
This is the purpose of *sequence renaming tokens*. They give you
various ways to create sequences that can be embedded in the final
file or directory name.
 
.. TIP:: Many sequence renaming tokens described below share the
same name with an attribute renaming token described in
the previous sections. That's because they are based on
the same property of the file- or directory being
renamed. However, it's easy to tell which is which:
Sequence renaming tokens always begin with either ``+``
or ``-`` (to indicate ascending- and descending ordering
respectively).
 
So, ``/GROUP/`` is an attribute renaming token that
returns the group *name* for the file. However,
``/+GROUP.../`` is a sequence renaming token that returns
a number indicating what *position* the file is in when
all the files named on the command line are *ordered by
their group names*.
 
 
General Format Of Sequence Renaming Tokens
==========================================
 
FIX THISSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
 
 
Let's Learn The Alphabet
========================
 
 
Count Pattern Format
====================
 
The counting pattern is used to specify two things: The width of the
 
``/+-USER:Alphabet:FormatField/ Sequence based on``
 
Explanation
 
 
COMMON TASKS AND IDIOMS
-----------------------
 
With a program as feature dense as **tren**, it's not
possible to document every possible use case. The following
examples cover many common applictions of the program.
 
- Literal String Replacement
 
- Changing A File's "Extension" Suffix
 
- Appending- Or Prepending Strings To An Existing File Name
 
- Ordering File Names By Last Modification Time
 
- Ordering File Names By Modification Time Within Date
 
- Ordering File Names By Size
 
 
BUGS, MISFEATURES, OTHER
------------------------
-----------------------------
 
::
 
$Id: tren.rst,v 1.168 2010/04/01 21:55:53 tundra Exp $
$Id: tren.rst,v 1.169 2010/04/02 03:15:49 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren