Fork: 0
tundra / tren
Browse code
Wrote section on alphabet definition and use.
master
1 parent f57c7c1 commit 95ac8ed00a25bc2df451e91b0ea4d19a21839e66
@tundra tundra authored on 6 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
132
■■■■■
 tren.rst
- descending
Type (Required):
The attribute to use to create the ordering.
The attribute used to create the ordering.
 
Counting Alphabet (Optional):
 
The name of the counting system to use.
counting in Decimal. Note that you *cannot* omit the alphabet
delimiters, so the correct form of a sequence renaming token then
becomes::
 
/Ordering FlagType::Counting Pattern/
/OrderingType::Counting Pattern/
 
A *Counting Pattern* is optional. Counting patterns are used to do
two things: Set the initial value for the count and Describe the
layout of how the count should look. This is described in the section
below entitled, `Counting Pattern Format`_.
 
If you omit a counting pattern, **tren** will start counting from the
zero-th "number" in your chosen alphabet, producing a counting pattern
as "wide" as necessary to count all the items being renamed.
as "wide" as necessary to count all the items being renamed. In that
case, the format of a sequence renaming token becomes::
 
/OrderingType:Alphabet:/ # With explicit alphabet
/OrderingType::/ # With default decimal alphabet
 
 
Let's Learn The Alphabet
========================
 
Sequence renaming tokens are essentially "counters" that return a
number string representing where the file- or directory being renamed
sits in some order - say, by time, alphabetically or on the command
line.
 
To be as flexible as possible in creating renaming strings, it's
helpful to be able to "count" in any *base*, and use any *set of
symbols* when counting. For instance, you may prefer sequences of
letters instead of numbers. Such a sequence might look like this::
 
a
b
...
z
aa
ab
...
az
ba
bb
 
And so on.
 
**tren** has a number of standard such "counting alphabets" built in
for the most common counting situations. As described in the previous
section, you specify which of these you want to use in each sequence
renaming token reference on the command line. (If you omit naming a
specific alphabet, the token will default to counting in Decimal.)
 
The built in alphabets are::
 
Binary - Counting in Base 2 using numbers
Octal - Counting in Base 8 using numbers
Decimal - Counting in Base 10 using numbers
HexLower - Counting in Base 16 using numbers and lower case letters
HexUpper - Counting in Base 16 using numbers and upper case letters
Lower - Counting in Base 26 using lower case letters
LowerUpper - Counting in Base 52 using first lower- then upper case letters
Upper - Counting in Base 26 using upper case letters
UpperLower - Counting in Base 52 using first upper- then lower case letters
 
 
.. NOTE:: **The difference between a "base" and a "symbol set".**
 
In order to make such counting-based renamings as flexible
as possible, **tren** is built to be able to count *in any
base* (2 or higher) and *make use of any symbol set*.
What's the difference? The "base" tells you how many
symbols there are in your counting system. In Decimal, for
example, there are 10. The "symbol" set, assigns a
character to represent each of those positions. In Decimal,
we customarily use, "0", "1", "2", and so on. However,
there is nothing magical about the symbol set. It is the
*base* that defines the counting system. The symbol set is
just an arbitarary representation. For instance, there's no
reason we can count in base 10, using the symbols, ")", "!",
"#", "$", ... and so on.
 
This ability to use any symbol set in any base makes it easy to
construct counting strings that suit your particular renaming needs.
You do this by defining your own, custom counting "alphabet" via the
``-A`` command line option::
 
-A AlphabetName:string-of-characters
 
Once defined, later renaming tokens on the command line can refer to
it via the ``/...:AlphabetName:.../`` syntax discussed previously.
 
Say we do this::
 
tren.py -A Foo:s2X -r=/+MTIME:Foo:/ *
 
This will rename all the files in the current directory in "mtime" timestamp
ascending order using the following counting scheme::
 
s
2
X
ss
s2
sX
2s
22
2X
 
And so on. You can use most any combination of characters you like to
customize your sequence renaming token output. There are a few things to
keep in mind, however:
 
- The counting *base* is determined by the *length of the symbol set*
not what characters you use.
 
- You can define as many new alphabets as you like on the command line.
 
- The alphabet name is case sensitive. ``Foo``, ``FOO``, and ``foo``
are all different alphabet names (assuming they are all defined).
 
- There is no requirement that the symbol set be built out of unique
characters. **tren** does no analysis of your symbol set at all,
so this is permitted (if not recommended)::
 
-A Foo:abcx123xj3,m2
 
- Similarly, you can populate your alphabet with any symbols you
like, BUT remember they're going to be embedded in some file-
or directory name. It's a good idea to make sure you avoid illegal
or undesirable characters like ``/``, ``\``, and ``-`` in your
alphabets so they don't end up getting embedded in a name (or trying
to, anyway).
 
 
Counting Pattern Format
=======================
on some property common to everything being renamed*. Keep in mind
that for purposes of sequencing, **tren** *makes no distinction
between a file and directory*. It merely sequences based on the
property you requested.
 
NOTE HERE ABOUT COMMAND LINE LIST V. FILES ACTUALLY PROCESSED
 
NOTE HERE ABOUT WHAT HAPPENS WHEN MORE THAN ONE FILE/DIR MAPS
TO SAME PROPERTY.
 
 
**tren** currently supports the following kinds of sequencing:
 
``/+-ADATE:Alphabet:FormatField/ Sequence based on``
-----------------------------
 
::
 
$Id: tren.rst,v 1.175 2010/04/05 20:33:20 tundra Exp $
$Id: tren.rst,v 1.176 2010/04/06 21:44:45 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren