Written from a line-by-line source review; every example output is from a real run.
Introduction
The print plugin is the most basic text-output operation in DominScript: following the traditional C-style printf pattern, it builds a string from a format string and any number of values, and writes the result to standard output (stdout). The plugin flushes automatically at the end of every call, so the written text appears at once. It has a single verb, but it is available under two names (PrintF and printf) — both names call exactly the same function.
The two names
print.printf follows the familiar lower-case C convention and most sample scripts use this name. print.PrintF follows the PascalCase convention of DominScript plugins. Same behavior, same implementation — the choice is stylistic. The examples in this reference use the lower-case printf form, since it is the most common.
Loading the plugin
plugin "../plugins/print/PrintPlugin";
A typical flow — formatted output
i32 $n;
double $pi;
$n = 42;
$pi = 3.14159;
printf("n=%d, pi=%.2f\n", $n, $pi);Supported format specifiers
The format string is a simple C-like pattern. A “%” character must be followed by an optional width, an optional “.precision”, and a specifier character. Five specifiers are supported: %d (integer), %x (hexadecimal integer, lower-case), %f (floating-point), %s (string), and %% (a literal % character). The width applies to every specifier as left-padding with spaces to the given width; the precision specifies, for %f, the number of decimal digits (default 6).
What to know about every function (the basics)
The first argument MUST be a string (the format string); the following arguments must have types matching the specifiers.
Type strictness: %d accepts only int, %f only float, %s only string. A different type raises a runtime error.
Argument count strictness: if there are fewer arguments than specifiers, a runtime error.
The specifiers may have width and precision (e.g. %5d, %.2f, %10s). The width left-pads with spaces; %0-prefixed padding is NOT supported.
The output goes to standard output (stdout), and is flushed automatically at the end of every call (line buffering does not prevent the output from appearing).
The return value is ALWAYS 0 (the function does not return the number of characters, only a success indicator).
An unknown specifier (e.g. %z) or an invalid character after a numeric width raises a runtime error.
How to read the signatures
format is the format string, and the following ... is the variable number of evaluated arguments (integer, floating-point, or string). The type after the -> arrow is the return type. print.printf(format, ...) -> int expects a format string and zero or more values, and always returns 0.
Formatted output
Writes formatted text to standard output (stdout). Both names of the function (PrintF and printf) perform the same operation.
print.printf
print.printf(format, ...) -> int
Builds a string from a format string and any number of values, and writes it to standard output.
| Parameter | Type | Description |
|---|---|---|
| format | string | The format string (required). It knows the %d, %x, %f, %s, and %% specifiers; each supports a width (e.g. %5d), and — for %f — a .precision (e.g. %.2f). |
| ... | variadic | The values matching the specifiers in the format string (integer, floating-point, or string), in the corresponding order and type. |
Always 0 (success indicator). A bad format, wrong type, or missing argument raises a runtime error.
printf("dec=[%d] width5=[%5d]\n", 42, 42);
printf("hex=[%x] width4=[%4x]\n", 255, 255);
printf("float=[%f] p2=[%.2f] p0=[%.0f]\n", 3.14159, 3.14159,
3.14159);
printf("str=[%s] width10=[%10s]\n", "hi", "hi");
printf("escape: 100%%\n");dec=[42] width5=[ 42] hex=[ff] width4=[ ff] float=[3.141590] p2=[3.14] p0=[3] str=[hi] width10=[ hi] escape: 100%
The most common text-output operation: in every script you use this to write out computed values, states, and check messages. You can combine several values in one call; the type strictness helps catch mistakes early.
print.PrintF
print.PrintF(format, ...) -> int
Exactly the same as printf — a PascalCase alias for the same function.
| Parameter | Type | Description |
|---|---|---|
| format | string | See printf. |
| ... | variadic | See printf. |
Always 0. printf and PrintF are semantically identical.
print.PrintF("int=%d, string=%s\n", 7, "apple");int=7, string=apple
Use the PrintF name if you want to consistently follow the DominScript plugin-API PascalCase convention in your source code. There is no behavioral difference from the lower-case printf.
Practical notes
What the print plugin is good for
Diagnostic messages and intermediate values during development and debugging.
Log-like output in command-line scripts (simpler than the full log plugin).
User feedback: status, errors, results — all formatted nicely.
Mixing numeric values and strings into one piece of text in a single call (no need for separate string concatenation).
The specifiers exactly
%d for the decimal integer (signed, if negative). %x for the hexadecimal integer (lower-case “a”..“f”), without sign. %f for the floating-point, by default with 6 decimal digits; with .precision (e.g. %.2f) you can set the desired number of decimals. %s for the string (unchanged). %% places a single literal % character in the output. The width left-pads with spaces in every case.
What it does not support
The plugin provides a focused, minimal printf implementation. It does NOT know: %0-prefix padding (zero-padding), left-alignment (% - flag), %u (unsigned), %o (octal), %c (character), %p (pointer), %e/%g (scientific float), %lld/long modifiers, or any length modifiers. The supported %d/%x/%f/%s/%% with width/.precision covers typical script needs; if you need more complex formatting, preprocess with the str.* functions.
Return value
printf ALWAYS returns 0 (success), not the count of characters written. If you need the character count, build the string first (with the str plugin), query its length, and then write it with printf. The 0-return lets you embed printf into a complex expression without disturbing the order of the output.
Error handling
A wrong argument count (fewer arguments than specifiers), a type mismatch (for example passing a double to %d), or an unknown specifier are reported by the runtime as a runtime error, and the script stops. Non-printf errors (for example memory exhaustion) are rare, but also raise a runtime error. On a successful call, the output appears on stdout at once (flushing is automatic).
The script_state central script-state plugin
A single byte buffer shared between callbacks — complete function reference