Purpose

Run ETAC Scripts Help

Document Date: 1 August 2020

Run ETAC Scripts Version: 3-0-6-ena

ETAC Programming Language Version: 1-1

The Run ETAC Scripts program (RunETAC.exe) executes one or more ETAC code files. The internal name of the program is RunETAC-3-0-6-ena, and the distributed name is RunETAC.exe. This document is for version 1-1 of the ETAC Programming Language implemented in program RunETAC.exe version 3-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)

RunETAC.exe executes the supplied loader script (RunETAC.etac or RunETAC.btac) before it executes the specified ETAC code files. The loader script may be modified by the ETAC programmer to set up the environment for the current session of RunETAC.exe. For example, if the RunETAC.exe session is intended to operate in a particular way, the string argument specified on the command line is passed on to the loader script, which sets up the appropriate ETAC environment based on the value of that string argument. The specified ETAC code files are then executed in order, one at a time, operating under that environment. The default argument to the loader script is an empty string. That argument, whether it is empty or not, is ignored by the originally supplied loader script, which loads the references to the ETAC definitions and standard ETAC library before executing the specified ETAC code files. The location of the loader script is specified at ‹LoadDir=...› in RunETAC.ini as a directory path. The default location is the System directory under the installed RunETAC directory. If RunETAC.exe cannot find the loader script then the user is prompted to enter its file path.

If Run ETAC Scripts has been set up properly, the user can execute a single ETAC code file by double clicking the file in Windows®. The user can also edit and debug ETAC text script files from Windows via the popup menu. Alternatively, the user can create a Windows shortcut file to execute one or more ETAC code files via the command line. The command line to operate Run ETAC Scripts is in the form of keyword-arguments (keywords and their arguments). See Program Command Line Arguments for details.

Run ETAC Scripts does minimal syntax checking on ETAC script files before executing them. That minimal syntax checking was not designed to aid the programmer in debugging their ETAC scripts. It was designed to make sure that the ETAC script files can be executed. The ETAC Compiler is used to do detailed syntax checks on ETAC scripts without executing them (read the document The ETAC Compiler in the file ETACCompiler.pdf for more details).

For full details about Run ETAC Scripts, read the following documents:

An Overview of ETAC (ETACOverview.pdf)

The Official ETAC Programming Language (ETACProgLang(Official).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

complex string

A string that is delimited either by double quotes (‹"› U+0022) or single quotes (‹'› U+0027). If the string is delimited by double quotes, then escape characters within the string are interpreted as follows:

\xhh | ISO-8859-1 (Latin-1) character code (U+00hh),
\#u···u# | Unicode® scalar value (U+u···u),
\\ | backslash character (\),
\<SP> | backslash character (\),
\" | double quote character ("),
\' | single quote character ('),
\n | new line (<LF>),
\t | horizontal tabulate,
\v | vertical tabulate,
\b | back space,
\r | carriage return (<CR>),
\f | form feed,
\a | alert,
\<CR> | ignored,
\<LF> | ignored,
\<CR><LF> | ignored,
\<LF><CR> | ignored,

where h and u are a hexadecimal characters, <SP> is a space character (U+0020), <LF> is a line feed character (U+000A), and <CR> is a carriage return character (U+000D).

If the string is delimited by single quotes, then the only escape character allowed within the string is a backslash with the following restrictions. (1) A backslash cannot appear before the final delimiting single quote. For example, ‹'string\'› is invalid. To achieve the correct effect, ‹string\›, use ‹'string\·'› (where · represents a space). A backslash followed by a space (not a white-space) represents only a backslash (the space is ignored). However, the conversion is valid only if ‹\› is followed by one or more spaces to the end of the string. In any other position, ‹\·› is taken as is. (2) A backslash followed by a single quote character represents only the single quote character. For example, ‹'\·the\'string\'\····'› represents the string ‹\·the'string'\···› (where · represents a space). Notice that the last string has one less space at the end than the original string.

An alternative to the case for single-quoted strings is to enclose the desired string in double-angle quotes ‘«’ (U+00AB) and ‘»’ (U+00BB) instead of single quotes. In this case, the two restrictions mentioned above do not apply. For the example above, ‹«string\»› is valid without the need for an end space; likewise for ‹«\·the'string'\»›. The double-angle quotes themselves are ignored, but the text in-between is understood literally as presented, except for leading and trailing spaces which are ignored.

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

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.

loader script

This is an ETAC Code file typically used to set up the ETAC environment before the specified ETAC Code files are executed. The file name for the default loader script is RunETAC.etac or RunETAC.btac. The loader script always takes one string argument (the default argument is an empty string). The default location of the loader script is in the System directory under the installed RunETAC directory.

standard TAC library

This is a library of custom commands that are implemented internally to the Run ETAC Scripts program. To use any of those custom commands, the references to the library commands need to be loaded first. This is normally done by the default loader script.

string block

This is any part of a text string delimited by matching parentheses ‹()›, square brackets ‹[]›, braces ‹{}›, double quotes ‹"› (U+0022), or single quotes ‹'› (U+0027). A string block includes the delimiter characters. For example, the highlighted substrings within ‹is there (anybody out) there, tell 'me if' there is› are string blocks.

