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 belong only to the imported signature. They do not create locals in the importing scope.

inputsSchema lists the parameters in C declaration order, but the data stack holds them in reverse: the first C parameter is the top stack item and the last C parameter is the deepest. To call f(a, b, c), push c, then b, then a, and then mention f. Stack effects in this reference are written from the lowest stack position to the top, so an imported function is documented as (c b a -- result), the reverse of its C parameter list.

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.
• At the call site the first declared input is the top stack item and the last declared input is the deepest; a mismatching item schema is reported as Input «NAME» is of different schema.
• 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.
• 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.