XTRAN Example — Create File Renumbering Script

This example uses an XTRAN rules file comprising 113 non-comment lines of XTRAN's rules language ("meta-code").

These rules originally took less than two hours to write and about ½ hour to debug.  (That's right, just over two hours total!)

We then added the "not" regular expressions capability; that took ½ hour to write and ½ hour to debug.

The rules assume that files exist with names that match a given regular expression (specified via an environment variable) whose first group matches the name of each file's root entity that will be used for renumbering.  The rules create a script that will renumber the files for each entity, 1-n.

Because you specify the format for each script command, the rules can create a script for any scripting language you wish.  In this example, we create a BASH script.

To determine each file's new (renumbered) name, the rules use a printf() format (specified via an environment variable) that contains exactly one %s for the file's entity name and exactly one %d for the file's new number.  The rest of the format can be anything, but the %s must precede the %d.

The rules read the names of the files to be renumbered, one per line, from a file specified via an environment variable, ignoring blank lines and lines starting with ;.  They create a script, as the file specified via another environment variable, that will renumber all of the files for each entity sequentially.

You can optionally provide a list of one or more "not" regular expressions (via an environment variable).  If so, the rules will ignore file names that match any of them.

The rules create each renumbering script command using a format (specified via an environment variable) in which:

The resulting script can then be executed in the directory containing the files to do the renumbering.

For example, given a set of files with the names

    f-<entity>-<rest>.txt

where:
    <entity> is the file's root entity name
    <rest> is the rest of the file name

…and we want to create a BASH script to rename each entity's files to

    <entity>-001.txt
    <entity>-002.txt
    …

We use the following regular expression to match the names of the files to be renumbered, in which the group \(...\) matches <entity> in the "original file name" pattern above.

    ^f-\([A-Za-z0-9]*\)-

We specify the following "not" regular expression.

    ^f-whatsit

We use the following new file name pattern for renumbering, in which the %s represents each original file name's <entity> and the %03d represents a unique number, 1-n, that we will generate for each <entity>.

    %s-%03d.txt

We use the following script command format to create the renumbering script (BASH in this case).  Note that we use ^Q to specify double quotes in the resulting script around each original file name (^1), in case its <rest> has spaces in it.  We don't need double quotes around each new file name (^2), because we know it won't have any spaces in it.

    mv^S^Q^1^Q^S^2

How can such powerful and generalized text manipulation be automated in about 3 hours and only 113 code lines of XTRAN rules?  Because there is so much capability already available as part of XTRAN's rules language.  These rules take advantage of the following functionality:

The input to and output from XTRAN are untouched.

Process Flowchart

Here is a flowchart for this process, in which the elements are color coded:

data flowchart

Input to XTRAN:

; File names to renumber
;
f-frammis-file1.txt
f-gizmo-2.txt
f-gizmo-03.txt
f-whatsit-05.txt
f-frammis-7.txt
f-widget-number-3.txt
f-gizmo-num-5.txt
f-whatsit-02.txt
f-frammis-3.txt

Output from XTRAN — BASH script:

mv "f-gizmo-2.txt" gizmo-001.txt
mv "f-gizmo-03.txt" gizmo-002.txt
mv "f-gizmo-num-5.txt" gizmo-003.txt
mv "f-widget-number-3.txt" widget-001.txt
mv "f-frammis-file1.txt" frammis-001.txt
mv "f-frammis-7.txt" frammis-002.txt
mv "f-frammis-3.txt" frammis-003.txt