ESCR Program and Callable System

Last updated 28 February 2021



The ESCR system is a script processing system intended to build applications on that need to execute scripts as part of their function. The script system executes interpreted code organized as lines of text.

The scripting system can operate in one of two high-level modes:

Script Mode

The source code is purely code executed by the script system. The code is therefore a program, with the script system being the interpreter that executes the program.

Pre-processor Mode

The source code is the input to a pre-processor. The purpose of the script logic is to transform the pre-processed code into post-processed code. Special syntax is required to identify script commands and other constructs. When no such special syntax is present, the data is simply copied from the input file to the output file.

The special syntaxes for identifying script elements are configurable by the application using the script system. For example, a particular pre-processor program may use the rule that script commands must start with a slash to distinguish them from text that is simply data to be copied from the input file to the output file.

At its core, the ESCR system is a linkable library. This library performs the mechanics of executing script elements, and in pre-processor mode of identifying script elements and copying other data to the output. The application provides the lines of source code to process, by referencing files, file snippets, previously stored source lines, or source lines generated by the application.


Applications can customize certain aspects of the script system that affect the scripting "language" as seen by users. Applications may be documented listing only these customizations, then referring to this ESCR script system documentation for the remaining language features.

Each application should specify how it customizes the script system. The possible customzations are:

  1. Whether the script system is run in script mode or pre-processor mode.
  2. Syntax for identifying script comments. No script interpretation is performed within script comments. In pre-processor mode, script comments are not copied to the output file.
  3. In preprocessor mode, syntax for identifying comments in the data file. No script interpretation is performed within data file comments, and they are copied to the output file.
  4. Syntax for identifying script commands. This is generally not used in script mode since all source code is a sequence of script commands.
  5. Additional commands. The syntax for identifying commands is the same for all commands, regardless of whether they are native to the script system or added by the application.
  6. The syntax for identifying functions in-line with other code (or also in-line with raw data in pre-processor mode).
  7. Additional functions. The syntax for identifying functions is the same for all functions, regardless of whether they are native to the script system or added by the application.
  8. The start and end of literal string identifiers. There can be multiple pairs of literal string start/end characters. String start/end identifiers are limited to single characters.
  9. Required file name suffixes for include files referenced by the native INCLUDE command.

The ESCR Program

The ESCR program uses the script system in script mode. It is a stand-alone interpreter exporting the native features of the ESCR script system. Its purpose is to be a script interpreter, and to serve as a example of a minimum application using the ESCR script system.

Most of this ESCR documentation is written as a manual for the ESCR program. However, all the script execution symantics, such as the operation of commands, inline functions, and the like, are implemented in the callable ESCR system and therefore apply to other applications using this system.

The script system customizations used by the ESCR program, according to the list above, are:

  1. Script mode, not pre-processor mode.
  2. Script comments start with "//". "//" not within a quoted string and all characters following the "//" on a line are a comment. Comments end at the end of line.
  3. There are no data file comments. There is no data since the system is not in pre-processor mode.
  4. There is no special syntax for identifying script commands. The first keyword on each line is a script command name.
  5. No commands are added to those built into the script system.
  6. Inline functions start with "[" and end with "]".
  7. No functions are added to those built into the script system.
  8. String literals can be enclosed in quotes ("...") or apostrophies ('...').
  9. The names of files referenced by the INCLUDE command must end in ".escr" or ".es".

Documentation Conventions

Source code

Verbatim source code is shown in

fixed-space font

just like you would see it in a source code editor. 


ESCR keywords are shown in

bold face

in descriptive text. When they appear within larger source code, they are shown in

bold and fixed space

Keywords are case-insensitive. They may be shown upper case, lower case, or mixed case in this document.


Brief descriptions of what to write instead of the actual text to write are shown in

italic type

Such descriptions must be replaced by the item they describe in the actual source code. 

Examples syntax

Unless explicitly stated otherwise, source code examples in this documentation use the defaut ESCR syntax rules. See the Customizations section for what parts of the syntax can be customized by applications.

Version History

18 Oct 2016

Main INDEX.HTM created, only sparsely filled in. Includes Index, Introduction, and Version History sections. Index is very small, Introduction is mostly written, and Version History not written at all. Much left to add.

