Purpose

ETAC Compiler Help

Document Date: 1 August 2020

ETAC Compiler Version: 2-0-6-ena

ETAC Programming Language Version: 1-1

The ETAC Compiler program (ETACCompiler.exe) converts ETAC code files from one form to another, and does detailed syntax checking on ETAC text script files. The internal name of the program is ETACCompiler-2-0-6-ena, and the distributed name is ETACCompiler.exe. This document is for version 1-1 of the ETAC Programming Language implemented in program ETACCompiler.exe version 2-0-6-ena.

An ETAC code file can be in one of the following forms:

(1) | Plain text as a regular (Windows-1252) or Unicode® (UTF-8, UTF-16, or UTF-32) ETAC (or TAC) script file. (extension: *.etac or *.tac)
(2) | Preprocessed and compressed ETAC text script file (ETAC packed script). (extension: *.ptac)
(3) | Compressed TAC binary file (containing TAC binary instructions). (extension: *.btac)

The ETAC Compiler can convert ETAC code from any one of the above forms to any other. Original ETAC source code is in the form (1) above, and does not need to be converted to be executed by the Run ETAC Scripts program (RunETAC.exe). However, converting an ETAC script from plain text to another form can yield certain advantages. A TAC binary file, (3), can load slightly quicker than a text ETAC file, (1) or (2), since no parsing and syntax checking is done. But the main advantage of a TAC binary file is that the inclusion files would have all been processed and are included in the binary file. However, a TAC binary file cannot normally be debugged unless it is first converted to a text file (conversion from (3) to (1)). Such a conversion, however, will be in the form of ETAC text instructions rather than high-level code. Compressed ETAC text script files (2) are typically used as inclusion files. The advantage here is that the nested inclusion files specified in the original inclusion file are also compressed within the same packed file resulting in only one inclusion file. Files of the form (2) can be debugged but will have had the comments stripped out.

The ETAC Compiler can also combine any number of ETAC code files (in any mixture of the three forms above) into a single output file (again, in any one of the three forms). When code files are combined, they are first internally converted to the output form and then merely concatenated. This requires that the original input files be designed for such concatenation.

The syntax checking done by the ETAC Compiler is more detailed than the one done by the Run ETAC Scripts program, and includes warning checks. Only ETAC files of the form (1) and (2), (ETAC scripts), can be syntax checked. However, files of the form (2) should have already been syntax checked. A list of errors and warnings for the file being syntax checked (input file) is displayed in a dialog box. When the user selects an error or warning, the offending token is highlighted in another window which displays the whole (slightly converted) input file containing that token. The list of errors and warnings, along with their line numbers in the original input file, can be exported to an RTF (Rich Text Format) or TAB-separated text file for later viewing. The ETAC Compiler can be directed to filter out warnings that have occurred with the same input file in the previous session. However, the ETAC Compiler only remembers the error code, input file, and line number of a warning, and so this feature is unable to distinguish more than one warning of the same warning code on the same text line in the same input file. Nevertheless, this is still a useful feature, enabling the user to see only the latest warnings of an input file. Note that this feature only filters warnings, not errors, since errors will cause the script to fail if run. Also note that the ETAC Compiler checks the same errors as is done by the Run ETAC Scripts program, but the errors are checked in more detail.

The input instructions to operate the ETAC Compiler are in the form of keyword-arguments (keywords and their arguments) that allow any number of groups of ETAC code files to be processed independently one after another. The keyword-arguments can be specified directly or in a text file. See Program Command Line Arguments for details.

The following table describes the different types of output file (and their default extensions) produced by the ETAC Compiler for various operations. The keyword in parentheses under Operation is supplied to the ETAC Compiler for the specified operation. Any of these output files can be used as input files in another compilation session.

