use (moduleDescriptor --)

Inputs

• moduleDescriptor: Known, non-NIL module-path or selected-name descriptor Text.

Outputs

• None.

The input moduleDescriptor is known Text. It names a module path without the trailing .mpl. If it contains no dot after the last path separator, it names one module path. If it contains a dot after the last / or \, only that rightmost post-separator dot has special meaning: the text before it names the module path, and the text after it names one selected public name. Earlier dots, and any dots before the last path separator, remain part of the module path.

Loading a module with use also enables same-name lookup of that module's overload names. The whole-module form directly imports public non-overload names. The single-symbol form loads the module and directly imports only the selected public non-overload name. If the selected public name is an overload, loading the module makes its public overloads available through same-name lookup. A private overload cannot be selected directly, but it still participates in same-name lookup after the module has been loaded.

Behavior

• An empty module path or an empty selected name is invalid.
• Imported names participate in normal name lookup in the current scope and nested inner scopes.
• If the selected module or symbol cannot be found, the program is invalid.
• The first use of a module must be processed in the global scope of a module. Inside { }, inside a Block behind a call boundary, or in a function body it is rejected: File «name.mpl» was not initially loaded at the global level. A Block processed inline by ucall is still the global scope.
• A module that is already loaded can be used again in a function body or in a module-level DIE field; that imports its names into the current scope. For a constructed Dict, import the names in the enclosing scope before constructing the Dict. See Modules.

Known issue: importing names inside a constructed Dict ({ "m" use … }) can produce invalid LLVM IR; Clang reports constant expression type mismatch. Import the names in the enclosing scope before constructing the Dict.

Example

useExample.mpl

overload virtual helper: 3;
virtual first: 1;
virtual second: 2;

test.mpl

"useExample" use

{} 0 {} [
  "-- whole module imports public non-overload names --" printCompilerMessage
  first printStack _:;
  second printStack _:;

  "-- overload still participates in lookup after whole-module load --" printCompilerMessage
  helper printStack _:;

  0
] "main" exportFunction

Expected Output During Compilation

-- whole module imports public non-overload names --
1
2
-- overload still participates in lookup after whole-module load --
3

selectedNameExample.mpl

"useExample.second" use

{} 0 {} [
  "-- selected public name --" printCompilerMessage
  second printStack _:;

  "-- overload still participates in lookup after selected-name load --" printCompilerMessage
  helper printStack _:;

  0
] "main" exportFunction

Expected Output During Compilation

-- selected public name --
2
-- overload still participates in lookup after selected-name load --
3

See also

• NAME: ...; node — Pushes a name onto the name stack and creates a local by consuming that name and one data-stack object.
• codeRef builtin (inputsSchema output options -- code) Constructs a Code schema and pushes a known NIL Code object of that schema.
• def builtin (object name --) Creates a named local or field using a known Text name.
• exportFunction builtin (inputsSchema output options callable name --) Exports a named function built from a Block and a signature.
• importFunction builtin (inputsSchema output options name --) Declares or imports a named function with the supplied signature and binds it in the current scope as a Code local.
• importVariable builtin (schema name --) Creates a local that refers to an external variable of the requested non-Meta schema; the created local is treated as unknown.