importFunction (inputsSchema output options name --)

Inputs

• inputsSchema: Descriptor of the imported function input stack.
• output: Descriptor of the imported function output stack.
• options: Descriptor of the imported function calling options.
• name: Known imported function name.

Outputs

• None.

importFunction constructs a function signature, records the external declaration, and creates the imported function name in the current module as a usable Code local.

Names written inside inputsSchema do not create locals in the importing scope.

Input order on the data stack follows the stack-order rule of Code signatures. Stack effects use the notation defined in Objects and values.

The created imported name is not a known NIL Code object. The builtin creates or reuses a declaration only; it does not compile a Block body.

Pending overload and private modifiers apply to the imported name. A pending virtual modifier is invalid here.

Behavior

• inputsSchema, output, and options are interpreted through the same signature-building logic as codeRef. In that logic, inputsSchema and options are Dict descriptors or the empty Tuple (). The recognized option fields are convention (Text) and variadic (Cond); see Options descriptor on the codeRef page for the full specification.
• name must be known, non-NIL, non-empty Text.
• If the function name was already declared with the same signature, importFunction reuses that declaration.
• If the function name was already declared with a different signature, compilation fails.
• If the function name was not declared yet, the builtin creates a new external declaration.
• The earlier declaration may come from any module of the program, even from a private import in a library module; with different signatures, the one processed second fails.
• Valid only at module level.
• The builtin creates the imported Code name immediately. That name is available for read, call, export, and later lookup in the same module.
• Repeating importFunction with the same name and signature still creates another current-scope Code name; normal newest-to-oldest lookup then selects the latest one.
• The created imported name is usable and non-NIL, but known? still reports FALSE for it.

Example

importExample.mpl

"-- codeRef only builds NIL code --" printCompilerMessage
{text: 0nx;} 0 {} codeRef printStack _:;
{text: 0nx;} 0 {} codeRef known? printStack _:;

private overload {text: 0nx;} 0 {} "puts" importFunction
{text: 0nx;} 0 {} "puts" importFunction

"-- imported name immediately usable here --" printCompilerMessage
@puts printStack _:;
@puts known? printStack _:;

virtual visible: 2;

test.mpl

"importExample.visible" use

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

  "-- private overload imported name participates in lookup --" printCompilerMessage
  @puts printStack _:;
  @puts known? printStack _:;
  0
] "main" exportFunction

Expected Output During Compilation

-- codeRef only builds NIL code --
{text: Natx;} Int32 {} codeRef CNIL
FALSE
-- imported name immediately usable here --
{text: Natx;} Int32 {} codeRef
FALSE
-- selected public name --
2
-- private overload imported name participates in lookup --
{text: Natx;} Int32 {} codeRef
FALSE

Parameter order

{fd: 0; buf: 0nx; count: 0nx;} 0ix {} "write" importFunction

{} 0 {} [
  "-- write(fd, buf, count): count is pushed first, fd is on top --" printCompilerMessage
  6nx "hello\n" storageAddress 1 write _:;
  0
] "main" exportFunction

Expected Output During Compilation

-- write(fd, buf, count): count is pushed first, fd is on top --

Expected Output

hello

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.
• 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.
• use builtin (moduleDescriptor --) Imports public names from a module path named by known Text, or imports one selected public name when the last dot after the last path separator separates the module path from that name.