Operation | Ext | Description | Form
Binary (BINARY) | btac | Produces a binary file containing TAC binary instructions. This is the default operation. | (3)
Instructions (INSTR) | tac | Produces a text file containing TAC text instructions in the form: ‹type:argument;› | (1)
Preprocessed (PPROC) | etac | Produces a preprocessed file for diagnostics purposes. The file may not be able to be processed as an ETAC text script because preprocessor definition references are not resolved at the preprocessor stage. All preprocessor directives are processed. Comments are removed and white-spaces are reduced to a single space. | (1)
Processed packed (PACK) | ptac | Produces a preprocessed packed script (ETAC packed script) with preprocessor definitions included at the beginning of the file. Comments are removed and white-spaces are reduced to a single space. | (2)
Unprocessed packed (EXPACK) | ptac | Produces packed script (ETAC packed script) with all ‘::include’ instructions unconditionally expanded. The input files are not preprocessed. Comments are removed and white-spaces are reduced to a single space. | (2)
Syntax check (SYNTAX) | N/A | Checks the input files for syntax errors and warnings only. The input files are preprocessed before they are checked. Shows warnings and fatal errors. Fatal errors are the errors that are checked each time the script is run. Warnings are produced only with this option. The token causing the selected error or warning is highlighted in a window. No output file is produced. | N/A

The following table describes the various operations that can be performed by the ETAC Compiler for each type of ETAC code file used as an input file. There are fundamentally two classes of ETAC code files: (a) some form of packed or plain text (Text Code), and (b) TAC binary instructions (Binary TAC). The form of input file is determined by the contents of the file, not by the file’s extension.

Input File Type |  |
 | Operation | Description
Text Code (a) |  | (Input Forms: (1), (2); File Extensions: tac, etac, ptac)
 | BINARY | The input file is compiled into TAC binary instructions then written to the specified output file with a default extension of ‘btac’.
 | INSTR | The input file is internally converted into TAC text instructions then written to the specified output file with a default extension of ‘tac’.
 | PPROC | The input file is preprocessed only, then written to the specified file with a default extension of ‘etac’. The output file is not packed, it is a readable text file.
 | PACK | The input file is preprocessed and packed then written to the specified output file with a default extension of ‘ptac’.
 | EXPACK | The input file is not preprocessed except for ‘::include’ commands (which are unconditionally expanded). It is packed into the specified output file with a default extension of ‘ptac’.
 | SYNTAX | The input file is checked for errors and warnings. If a syntax error or warning occurs, the error or warning is shown in a dialog box. Another window containing the appropriate ETAC script will show the offending token highlighted. No output file is produced.
Binary TAC (b) |  | (Input Form: (3); File Extension: btac)
 | BINARY | The input file is copied to the specified output file with a default extension of ‘btac’.
 | INSTR | The input file is internally converted into TAC text instructions then written to the specified output file with a default extension of ‘tac’.
 | PPROC | The input file is internally converted into TAC text instructions then written to the specified output file with a default extension of ‘tac’.
 | PACK | The input file is internally converted into TAC text instructions and packed then written to the specified output file with a default extension of ‘ptac’.
 | EXPACK | The input file is internally converted into TAC text instructions and packed then written to the specified output file with default extension ‘ptac’.
 | SYNTAX | No action occurs and no output file is produced.

For full details about the ETAC Compiler, read the document The ETAC Compiler (in the file ETACCompiler.pdf).

Copyright © Victor Vella (2020). All rights reserved.

RunETAC, AppETAC, ETAC, ETAC logo (the ETAC logo), and ETAC Compiler logo (the ETAC Compiler logo) are unregistered trade marks (™) of Victor Vella for computer software incorporating an implementation of a computer programming language. There may be other owners of the “ETAC” trademark used for other purposes.

MS-DOS and Windows are registered (®) or unregistered (™) trademarks of Microsoft Corporation.

Unicode is a registered trademark (®) of Unicode, Inc. in the United States and other countries.


Definitions

All Definitions

ETAC code

This is ETAC script or TAC binary instructions. A file containing ETAC code typically has an extension of etac, tac, ptac, or btac.

ETAC packed script

An ETAC text script that has been preprocessed or expanded, and compressed. A file containing ETAC packed script is a binary file, typically having an extension of ptac.

ETAC script

This is ETAC text script or ETAC packed script. A file containing ETAC script typically has an extension of etac, tac, or ptac.

ETAC text script

