Written from a line-by-line source review; every example output is from a real run.
Introduction
The abi plugin demonstrates the parameter type handling of the DominScript plugin ABI (Application Binary Interface): how the plugin system receives and checks arguments passed by value and by reference, and how it enforces the expected type (integer, floating-point, number). It is a sample and verification plugin: each function expects a particular parameter convention and runs only if the caller passes exactly that; otherwise it raises an error. The returned values are simple, easily recognizable markers that show which convention took effect.
Value and reference
There are two kinds of parameter passing. The by-value (Expect*) functions receive a COPY of the given number and return a computed value (demonstrating thereby that the type arrived correctly). The by-reference (Accept*Ref) functions receive a REFERENCE pointing to the variable (in DominScript the $variable is passed as a reference), and return a fixed marker number that confirms the reference convention worked correctly.
Type strictness
Every function strictly checks the parameter's type. ExpectInt accepts only an integer (i32), ExpectFloat only a floating-point (double) value; ExpectNumber accepts both (and treats them as floating-point). AcceptIntRef expects a reference to an integer variable, AcceptFloatRef to a floating-point variable. If the type or the parameter kind (value vs reference) does not match, the call raises a runtime error.
Loading the plugin
plugin "../plugins/print/PrintPlugin"; plugin "../plugins/abi_types/AbiTypesPlugin";
A typical flow — trying out the type conventions
i32 $i;
double $f;
$i = 10;
$f = 3.0;
printf("%d\n", abi.ExpectInt(10)); // by value, integer
printf("%d\n", abi.AcceptIntRef($i)); // by referenceWhat to know about every function (the basics)
The Expect* functions receive the argument by value and return a computed result: ExpectInt → +1, ExpectFloat → +0.5, ExpectNumber → +0.25 (always as floating-point).
ExpectInt accepts only an integer, ExpectFloat only a floating-point; ExpectNumber accepts both an integer and a floating-point (the result is floating-point in both cases).
The Accept*Ref functions expect a variable reference (the $variable form), and return a fixed marker number: AcceptIntRef → 111, AcceptFloatRef → 222.
The marker numbers (111, 222) do not mean a value on their own — they only confirm that the appropriate reference convention took effect.
Every function is strict: a wrong type or a wrong parameter kind (a value instead of a reference or vice versa) raises a runtime error.
The plugin is stateless; the functions are independent of each other.
How to read the signatures
value is a by-value parameter, value (reference) is a reference pointing to the variable. The type after the -> arrow is the return type. For example, abi.ExpectInt(value) -> int takes an integer value and returns an integer.
Value parameters
Receiving a number by value, with strict type checking. The result is a computed value that confirms the correct type reception.
abi.ExpectInt
abi.ExpectInt(value) -> int
Expects an integer value and returns it increased by one.
| Parameter | Type | Description |
|---|---|---|
| value | int | The integer value (only i32 is accepted). |
value + 1. If the parameter is not an integer, a runtime error.
printf("%d\n", abi.ExpectInt(10));11
To demonstrate and try out the integer (i32) by-value parameter convention. If you pass a floating-point, the call raises an error — this illustrates the type strictness.
abi.ExpectFloat
abi.ExpectFloat(value) -> double
Expects a floating-point value and returns it increased by 0.5.
| Parameter | Type | Description |
|---|---|---|
| value | double | The floating-point value (only double is accepted). |
value + 0.5. If the parameter is not a floating-point, a runtime error.
printf("%f\n", abi.ExpectFloat(2.0));2.500000
To demonstrate the floating-point (double) by-value parameter convention. If you pass an integer, the call raises an error — this is how the explicitly floating-point parameter differs from ExpectNumber, which accepts both.
abi.ExpectNumber
abi.ExpectNumber(value) -> double
Expects a number (integer or floating-point) and returns it as floating-point, increased by 0.25.
| Parameter | Type | Description |
|---|---|---|
| value | number | An integer or floating-point value (both are accepted). |
value + 0.25 as floating-point. If the parameter is not a number, a runtime error.
printf("%f\n", abi.ExpectNumber(10));
printf("%f\n", abi.ExpectNumber(2.0));10.250000 2.250000
To demonstrate the flexible “any number” parameter convention: it accepts both an integer and a floating-point value, and processes them uniformly as floating-point. A useful pattern when a function does not care whether it gets a whole or a fractional number.
Reference parameters
Receiving a reference to a variable, with checking of the referenced type. The result is a fixed marker number that confirms the correct reference reception.
abi.AcceptIntRef
abi.AcceptIntRef(value) -> int
Expects a reference to an integer variable and returns a fixed marker number.
| Parameter | Type | Description |
|---|---|---|
| value | int (reference) | A reference pointing to an integer variable (the $variable form). |
111 (a fixed marker). If the parameter is not a reference, a runtime error.
i32 $i;
$i = 10;
printf("%d\n", abi.AcceptIntRef($i));111
To demonstrate the integer-reference (by-reference) parameter convention. The returned 111 is not a value but a sign that the reference arrived correctly. If you pass by value (not as $variable), the call raises an error.
abi.AcceptFloatRef
abi.AcceptFloatRef(value) -> int
Expects a reference to a floating-point variable and returns a fixed marker number.
| Parameter | Type | Description |
|---|---|---|
| value | double (reference) | A reference pointing to a floating-point variable (the $variable form). |
222 (a fixed marker). If the parameter is not a reference, a runtime error.
double $f;
$f = 3.0;
printf("%d\n", abi.AcceptFloatRef($f));222
To demonstrate the floating-point-reference parameter convention. The returned 222 confirms the correct reference reception. The marker number that differs from AcceptIntRef's makes it clear which convention took effect.
Practical notes
What the abi plugin is good for
Illustrating the plugin ABI's parameter type handling: how an integer, a floating-point, and a by-reference argument arrive.
A verification sample: when developing a new plugin, it shows as a reference the correct pattern of type checking and parameter conventions.
Demonstrating type strictness: it is clearly visible when the system rejects an argument of an inappropriate type or kind.
A testing aid: a quick check of how value and reference passing work.
Value vs reference
The Expect* functions receive the parameter by value (a copy of the given number) and confirm the correct type reception with a computed result. The Accept*Ref functions receive the reference passed in the $variable form, and confirm with a fixed marker number (111 or 222) that the reference convention worked correctly. The difference between the two marker numbers makes it clear which function (and thus which convention) ran.
As a sample for other plugins
This plugin is primarily for demonstration and verification. When writing your own plugin, it shows clearly how to declare and check a value or reference parameter, and how the system handles type matching. For actual, useful operations the other plugins (str, map, fileio, etc.) provide a rich API.
Error handling
Every function strictly checks the parameter: a wrong argument count, a wrong type (for example a floating-point for ExpectInt), and a wrong parameter kind (a value instead of a reference or vice versa) are reported by the runtime as a runtime error, and the script stops. On a successful call, Expect* returns the computed value and Accept*Ref the fixed marker number.
The runtimeutil runtime-utility plugin
Waiting, timestamp, and local IP address — complete function reference