Module Renaming

An Avail programmer can short-circuit the module resolution process for an import target by supplying a module renames file. A module renames file is a plain text document that contains Unicode code points in the UTF-8 character encoding. Its contents are zero or more module renaming rules:

Where a module renaming rule is expressed by sourceName → targetName, and sourceName and targetName are canonical names denoted as simple quoted strings. In this context, a simple quoted string comprises a quotation mark " (U+0022), then arbitrarily many characters other than a quotation mark, then a quotation mark. A module renaming rule is a directive to the module resolution process to replace each occurrence of sourceName with targetName before attempting to derive a file reference.

All official Avail tools released and supported by The Avail Foundation, LLC, such as the Avail workbench and the command-line Avail compiler, support specification of the module renames file via the AVAIL_RENAMES environment variable.^[1]

The need to augment the usual module resolution process with a module renames file is unusual; the usual use case is for the module renames file to be an empty document.

Here is an example of a nonempty module renames file:

In this fictional scenario, the innovative folks behind Virtual Walrus Polisher Plus are having problems with a couple of their robot's control modules.^[2] They have written both debug and release versions of the controllers responsible for the polishing brush and the varnish applicator attachments of the robot. Presumably the debug versions contain additional logging, assertions, etc. The module renames file directs the system to resolve references to the release modules into references to the debug modules before allowing module name resolution to proceed. Because of this interference, the system will load the debug modules instead of the release modules.

[1] These tools may also permit the module renames path to be specified by some other means, but they will always honor the AVAIL_RENAMES environment variable.

[2] Since the product is Virtual Walrus Polisher Plus, presumably these are controllers for the attachments of a virtual robot that inhabits the same level of reality as the virtual walrus.