ETAC program code that is in human readable and writable text form. This includes TAC text instructions. A file containing ETAC text script typically has an extension of etac or tac.

input file

An input file is a file containing ETAC code which is to be compiled, converted (typically to a new file), or checked for syntax errors. The contents of an input file must be: ETAC text script (extension: etac or tac), ETAC packed script (extension: ptac), or TAC binary instructions (extension: btac). An arbitrary text file is interpreted as ETAC text script. An arbitrary binary input file is not compiled unless it contains ETAC packed script or TAC binary instructions. Note that an input file need not have the extension as specified above. An input file is not altered unless an output file path is the same as the input file path.

output file

An output file is a TAC or ETAC file compiled or converted from an input file. The contents of an output file can be one of the following: a TAC or ETAC text script (extension: tac or etac), packed script (extension: ptac), or TAC binary instructions (extension: btac).

TAC binary instruction

A TAC binary instruction is a binary form of a TAC text instruction. TAC binary instructions exist in binary files. Such a file can be compiled into TAC text instructions by the ETAC Compiler. Any ETAC code can be compiled into TAC binary instructions. A file containing TAC binary instructions typically has an extension of btac.

TAC text instruction

A TAC text instruction is a human readable text instruction of the form ‹type:argument› where type is any one of: INT, DEC, STR, LBC, LBO, CMD, OPR, MRK, MEM, NUL, or EXE, and argument is an appropriate argument for type. TAC text instructions may exist in ETAC text script files or in files containing only TAC text instructions. Such a file can be compiled into TAC binary instructions by the ETAC Compiler. The ETAC Compiler can also compile ETAC code to TAC text instructions. A file containing TAC text instructions alone typically has an extension of tac.


Notational Conventions

The following notational conventions are used in the keyword arguments syntax.

Convention | Meaning
TEXT | A fixed text style indicates text characters to be entered as shown.
[text] | Red square brackets indicate optional text between the brackets. This means that the text between the brackets can optionally be omitted. The brackets themselves are not part of the syntax and are not to be entered.
{text} | Red braces indicate the default text used if no text is entered, otherwise the entered text is used. The braces themselves are not part of the syntax and are not to be entered.
(text) | Red parentheses serve to group text together as a single unit. The parenthesis themselves are not part of the syntax and are not to be entered.
text | text | Red vertical bars separate one of a number of options to be entered. If more than one of the optional text is entered, the last option takes precedence unless it is also the default text (indicated by {text}). The bars themselves are not part of the syntax and are not to be entered.
··· | Red middle ellipses indicate that the preceding syntax is repeated from zero to any number of times as required but is optionally entered. The ellipsis themselves are not part of the syntax and are not to be entered.
argument | Italic text indicates an argument to be entered. The description of the actual text to enter is displayed by clicking on the relevant keyword (shown in GREEN). The italic text itself is not part of the syntax and is not to be entered.


Command Syntax

Program Command Line Arguments

The ETAC Compiler can be execute either from the MS-DOS® or Windows® environment. In either case, a command line needs to be specified. From within Windows®, the command line is typically entered in a shortcut file, as follows, to execute the ETAC Compiler (ETACCompiler.exe). In the Target entry of the shortcut properties, enter the following: ‹"path\ETACCompiler.exe" kw-args›, where path is the directory path of the directory containing ETACCompiler.exe, and kw-args represents the keyword-arguments for the ETAC Compiler (described below). If the ETAC Compiler is execute with an empty command line, a dialog box is displayed to enter the keywords and arguments. To display the Start Box before entering the keywords and arguments in the dialog box, specify START on the command line. To display the About Box, specify ABOUT on the command line.

The program command line arguments for ETACCompiler.exe are defined below. String arguments can be quoted by being enclosed in single or double quote characters, which are not part of the string. The beginning and ending characters of a quoted string must be the same quote character, and that character must not exist within the string. Also, the ending quote character must not be immediately preceded by a backslash (\). A directory path ending with a backslash within a quoted string needs to have a space after the backslash, for example "C:\Name1\Name2\ " is valid, but "C:\Name1\Name2\" is not. However, an ending backslash is not normally needed for a directory path. The text within single or double quotes is taken literally by the command line interpreter. To insert a quote or comma or any other character in a non-quoted string, precede it with a backslash, which is ignored. The keywords can be presented in any order. ETAC comments, [* ... *], can be used to comment out parts of the command line.

