quicktrans

Usage

quicktrans file-namebase input-extention output-extention

Example

quicktrans sample qc c

This command process the blueprint file sample.qc to form the output file, sample.c. This will be the example used by the documentation of this program.

Description:

The quickify program was a genuinely good program. It enabled a source code to be custom-generated based on preferences found in the environment. However, it was limited, in that to get those preferences put into the environment required the user to write an often-complicated wrapper script. What was needed was a generic wrapper script that could on it's own extract those preferences based on directives found within the blueprint files themselves. This is why quicktrans was written.

The quicktrans program first runs quickify in "pref" mode on two files, and appends the output of one to the output of the other. First in the concatenation is the output of quickify when run in "pref" mode on a file that is known as inhouse-res/basics.blpr, either from the current working directory or from a directory higher up on the heirarchy (the file to be hereby referred to as the "Global Blueprint File"). Next in the concatenation is the output of quickify when run in "pref" mode on our Source Blueprint file it's self (which in the case of our example is sample.qc).

Now, quicktrans has the Preference Directive file. Though the Preference Directive file never existed on disk (and generally never does) for ease of discussion, let's refer to it as a file. It then processes these directives one by one, starting with the first directive derived from the Global Blueprint file to the last directive derived from our Source Blueprint File (in this case sample.qc).

After that, it then runs quickify again, this time in normal mode, and this time only on our Source Blueprint file. (The Global Blueprint File is left out of this round of processing.) The output this time, instead of going to core memory, is instead piped to the Output File, which in the case of our example is sample.c.

Now, this document does not tell you how to write data into the Blueprint Files themselves in order to get the desired results in the Preference Directive file. For that information, read the documentation on quickify. Instead, this document will focus it's effort on describing how the directives in the Preference Directive file are processed once they are formed. For this purpose, we'll have to further elaborate the example that was briefly described in the header of this document.

In the example this document uses, we will assume that the inhouse-res directory that contains the basics.blpr file is two directories up, so that the Global Blueprint file is here referred to as ../../inhouse-res/basics.blpr.

Preference Directive File derived from ../../inhouse-res/basics.blpr and sample.qc:

pref:compil-pref:BX3PREF:XX_COMPIL_PREF:Main Compilation Preference File:
pref:company-name:XX_COMPIL_PREF:XX_COMPANY_NAME:Who Compiled the Program:
cmd:XX_LOCAL_DIR:pwd:
tran:XX_LOCAL_DIR:XX_PACKAGE_DIR:
chop:XX_PACKAGE_DIR:
chop:XX_PACKAGE_DIR:
tran:XX_PACKAGE_DIR:XX_LOCAL_PREF:
ap-lit:XX_LOCAL_PREF:/proj.prf3:

Now, the first directive is an instance of pref. What pref does is invoke a call to the krefslc3 user command. The krefslc3 command will extract the preference variable compil-pref from the file preference file named by the environment variable BX3PREF, and the result will be stored in the environment variable XX_COMPIL_PREF. If that preference variable is not found, then this program will terminate with an error message. The error message will include the words "Mail Compilation Preference File" to explain the user what the missing variable is supposed to represent.

In the case of this directive, the source Environment Variable is BX3PREF, which happens to be a standard environment variable for BOXENV. However, a pref directive can also use an environment variable set by an earlier instance of pref, as is the case with the next directive, which extracts from the Main Compilatioin Preference File the name of your company, so that the program can have a line saying what company compiled the program.

The next directive is an instance of cmd. What cmd does is execute a user command and store the output in an environment variable. In case, the user command is executed is pwd, and the output is stored in the environment variable XX_LOCAL_DIR. This is a good time to note that pwd will not tell us where quicktrans was invoked from. Instead it will tell us what directory our Blueprint File is in, because the first thing quicktrans does is move to that directory.

After that is an instance of tran, that copies the contents of XX_LOCAL_DIR to the environment variable XX_PACKAGE_DIR. Of course, since the inhouse-res directory is two directories up, chances are that the main directory of the package's source code is also two directories above the one specified by XX_LOCAL_DIR. For that reason, following the tran directive are two instances of chop. Each of those two chop directories takes XX_PACKAGE_DIR and chops everything after and including the last forward-slash ("/") that it finds.

The last two directives set up the environment variable XX_LOCAL_PREF to name the Project Preference file (i.e., the primary preference file of this software package). The first of these two directives is another tran directive, which transfers the contents of XX_PACKAGE_DIR to XX_LOCAL_PREF. The last directive is an instance of ap-lit (short for "Append Literal"). This appends the literal string "/proj.prf3" onto the environment variable XX_LOCAL_PREF.

Now, as you may have noticed, all the environment variables set by these directives began had names beginning with "XX_". There is nothing in quicktrans that enforces this. However, that's still a good practice so as to avoid conflicting with other environment variables.

In case you need to use a directive that's not documented on this page, check out the Directive List for more information.