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:
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.
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:
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:
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.
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.
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.
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.
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.
Finished up command descriptions, added function descriptions.
Some fixes and the like. CHAR function now takes multiple arguments. PI function now takes second optional argument.
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.
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.
Added Symbols section between Data types and Commands.
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.
Added pre/post increment/decrement functions.
Changed WRITETO and WRITEEND command names to WRITEPUSH and WRITEPOP.
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.
Added optional exit status code argument to the STOP command.
Added the RUN command.
Made some minor typo and formatting fixes.
Fixed bug in LOOP SYMBOLS where the first entry of a symbol table was not included.
Added UNQUOTE function.
Added ISINT and ISNUM functions.
TNAM function can now take multiple arguments. The function operates on the concatenation of the arguments.
Added DNAM function. This function was later renamed to DIR.
Added VNL function.
Added APPEND command.
Added user-defined commands via the COMMAND and ENDCMD commands.
Added user-defined functions. Added commands FUNCTION, ENDFUNC, FUNCVAL, and FUNCSTR.
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.
Added DIR command.
Enhanced the DEL command. The type of symbol can now be specified, and it can now delete file system objects.
Renamed DNAM function to DIR.
Added FILE function.
Fixed bug in DATE function where there output could sometimes be corrupted.
Fixed bug in user-defined function handling. Would sometimes get "extra token" error on line where user-defined function was envoked.
Fixed DENT function documentation to indicate the default case.
Added QTK function.
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).
Added pick...endpick blocks. This included adding the commands pick, option, optionif, optionelse, quitopt, quitpick, and endpick, and the function pick.
Quoted string start/end syntax can now be set by the application. The default is still quotes ("...") or opostrophies ('...').