Click for Notational Conventions

ETACCompiler.exe

[ARGS_PATH=arg-file-path, ···]
[{ED_ARGS} | NO_ED_ARGS]
[START | ABOUT ]

or

ETACCompiler.exe

[{BINARY} | PACK | EXPACK | INSTR | PPROC | (SYNTAX [F: warn-filt-file])]
[CDIR=dir-path]
[INCL_DIRS=incl-dir-file]
[PPDEFS=pp-defs]
SRC_FILES=src-file-path, ···
[OUT_FILE=out-file-path]
[LIST_INCFILES]
[QUIET_RUN]
[{EXIT_MSG} | NO_EXIT_MSG]
[{AUTO_LOG} | LOG_FILE=disk-file-path]

Examples

  1. "C:\Program Files\ETACCompiler\Programs\ETACCompiler.exe" SYNTAX CDIR="C:\Development\MyProject" SRC_FILES="MyFile1.etac", "MyFile2.tac", "MyFile3.etac"
    This line performs a syntax check on the files MyFile1.etac, MyFile2.tac, and MyFile3.etac, in the MyProject directory. No output files are produced.

  2. ETACCompiler.exe CDIR='..\ETACScripts' [*PPDEFS="RELEASE"*] SRC_FILES=[*"Script1.etac", *] "Script2.etac", 'Script3.etac' OUT_FILE=Output\\New*
    This line compiles the input files Script2.etac and Script3.etac, existing in the ETACScripts directory (which is in the directory at the same level as the current one), and places the output files into NewScript2.btac and NewScript3.btac (respectively) in the Output directory (relative to the new current directory specified at: ‹CDIR='..\ETACScripts'›) as TAC binary instructions. The commented out parts of the command line are ignored. Notice the double backslash at ‹OUT_FILE=Output\\New*›. This represents a single backslash, but because the argument of OUT_FILE= is not in quotes, a backslash is interpreted as an escape character, and a double backslash as a single backslash. The second backslash cannot be replaced by a space because the command line interpreter uses a different system of escape characters than does the ETAC interpreter (which interprets both ‹\\› and ‹\ › as a single backslash character).

  3. ETACCompiler.exe SRC_FILES="Script1.etac", Script2.tac, 'Script3.btac' PPDEFS="RELEASE" OUT_FILE="..\Release\ " [* Notice the space after the last backslash. *]
    This line compiles the input files Script1.etac, Script2.tac, and Script3.btac, existing in the current directory, and places the output files into Script1.btac, Script2.btac, and Script3.btac (respectively) in the Release directory (which is in the directory at the same level as the current one) as TAC binary instructions. The backslash at the end of ‹"..\Release\ "› represents a single backslash character (just as two backslash characters normally would). But because a backslash character just before a quote character escapes the quote character (and therefore the string will not be terminated by a quote character), a space character needs to be used after the second backslash character rather than another backslash character. In this example, ‹"..\Release\ "› is interpreted by the ETAC Compiler rather than by the command line interpreter. That interpretation results in the argument being equivalent to ‹..\Release\›. The final backslash instructs the ETAC Compiler to place the output files, with their default file names, in the Release directory. Note that a forward slash could have been used at the end instead of a backslash followed by a space.

  4. ETACCompiler.exe START ARGS_PATH="ArgsFile.ecarg"
    This line displays the Start Box, and when the user clicks Start in the Start Box, the command line arguments in the file ArgsFile.ecarg will be displayed to the user for editing (if necessary) before being processed.

  5. ETACCompiler.exe SRC_FILES="Compiled.btac" INSTR
    This line compiles the input file (containing TAC binary instructions), existing in the current directory, and places the output file in the same directory. The output file will contain TAC text instructions. Effectively, the TAC binary instructions of the input file have been “decompiled”.

  6. ETACCompiler.exe BINARY SRC_FILES="Script1.etac", Script2.tac, 'Script3.btac' OUT_FILE="CombinedFile"
    This line internally compiles the input files Script1.etac, Script2.tac, and Script3.btac, existing in the current directory, then concatenates those files into the single output file CombinedFile.btac in the current directory as TAC binary instructions. Note that the file Script3.btac is not actually compiled, but is merely copied, because it has previously been compiled and already contains TAC binary instructions.