22 Oct 2016

Added Version History so far (not much). Created DTYPE.HTM, CMDS.HTM, and FUNC.HTM files with appropriate linking between them. Copied the associated sections from the PREPIC documentation file into these files. Fixed up DTYPE.HTM, and got partway thru CMDS.HTM.

3 Mar 2017

Some minor rewording, typo fixes, etc. Added default value to the description of each data type. Added Documentation Conventions section. Updated existing documentation to the stated conventions.

13 Mar 2017

Finished up command descriptions, added function descriptions.

14 Mar 2017

Some fixes and the like. CHAR function now takes multiple arguments. PI function now takes second optional argument.

16 Mar 2017

The LOOP command is now more flexible. What were previously options that had to be specified in a particular sequence are now arbitrary options that can be specified in any sequence. Merged all counted loop types into one. LOOP N is no longer a special case, for example.

Change FOR keyword to WITH, to more accurately reflect what it does, despite convention of existing computing history.

The loop value is now available in a constant instead of a variable.

2 Apr 2017

Added qualified symbols syntax.

Added VER, NAME, and QUAL options to SYM function. A SYMBOLS loop now loops over fully qualified symbol names. It previously looped over bare symbol names. A SYMBOLS loop can now take keywords that explicitly list the type of symbols to loop over. Previously, all symbols were looped over.

24 Apr 2017

Added Symbols section between Data types and Commands.

13 Jun 2017

Changed ESCR program command line argument handling.

All command line arguments to the ESCR program beyond the script name now become the arguments to the top level execution block. Previously, there were arguments for creating constants of specific values before the script was run.

14 Jun 2017

Added pre/post increment/decrement functions.

19 Jun 2017

Changed WRITETO and WRITEEND command names to WRITEPUSH and WRITEPOP.

29 Jun 2017

Changed the LOOP command default increment value for counted loops to always be 1. Was previously 1 or -1 depending on the the from and to values.

1 Oct 2017

Added optional exit status code argument to the STOP command.

Added the RUN command.

Made some minor typo and formatting fixes.

4 Jan 2018

Fixed bug in LOOP SYMBOLS where the first entry of a symbol table was not included.

13 Feb 2018

Added UNQUOTE function.

14 Feb 2018

Added ISINT and ISNUM functions.

TNAM function can now take multiple arguments. The function operates on the concatenation of the arguments.

3 Nov 2018

Added DNAM function. This function was later renamed to DIR.

31 Dec 2018

Added VNL function.

Added APPEND command.

1 Jan 2019

Added user-defined commands via the COMMAND and ENDCMD commands.

11 Jan 2019

Added user-defined functions. Added commands FUNCTION, ENDFUNC, FUNCVAL, and FUNCSTR.

19 Jan 2019

Added NL option to SYM function.

Fixed bugs in the SET and APPEND commands. These did not previously allow the variable to be specified with a qualified name.

22 Jan 2019

Added LOOP DIR command and DENT function.

2 Feb 2019

Added DIR command.

Enhanced the DEL command. The type of symbol can now be specified, and it can now delete file system objects.

3 Feb 2019

Added functions RUNEX, RUNTF, and RUNSO.

4 Feb 2019

Renamed DNAM function to DIR.

Added FILE function.

Fixed bug in DATE function where there output could sometimes be corrupted.

29 Mar 2019

Fixed bug in user-defined function handling. Would sometimes get "extra token" error on line where user-defined function was envoked.

13 May 2019

Fixed DENT function documentation to indicate the default case.

24 May 2019

Added QTK function.

9 Dec 2019

Enhanced DIR command. Previously only took single argument of directory to go to. Added subcommand to optionally perform other actions.

Change FILE function to return the empty string when the object type was requested but the object does not exist. Previously, the program was bombed. The object not existing is still a hard error for the remaining sub-functions (other than TYPE).

30 May 2020

Added pick...endpick blocks. This included adding the commands pick, option, optionif, optionelse, quitopt, quitpick, and endpick, and the function pick.

21 Feb 2021

Quoted string start/end syntax can now be set by the application. The default is still quotes ("...") or opostrophies ('...').