Fork: 0
tundra / tren
Browse code
Many typos and minor edits fixed.
master
1 parent b04a867 commit 4b6ef1d231c3eed5ea6356f678d314e7236c8128
@tundra tundra authored on 20 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
278
■■■■■
 tren.rst
--------
 
::
 
tren.py [-1aCcbefghqtvXx] [-F file] [-l string] [-r old=new]... file|dir file|dir ...
tren.py [-1aCcbEefghqtvXx] [-F file] [-l string] [-r old=new]... file|dir file|dir ...
 
 
OPTIONS
-------
 
This option is provided so you can toggle the program back to
its default behavior after a previous ``-g`` on the command
line.
 
This option is ignored during regular expression processing
(``-x``).
 
-a Rename within the entire file or directory name
 
(*Default*: This is the program default)
contents or type of file. By default, **tren** does renaming
in the entire filename *including* the extension. For example
doing this::
 
tren.py -g -r eg=ug peg.jpeg
tren.py -g -r e=u peg.jpeg # -g = "rename all"
 
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 -g -b -r eg=ug peg.jpeg # Renames file to pug.jpeg
tren.py -g -b -r e=u peg.jpeg # Renames file to pug.jpeg
-C Do case-sensitive renaming
 
(*Default*: This is the program default)
This option is provided so you can toggle the program back to
its default behavior after a previous ``-c`` on the command
line.
 
This option is ignored during regular expression processing
(``-x``).
 
-c Collapse case when doing string substitution.
 
(*Default*: Search for string to replace is case sensitive)
 
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
 
This option is ignored during regular expression processing
(``-x``).
 
-e Only perform renaming within "extension" portion of
or directory name.
 
(*Default*: Substitute within the entire file or directory name)
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
 
-E Continue renaming even after an error is encountered
 
(*Default*: Stop processing after any error)
 
-F file Read command line arguments from ``file``
 
It is possible to perform multiple renaming operations in one
# Example replacement string file
# Each line appended sequentially
# to the command line
 
-x
-r t[ext]+=txt # Appended first
-c -g my=Mine
-X
-r =/L/ -r foo=bar
 
.. NOTE:: There is one important difference between an actual
command line and keeping the arguments in a file like
this. *Filename wildcards are not expanded within the
file.* ``*.txt`` will typicaly create a list of files
ending in ``.txt`` when given on the command line.
However, the ``*`` metacharacter has no meaning like this
when used inside an arguments file.
file.* ``*.txt`` will typically be expanded by a command
shell to create a list of files ending in ``.txt``.
However, the ``*`` metacharacter has no such meaning when
used inside an arguments file.
 
-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
-g Replace all instances (global rename) 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::
option to enable "global" renaming::
 
tren.py -g -r p:P pop.txp # Renames file to: PoP.txP
 
This option is ignored during regular expression processing
(``-x``).
 
-h Print help information.
 
 
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
tren.py -g -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
simpler tools to provide higher-level renaming capabilities.
 
**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 a warning message will be
file or directory being processed and an error message will be
displayed. This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename. You can override this default and *force* a renaming and thus
the removal of such existing files or directories (``-f`` option).
 
tren.py -r old=new <list of files, directories to rename>
 
 
The ``old`` and ``new`` string are built using a variety of
The ``old`` and ``new`` renaming strings are built using a variety of
building blocks:
 
============================= =============================
*Old Strings Are Built With:* *New Strings Are Built With:*
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
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
"extension" (``-e``) portions of the filename.
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**
command line::
 
tren.py -r .Jpeg=.jpg -r old=ReallyOld *
tren.py -g -r .Jpeg=.jpg -r old=ReallyOld *
 
This would rename all the files in the current directory, replacing
``.Jpeg`` with ``.jpg`` and ``old`` with ``ReallyOld`` anywhere these
strings appeared in any of the file or directory names.
 