ARGS_PATH=arg-file-path, ···

arg-file-path is the full path of the argument file. An argument file can contain command line keyword-arguments in one of the two forms (not both forms together). This implies that a tree structure of input files can be compiled — the final nodes of the tree will be keyword-arguments of the second form. The default extension of an argument file is ‘ecarg’.

ED_ARGS

Specifies to present the user with a dialog box to allow him to edit the keywords and arguments of the contents of the arg-file-paths (if specified) before they are processed. This option is the default if the ETAC Compiler is execute with an empty command line.

NO_ED_ARGS

Specifies to not present the user with a window to allow him to edit the keywords and arguments of the contents of the arg-file-paths before they are processed. The keywords and arguments in the specified arg-file-paths will be processed without allowing the user to modify them.

START

Displays the Start Box before beginning the program.

ABOUT

Displays the About Box before beginning the program.

BINARY

The input file (src-file-path) is compiled into TAC binary instructions and put into the output file (out-file-path) with default extension ‘btac’. If the input file contains TAC binary instructions then it is merely copied to the output file.

PACK

A copy of the input file (src-file-path) is preprocessed and packed with the preprocessor definitions of the input file inserted at the beginning of the output file with default extension ‘ptac’. The preprocessor inclusion directives, ::include ..., are expanded as part of the preprocessing operation. Comments are removed and white-spaces are reduced to a single space. If the input file contains TAC binary instructions then it is first internally converted to TAC text instructions before being packed. This option is useful for removing irrelevant preprocessor conditional code based on existing preprocessor definitions. Note that preprocessing a TAC or ETAC file does not resolve the preprocessor definition names; that is the reason that the preprocessor definitions are retained in the output file. This option is typically used for combining a number of TAC or ETAC scripts containing only definitions into a single file.

EXPACK

The preprocessor inclusion directives, ::include ..., in the input file (src-file-path) are merely expanded and packed into the output file with default extension ‘ptac’. The input file is not preprocessed. Comments are removed and white-spaces are reduced to a single space. If the input file contains TAC binary instructions then it is first internally converted to TAC text instructions before being packed. This option is useful for retaining unprocessed preprocessor conditional directives in the output file. The option is typically used for combining a number of TAC or ETAC scripts and their inclusion files into a single file without preprocessing.

INSTR

A copy of the input file (src-file-path) is converted into TAC text instructions and written to the output file with default extension ‘tac’.

PPROC

The input file (src-file-path) is preprocessed only into the output file with default extension ‘etac’. The output is not packed; it is a readable text file. If the input file contains TAC binary instructions then it is converted into TAC text instructions and written to the output file with default extension ‘tac’. This option is useful mainly for debugging purposes. The output file may not be able to be executed because preprocessing a TAC or ETAC file does not resolve the preprocessor definition names.

SYNTAX [F: warn-filt-file]

Indicates to check for syntax errors or warnings only — no compilation or conversion occurs. Syntax errors or warnings occurring in the input file (src-file-path) being checked are listed in a dialog box. When the user selects an error or warning, the offending token is highlighted in a window containing the current input file. If the input file contains TAC binary instructions then no action occurs. Warnings are only suggestions and do not necessarily indicate a problem with the input file. ‘OUT_FILE=out-file-path’ is ignored if this option is present.

If ‘F: warn-filt-file’ is present, only new warnings are shown for the input file. warn-filt-file is the path of a text file, specified by the user but maintained by the ETAC Compiler, to record all the warnings of the input file being checked. Next time the ETAC Compiler carries out a syntax check on the same input file, those recorded warnings will be filtered out and will not show in the error and warning list unless the ‘New Warnings’ check-box is unchecked. If warn-filt-file is a relative file path then it is relative to the directory specified at ‘CDIR=dir-path’. The same warn-filt-file can be used for checking different input files.