TAC binary instruction

A TAC binary instruction is a binary form of a TAC text instruction. TAC binary instructions exist in binary files. Any ETAC code can be compiled into TAC binary instructions by the ETAC Compiler. 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. The ETAC Compiler can 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

Run ETAC Scripts can be executed 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 Run ETAC Scripts (RunETAC.exe). In the Target entry of the shortcut properties, enter the following: ‹"path\RunETAC.exe" kw-args›, where path is the directory path of the directory containing RunETAC.exe, and kw-args represents the keyword-arguments for Run ETAC Scripts (described below). To display the Start Box, specify START on the command line. To display the About Box, specify ABOUT on the command line.

The command line for RunETAC.exe contains the ETAC code files that the user wants to execute. When executed, RunETAC.exe first searches for the loader script (RunETAC.etac or RunETAC.btac) to set up the environment to execute the desired ETAC code files. If the loader script is not found, RunETAC.exe will present the Start Box, and when the user clicks Start, a file dialog will be presented allowing the user to specify the loader script. However, the Start Box is not presented (unless instructed to do so by specifying START on the command line) if RunETAC.exe finds the loader script in certain places to be described next. RunETAC.exe first searches (1) the directory from which RunETAC.exe itself was executed. If the loader script is found in that directory it will be executed, and the Start Box will not appear. If the loader script is not found in that directory, RunETAC.exe will search (2) the current directory for the loader script. If the loader script is found in the current directory it will be executed, and the Start Box will not appear. If the loader script is not found in the current directory, RunETAC.exe will search for the RunETAC.ini file to determine (3) the directory (specified at ‹LoadDir=...› in RunETAC.ini) containing the loader script. The search for RunETAC.ini will begin with the directory in which RunETAC.exe itself exists, followed by a search in the system Windows directory. If the loader script is not found in the directory specified in the RunETAC.ini file, RunETAC.exe will (4) present the Start Box (as mentioned previously) allowing the user to specify the loader script. RunETAC.exe searches for RunETAC.etac first then searches for RunETAC.btac in each of the previously mentioned directories in turn. The command line can indicate to prevent the searching for the loader script by specifying NO_LOADER. Note that if Run ETAC Scripts has been set up properly, the user can execute a single ETAC code file by double clicking the file in Windows — there is no need to set up a shortcut file with a command line in that case. Note also that there is no way for the user to specify the file name of the loader script on the command line. If the user wants a different loader script to run than the default one, he needs to remove all instances of the loader script file from the search path mentioned previously so that RunETAC.exe will present the dialog box for the user to enter his own loader script each time RunETAC.exe is executed.

The program command line arguments for RunETAC.exe are defined below. String arguments for file paths 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. To insert a quote or comma (or any other character) in a non-quoted string, precede it with a backslash, which is ignored.

When specifying the path in SCRIPTS=, if the specified file name has no extension and the file does not exist, and if DEBUG was specified on the command line, RunETAC.exe searches for the specified file with .etac appended to the file name first then with .btac appended to name. If DEBUG was not specified, and the specified file name has no extension and the file does not exist, then .etac will be assumed first, followed by .btac. Only the first-found file with the appended extension is executed. Script arguments (for the keyword SCRIPTS=) can be complex strings.

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

RunETAC.exe

[{""} | loader-arg]
[NO_LOADER]
[DEBUG]
[SOLO]
[ABOUT]
[START]
[{EXIT_MSG} | NO_EXIT_MSG]
[INC_DIRS=incl-dir-file]
[PPDEFS=pp-defs]
[SCRIPTS=path [{""} | arg], ···]
[{AUTO_LOG} | LOG_FILE=disk-file-path]

Examples

  1. "C:\RunETAC\Programs\RunETAC.exe" SCRIPTS=MyScript.etac
    This line executes the ETAC text script file MyScript.etac with an empty string (the default) as argument.

  2. RunETAC.exe START SOLO DEBUG SCRIPTS="MyScript1.etac" "Hello world,", 'MyScript2.etac' what\'s up?, MyScript3.etac "The opposite of \"down\""
    This line presents the Start Box, and if the user clicks Start on the Start Box, RunETAC.exe will run the ETAC text script files MyScript1.etac, MyScript2.etac, and MyScript3.etac, each in turn, in debug mode (the user can trace the execution of the scripts) with respective arguments ‹Hello world,›, ‹what's up?›, and ‹The opposite of "down"›. No other RunETAC.exe session will be allowed to run due to the SOLO keyword.

  3. RunETAC.exe NO_LOADER SCRIPTS="My Project\MyScript.btac" LOG_FILE="MyLog.txt"
    In this line, the user decided not to have the loader script executed. The ETAC binary instruction file, MyScript.btac, is executed with the default empty string argument. A log of the important events is recorded in the file MyLog.txt relative to the current directory. Note that MyScript.btac needs to set up the appropriate environment, which is normally done by the loader script, before executing the main code.

  4. RunETAC.exe "Hello world,\r\nwhat's up?\r\nThe opposite of \"down\""
    In this line, the user has written his own loader script file, RunETAC.etac, in the current directory. That file will run with the argument ‹Hello world,<CR><LF>what's up?<CR><LF>The opposite of "down"›. The argument is a double quoted complex string, so the escape backslash character takes effect. The argument would result in three lines if written to a text file.

  5. RunETAC.exe INC_DIRS='Incl File.txt' SCRIPTS="My Script 1.etac" SCRIPTS=MyScript2.btac, MyScript3.etac (MODE=open LOG_FILE="MyLog.log")
    This line runs the ETAC code files ‹My Script 1.etac›, MyScript2.btac, and MyScript3.etac, each in turn, with respective arguments ‹›, ‹›, and ‹(MODE=open LOG_FILE="MyLog.log")›. Notice that the arguments for the first two ETAC code files are the default empty strings. The argument for MyScript3.etac is in the form of keyword-arguments. MyScript3.etac will need to parse its argument (after removing the parentheses) as a keyword-argument sequence. The standard TAC library command, kw_args, is used for the parsing. ‹Incl File.txt› exists in the current directory, and contains a list of inclusion directories that are used with ‹My Script 1.etac› and MyScript3.etac. Presenting ‹SCRIPTS=...› more than once is acceptable by the keyword-argument processor, and is equivalent to ‹SCRIPTS="My Script 1.etac", MyScript2.btac, MyScript3.etac (MODE=open LOG_FILE="MyLog.log"› in this example.

  6. RunETAC.exe SCRIPTS="MyScript"
    Because ‹MyScript› has no file extension, RunETAC.exe will execute ‹MyScript.btac› if that file exists. If it does not exist then RunETAC.exe will try to execute ‹MyScript.etac›. However, if DEBUG had been specified on the command line, then RunETAC.exe would have searched for and executed ‹MyScript.etac› first before executing ‹MyScript.btac› if ‹MyScript.etac› had not existed.

  7. RunETAC.exe "MyScript.etac"
    Here, the user got very frustrated after executing the line above because the ETAC text script, MyScript.etac, did not run, but a message was displayed saying that the Run ETAC Scripts program has finished. Later, after actually reading the documentation, the user discovered that ‹SCRIPTS=› needs to be inserted on the command line before "MyScript.etac". The user was very happy after discovering that reading documentation is actually a useful activity.

loader-arg

Specifies the string argument for the ETAC loader script. loader-arg may be a complex string; if it is not a complex string then all characters (excluding leading white-spaces) to the next keyword (if there is one) or end of line (if there is no next keyword) are taken as loader-arg. Trailing white-spaces in loader-arg are ignored. If loader-arg is present, it must exist before all other keywords. The default for loader-arg is an empty string. If NO_LOADER is specified, loader-arg is ignored. Note that the originally supplied loader script ignores loader-arg.

NO_LOADER

Specifies not to search for the loader script. The default is to search for or request the loader script if not found. Note that this option is not normally specified because the loader script needs to set up an environment to run ETAC code files.

DEBUG

Runs the specified ETAC text script files (specified at: SCRIPTS=...) in interactive debugging mode, tracing the script as it runs.

SOLO

Specifies that only one instance of RunETAC.exe is allowed to run at a time.

ABOUT

Shows the About Box then exits.

START

Displays start dialog box.

EXIT_MSG

Displays a message when RunEtac.exe ends.

NO_EXIT_MSG

Does not display a message when RunEtac.exe ends.

INC_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 (::include ...) files. If incl-dir-file does not contain a drive specification then the path is relative to the current directory. Note that incl-dir-file specifies the file containing the inclusion directory paths; it is not the inclusion directory path itself.

The file specified at incl-dir-file contains an unquoted inclusion directory path on each line. If a directory path does not contain a drive specification then the path is relative to the current directory. No other text can exist on that line. Blank lines (lines that contain only spaces or no text at all) and lines beginning with an asterisk (*), possibly preceded only by 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 RunETAC.ini file at the ‘IncDirs=’ key under the Settings section. The RunETAC.ini file typically exists in the system Windows directory. If incl-dir-file is not found then the inclusion file paths in every script executed by RunETAC.exe will be relative to the current directory for inclusion files that have a relative path.

PPDEFS=pp-defs

pp-defs is a string of pre-processor definition names separated by spaces.

SCRIPTS=path [arg], ...

Specifies ETAC code files to execute after the loader script has finished running. path is the full or relative path of the file to execute. A relative path is relative to the current directory. The ETAC code files are executed in the order presented. path may be enclosed in single or double quotes; if it is not in quotes then it is end-delimited by the first white-space. The characters in path are taken as given.

arg may be a complex string; if it is not a complex string then all characters (excluding leading white-spaces) after path to the next comma outside a string block (but before the next keyword if there is one), next keyword (if there is no next comma), or end of line (if there is no next keyword) are taken as arg. Trailing white-spaces in arg are ignored. The default arg is an empty string.

AUTO_LOG

Specifies to automatically log certain activity records to the file RunETAC.log on the Windows® Desktop. This option is the default.

LOG_FILE=disk-file-path

Specifies the disk file path to log certain activity records relating to the program.