diff --git a/tren.rst b/tren.rst index 3c2448b..0da21ab 100644 --- a/tren.rst +++ b/tren.rst @@ -1981,7 +1981,7 @@ Type (Required): - The attribute to use to create the ordering. + The attribute used to create the ordering. Counting Alphabet (Optional): @@ -2011,7 +2011,7 @@ 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 @@ -2020,12 +2020,126 @@ 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 ======================= @@ -2062,6 +2176,12 @@ 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`` @@ -2222,7 +2342,7 @@ :: - $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: