codeRef · Builtins · MPL Reference

`codeRef (inputsSchema output options -- code)`

Inputs

inputsSchema: Descriptor of the Code input stack.
output: Descriptor of the Code output stack.
options: Descriptor of the Code calling options.

Outputs

code: Constructed Code object.

codeRef is a Code schema constructor. A callable signature is formed from an input descriptor, an output descriptor, an options descriptor, and codeRef.

codeRef does not compile a body and does not create locals from the names written inside inputsSchema. The result is a known NIL Code object of that signature.

Behavior

inputsSchema supplies the input schema as a Dict or the empty Tuple ().
output supplies the output schema.
Input order on the data stack follows the stack-order rule of Code signatures.
options supplies signature options as a Dict or the empty Tuple (). See Options descriptor below for the recognized fields.
Input names are not part of the schema: two signatures with the same input schemas, output, and options are one schema, and printing shows the input names of the first one created, which can be an unnamed one the compiler creates for a Block it compiles into a function or for ^, ceil, cos, floor, log, log10, sin or sqrt computed by a run-time call (Input «» in diagnostics).
codeRef? reports TRUE for the result, while code? reports FALSE.
The pushed object is not directly callable by call, because call rejects known NIL Code objects.
isConst reports TRUE for the result, while known? reports FALSE because the value is still NIL.
Usable non-NIL code comes from exportFunction, importFunction, or assignment of a matching Block to a Code destination.
If the signature is invalid, the builtin fails instead of pushing a result.

Options descriptor

The options input is a Dict whose fields configure the resulting Code schema, or the empty Tuple () when no options are needed. The empty Dict {} is also valid and equivalent to (). Every option field must be non-static and known; a Text option must also be non-NIL. Unrecognized field names are invalid.

Two option fields are recognized:

Name	Schema	Default	Meaning
`convention`	Text	absent = LLVM default	LLVM calling-convention keyword. It is recorded in the Code schema but not emitted in generated LLVM declarations, definitions, or calls (known issue). Typical values include `"ccc"` (C calling convention) and `"x86_stdcallcc"`. The Standard Library module conventions exports portable names `cdecl` and `stdcall` that resolve to the correct string for the current target.
`variadic`	Cond	absent = `FALSE`	When `TRUE`, the function accepts additional arguments after its declared inputs. At call sites the additional arguments are passed as a List or Tuple placed on the data stack below the declared inputs. Each item of that Struct must be non-Meta.

Known issue: another field order, or a field written with its default value (variadic: FALSE), makes another Code schema; same reports FALSE, and a Code input declared the other way rejects the value as of different schema. Write the option fields in one order and omit fields at their default.

Example

{} 0 {} [
  "-- empty signature --" printCompilerMessage
  {} () {} codeRef printStack _:;

  "-- non-empty signature is still only a signature value --" printCompilerMessage
  { value: 0; } 0 {} codeRef printStack _:;

  "-- family checks --" printCompilerMessage
  { value: 0; } 0 {} codeRef codeRef? printStack _:;
  { value: 0; } 0 {} codeRef code? printStack _:;
  { value: 0; } 0 {} codeRef known? printStack _:;
  { value: 0; } 0 {} codeRef isConst printStack _:;

  "-- convention option --" printCompilerMessage
  {} () {convention: "ccc";} codeRef printStack _:;

  "-- variadic option --" printCompilerMessage
  {format: 0nx;} 0 {convention: "ccc"; variadic: TRUE;} codeRef printStack _:;

  0
] "main" exportFunction

Expected Output During Compilation

-- empty signature --
{} () {} codeRef CNIL
-- non-empty signature is still only a signature value --
{value: Int32;} Int32 {} codeRef CNIL
-- family checks --
TRUE
FALSE
FALSE
TRUE
-- convention option --
{} () {convention: "ccc";} codeRef CNIL
-- variadic option --
{format: Natx;} Int32 {convention: "ccc"; variadic: TRUE;} codeRef CNIL

codeRef (inputsSchema output options -- code)