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
%s for the file's entity name and exactly
%d for the file's new number. The rest of the
format can be anything, but the
%s must precede
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
;. 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:
^1is replaced by the original file name.
^2is replaced by the new file name.
^Qis replaced by a double quote.
^Sis replaced by a space.
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
<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
<entity> in the "original file name" pattern
We specify the following "not" regular expression.
We use the following new file name pattern for renumbering, in which
%s represents each original file name's
<entity> and the
%03d represents a unique
number, 1-n, that we will generate for
We use the following script command format to create
the renumbering script (BASH in this case). Note that we
^Q to specify double quotes in the resulting script
around each original file name (
^1), in case
<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.
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:
- Text file input and output
- Text manipulation
- Delimited list manipulation
- Regular expression matching
- Environment variable manipulation
- Content-addressable data bases
- Access to XTRAN's Internal Representation (XIR)
- Creating new meta-functions written in meta-code, which we call user meta-functions
- Meta-variable and meta-function pointers
The input to and output from XTRAN are untouched.
Here is a flowchart for this process, in which the elements are color coded:
- BLUE for XTRAN versions (runnable programs)
- ORANGE for XTRAN rules (text files)
- RED for
- PURPLE for text data files
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