The Interpreter

<-- Back | Next -->

---

Builds of the interpreter are available here. An online interpreter is provided by Dennis Mitchell.

Shnap Environment

Shnap has a home directory it uses to store the standard lib. This directory is defined by the environment variable SHNAP_HOME. If SHNAP_HOME is not set, the home directory defaults to user home/.shnap. The location of user home changes depending on the operating system, but, for example, on windows it is C:/users/<username>. If the shnap home directory does not exist, the interpreter will create it and extract the standard libraries to it.

When the Shnap interpreter is initialized to execute a script, it goes through multiple loading stages.

When a "path" is mentioned below, it means a list of directories that are used for searching for Shnap scripts/modules. The lookup algorithm recognizes three file types, .shnap, .cshnap, and .sar (see compilation). Each directory is treated as a root package with .shnap and .cshnap modules inside it. Each directory is also recursively searched for .sar files, which are each individually treated as a root package, with compressed .shnap or .cshnap modules inside them. Modules in the file tree, as opposed to a .sar file, are prioritized over the modules located in .sar files. The order of modules searched in the file tree (and the .sar files) is undefined and should not be relied upon. The loading stages of the interpreter are:

• NATIVES: during the native loading stage, all modules available in the native path are loaded. Every module loaded during this stage is marked as a native module.
• BUILTINS: during the builtin loading stage, all modules available in the builtins path are loaded, and all modules in the prelib path are loaded. Every module loaded from the builtins path is marked as a builtin module, while the prelib modules are marked as prelib modules.
• NORMAL: the normal path is indexed for .sar files and the environment is setup.

Modules have different properties depending on what stage and path they are loaded from:

• native modules (all modules loaded from the native path) have all of their importable fields added to every script loaded after the NATIVES stage, including prelib scripts, builtin scripts, and normal scripts.
• builtin modules (all modules loaded from the builtins path) have all of their importable fields added to every script loaded after the BUILTINS stage, e.g. all normal scripts.
• prelib modules do not have their fields added to any script, but they are available for import in builtin scripts.
• normal scripts do not have any special properties, can import scripts loaded during any stage, and don't have their fields added to any scripts

The natives, prelib, builtins, and normal paths are specified with interpreter flags (see below), but each one has a default location that is always available (flags do not override this default location, they simply add more directories to the path). The default natives location is SHNAP_HOME/natives, the default prelib location is SHNAP_HOME/prelib, the default builtins location is SHNAP_HOME/builtins, and the default normal location is SHNAP_HOME/lib. When the interpreter is run in execute mode, the normal path will always gain at least one path (the directory of the script being executed), and other directories can be added with the appropriate flags.

Note: This loading process only occurs when a script needs to be executed. If the interpreter is compiling, rather than executing, this process will not occur.

Interpreter Flags

Interpreter help message:

Flags:
    -arg: The file(s)/script(s) to execute/compile
    -natives: A semi-colon separated list of files to use as native builtins
    -prelib: A semi-colon separated list of files to use as prelibs
    -builtin: A semi-colon separated list of files to use as builtins
    -path: A semi-colon separated list of files to use when searching for imports and scripts
    -compile: The directory to compile
    -keepScripts: If present, scripts and .sar files will be compiled
    -archive: The name of the archive
    -exec: A name of a script to execute
    -reloadHome: If present, update the standard libraries
    -debug: If present, tracebacks will be considerably more detailed
    -shell: If present, arg, exec and compile flags will be ignored and the Shnap shell will start
    -startScriptArgs: forces the remaining arguments to be used for the script, rather than the interpreter

Interpreter flags:

• If -shell is present, -arg, -compile, and -exec, and their related flags, will all be ignored, and the Shnap shell will start. If -shell is not present, -arg is required and:
• -arg is used differently depending on what flags are present:
  • If -compile is present:
    • -arg is the output directory
    • The value of -compile is the directory to compile
    • The value of -archive will be the name of the resulting archive
    • All path-related flags, and -debug, are ignored
  • If -exec is present OR -compile is not present
    • If -exec is not present: -arg is a script name and the directory where the interpreter was invoked is added to the normal path, -arg is the script that will be executed
    • If -exec is present: -arg is added to the normal path, and the value of -exec is a script name which will be executed
    • All the files in the flag will be added to the natives path
    • All the files in the flag will be added to the prelib path
    • All the files in the flag will be added to the builtin path
    • All the files in the flag will be added to the normal path
• If -reloadHome is present, the standard libraries will be re-extracted from the interpreter

Script arguments:

• Script arguments must come after all the interpreter arguments and flags
• The start of script arguments is determined by one of two ways:
  • An unrecognized flag will immediately trigger the start of script arguments
  • The -startScriptArgs flag will cause all following arguments to be interpreted as script arguments