If ‘F: warn-filt-file’ is absent, then all the warnings of the file being checked are listed.

CDIR=dir-path

During processing, the current directory will be changed to dir-path, and used for all files (other than the log file) that have no drive specification. If this keyword is absent then the program current directory is used instead.

INCL_DIRS=incl-dir-file

incl-dir-file is the file path of a text file containing a list of inclusion directory paths used to find inclusion files (at: ::include ...) in the input file. If incl-dir-file does not contain a drive specification then the path is relative to the specified current directory (CDIR=dir-path). Note that incl-dir-file specifies the file containing the inclusion directory paths, not the directory paths themselves.

The contents of the file specified at incl-dir-file contains an unquoted inclusion directory path on each line. If the directory path does not contain a drive specification then the path is relative to the specified current directory (CDIR=dir-path). No other text can exist on that line. Empty lines (lines that contain only spaces or no text at all) and lines beginning by an asterisk (*), possibly preceded with only spaces, are ignored. A line beginning with an asterisk indicates a comment line.

If this option is absent, incl-dir-file is obtained from the ETACCompiler.ini file at the IncDirs= key under the Settings section. The search for ETACCompiler.ini will begin with the directory in which ETACCompiler.exe itself exists, followed by a search in the system Windows directory. The ETACCompiler.ini file typically exists in the system Windows directory.

If incl-dir-file is not found then the inclusion file paths in any input file (SRC_FILES=src-file-path, ···) will be relative to the specified current directory (CDIR=dir-path) for inclusion files that have a relative path.

PPDEFS=pp-defs

pp-defs is a space-separated list of global preprocessor definition names. The whole list can be delimited by single or double quotes. Only definition names can be specified in the list (definition bodies must not be specified). The names are processed as though they were defined by the preprocessor ::define directive before each input file (src-file-path) is processed.

SRC_FILES=src-file-path, ···

src-file-path is a comma-separated list of input file names to be processed. Each file specified at src-file-path may be enclosed in single or double quotes. If a src-file-path has no drive specification, then it is relative the current directory specified at ‘CDIR=dir-path’.

OUT_FILE=out-file-path

out-file-path indicates the output file name or names. out-file-path can contain a directory path. If the directory path has no drive specified, then the path is relative to current directory specified at ‘CDIR=dir-path’. out-file-path can be a directory path only (indicated by a file separator at the end of the path). This indicates that the output file name will be the default file name, which is the input file name but with the appropriate extension.

If a file name is specified at out-file-path, then ‘*’ in the file name is replaced with the current input file name. If no ‘*’ is specified then all input files are internally concatenated to produced one file which is created as the specified output file. If no extension is specified in the output file then the appropriate extension is added. To prevent an extension from being added, use ‘.?’ as the extension (for example: ‘MyFile.?’ will produce the file ‘MyFile’).

If this keyword is absent, the default output files will be created in the current directory specified at ‘CDIR=dir-path’, or in the program current directory if ‘CDIR=dir-path’ is absent.

LIST_INCFILES

This lists the inclusion files encountered while processing the input files. The list is shown on the console window, unless QUIET_RUN is specified. The list is recorded in the log file. No inclusion file list is displayed or recorded in the log file if this keyword is absent.

QUIET_RUN

If present, the console window is not displayed. Progress and error messages are still logged to the log file. If absent, a console window is displayed showing the progress of the compilation.

EXIT_MSG

Displays a message when ETACCompiler.exe ends.

NO_EXIT_MSG

Does not display a message when ETACCompiler.exe ends.

AUTO_LOG

Specifies to automatically log certain error and activity records to the file ETACCompiler.log in the program current directory (not the directory specified at ‘CDIR=dir-path’) or the output directory where the output files are placed. If ‘OUT_FILE=out-file-path’ is not specified then the records are logged in the current directory. This option is the default.

LOG_FILE=disk-file-path

disk-file-path is the disk file path to log certain error and activity records relating to the compilation. If disk-file-path contains no drive specification, then the path is relative the program current directory (not the directory specified at ‘CDIR=dir-path’).