By default, only the first instance of the string is replaced in the
name, but you can use the ``-g`` option to replace *all* instances of
the old string with the new one.
 
If you need to include the equals sign as part of the old string or
the new string literal text, you have to escape it (``\=``)::
 
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: ``\=``.
 
Regular expression processing is unaffected by the ``-g / -1`` (global
rename) and ``-c / -C`` (ignore case) options. That's because there
are regular expression mechanisms for achieving the same thing. More
importantly, if you've selected regular expression matching, it's
probably because you want very fine grained control of the renaming
defined by the regex. In short, regular expression matching always
takes place on the *original characters* of the target portion of the
name and does replacement as called for in the regex itself.
 
 
 
An Overview Of Renaming Tokens
------------------------------
 
**tren** implements the notion of *Renaming Tokens*. These can
appear in either the old- or the new string components of a ``-r``
appear in either the ``old`` or ``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
 
 
**tren** has many other kinds of renaming tokens. Their
structure and use is described in some detail in the
next section.
section below entitled `RENAMING TOKENS: THE GORY DETAILS`_.
 
 
COMMAND LINE TOGGLES
--------------------
 
**tren** defaults a specific set of behaviors:
**tren** defaults to a specific set of behaviors:
 
- ``old`` and ``new`` renaming text is treated *literally*
- Renaming takes place within *the entire filename*
- *Only the first instance* of ``old`` is replaced with ``new``
It's important to understand some subtleties of just how **tren**
works, particularly if you intend to create complex, multi-replacement
command lines:
 
- Command line processing is from left to right. As we saw in the
- Command line processing is from left to right. As we saw in the
`COMMAND LINE TOGGLES`_ above, this means the options can be
different for each renaming operating you specify.
 
- Regular expression processing is unaffected by the ``-g / -1``
(greedy replace) and ``-c / -C`` (ignore case) options. That's
because there are regular expression mechanisms for achieving the
same thing. More importantly, if you've selected regular
expression matching, it's probably because you want very fine
grained control of the renaming defined by the regex. In short,
regular expression matching always takes place on the *original
characters* of the target portion of the name and does replacement
as called for in the regex itself.
(global rename) and ``-c / -C`` (ignore case) options.
 
- Filenames may be absolute, relative, or implict (to the current
working directory). **tren** keeps track of this and can do
renaming in directories other than the current one.
 
- **tren** processes each renaming string in the following
manner:
 
 
2) Replace all renaming tokens with their equivalent
text in both the ``old`` and ``new`` renaming strings.
 
3) If ``-c`` is in effect, collapse the target and the ``old``
renaming string to *lower case* before checking for a match.
 
4) Replace the first- (default and ``-1``) or all (``-g``) instances
of ``old`` with ``new``.
3) If doing literal string replacement:
 
- If ``-c`` is in effect, collapse the target and the ``old``
renaming string to *lower case* before checking for a match.
 
- Replace the first- (default and ``-1``) or all (``-g``)
instances of ``old`` with ``new``. 4)
 
4) If doing regular expression processing, replace any regex
matches with the corresponding ``new`` string. Keep in mind
that if ``-x`` is selected the *entire* ``old`` string is
treated as a Python regular expression. Pay particular
attention to this if you're combing literal text and/or
renaming templates with regular expression metacharacters.
 
- When all the renaming operations are complete - and thus a new filename
has been constructed - **tren** checks to see if a file or directory
by that name already exists. Unless the ``-f`` flag is in force,
**tren** will refuse to do a renaming *over an existing filename*.
If the new filename does not exist, **tren** will attempt the
renaming. If the rename fails for some reason - say you don't
have permission to rename a particular file or directory - you'll
see an error message to that effect.
 
- By default, **tren** will stop processing on any error. You
can override this with the ``-E`` option. In that case,
an error message will be displayed. No matter what caused
the error, **tren** will skip the file currently being processed
and go on to the next one.
 
 
RENAMING TOKENS: THE GORY DETAILS
---------------------------------
 
As we've just seen, a *Renaming Token* is nothing more than
a string representing something **tren** knows about one of
three things:
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
- A sequence that reflects some ordering principle
This token is replaced with the date of creation
of the file or directory being renamed. It is
in ``yyyymmdd`` format.
 
``/dd/ File or directory day of creation``
 
This token is replaced with the the day of the month the
file was created in ``dd`` format.
 
``/dy/ File or directory day of creation``
 
This token is replaced with the the name of the day the
file was created in ``Ddd`` format.
 
``/E/ Original File Extension``
 
This token is replaced the "extension" portion of the file
or directory before renaming. This does not include the
 
This token is replaced with the name of the
primary group to which the file belongs.
 
``/hh/ File or directory hour of creation``
 
This token is replaced with the hour the file was
created in ``hh`` format.
 
``/I/ File or directory creation date in ISO format``
 
This token is replaced with the date of creation of the
file or directory being renamed. It is similar to ``/D/``
except it is in ISO format, ``YYYY-MM-YY``.
except it is in ISO format, ``YYYY-MM-DD``.
 
``/L/ File or directory length``
 
This token is replaced with a numeric string
that indicates the length of the file or directory
in bytes.
 
``/mm/ File or directory minutes of creation``
 
This token is replaced with the minutes the file was
created in ``mm`` format.
 
``/mo/ File or directory month of creation``
 
This token is replaced with the numeric month the file was
created in ``mm`` format.
 
``/my/ File or directory month of creation``
 
This token is replaced with the abbreviated name of the
month the file was created in ``Mmm`` format.
 
``/ss/ File or directory seconds of creation``
 
This token is replaced with the seconds the file was
created in ``ss`` format.
 
``/T/ File or directory creation time``
 
This token is replaced with the time of creation
of the file or directory being renamed. It is
in ``hh:mm:ss`` format.
This token is replaced with the time of creation of the
file or directory being renamed. It is in ``hh:mm:ss``
format. This is equivalent to ``/hh/:/mm/:/ss/``.
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
file or directory's owner.
 
``/d/ File or directory day of creation``
 
This token is replaced with the the day of the month the
file was created in ``dd`` format.
 
``/h / File or directory hour of creation``
 
This token is replaced with the hour the file was
created in ``hh`` format.
 
``/m/ File or directory minutes of creation``
 
This token is replaced with the minutes the file was
created in ``mm`` format.
 
``/o/ File or directory month of creation``
 
This token is replaced with the numeric month the file was
created in ``mm`` format.
 
``/ooo/ File or directory month of creation``
 
This token is replaced with the abbreviated name of the
month the file was created in ``Mmm`` format.
 
``/s/ File or directory seconds of creation``
 
This token is replaced with the seconds the file was
created in ``ss`` format.
 
``/y/ File or directory year of creation``
``/yyyy/ File or directory year of creation``
 
This token is replaced with the year the file was
created in ``yyyy`` format.
 
 
 
``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the text
This token is replaced with the string
returned by executing the ``cmd`` command.
 
For instance, you might want to prepend the name
of the system to a all you shell scripts::
 
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/``,
``/T/``, and ``/S/`` renaming tokens described in the previous section.
``/L/``, and ``/T/`` renaming tokens described in the previous section.
 
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,
 
BUGS AND MISFEATURES
--------------------
 
On windows platforms, the ``/U/`` and ``/G/`` renaming tokens return
``winuser`` and ``wingroup`` respectively. They do not return the
underlying operating system ownership information.
 
On windows platforms, the ``/U/`` and ``/G/`` do not return the
underlying operating system ownership information.. They return
``winuser`` and ``wingroup`` respectively.
 
COPYRIGHT AND LICENSING
-----------------------
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.130 2010/01/20 22:26:26 tundra Exp $
$Id: tren.rst,v 1.131 2010/01/20 23:50:20 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren