Written from a line-by-line source review; every example output is from a real run.
Introduction
The stdio plugin handles the program's standard input and output streams (standard input, output, error): you can write text to standard output or standard error, read lines from standard input, check whether the input has reached its end, and flush the output buffers. The plugin is stateless; every call works directly on the given stream.
Three streams
The three standard streams: standard output (stdout) is for the program's normal output, standard error (stderr) for error and diagnostic messages, and standard input (stdin) for incoming data. Write and WriteLine write to stdout, WriteError to stderr; ReadLine reads from stdin. So the error messages can be separated from the normal output (for example in a pipeline or with redirection).
Automatic flushing
On every write (Write / WriteLine / WriteError) the plugin immediately flushes the given stream, so the written text appears at once. The Flush function can be called separately too, but is not needed for normal writing — it is mainly useful if you also wrote by another route (for example the print plugin) and want to be sure.
Loading the plugin
plugin "../plugins/print/PrintPlugin"; plugin "../plugins/stdio/StdioPlugin";
A typical flow — reading input, writing a response
string $line[256];
$line = stdio.ReadLine();
stdio.WriteLine("You typed: " + $line);What to know about every function (the basics)
The write functions (Write / WriteLine / WriteError) return the number of bytes actually written. WriteLine also counts the added newline (one byte).
ReadLine reads a whole line from stdin and TRIMS the trailing newline (it handles the CRLF \r\n pair correctly too). At the end of the file/input it returns an empty string.
IsEof returns 1 if standard input has reached its end, otherwise 0.
Flush flushes the stdout and stderr buffers and always returns 1.
The write functions flush automatically after every call.
An error (stopping the script) is caused by a wrong argument count or type, and by an actual write/read failure.
How to read the signatures
text is the text to write; ReadLine, IsEof, and Flush take no arguments. The type after the -> arrow is the return type. For example, stdio.WriteLine(text) -> int takes a text and returns the number of bytes written (including the newline).
Writing
Writing text to standard output (stdout) or standard error (stderr). The return value is the number of bytes written.
stdio.Write
stdio.Write(text) -> int
Writes the text to standard output, without adding a newline.
| Parameter | Type | Description |
|---|---|---|
| text | string | The text to write. |
The number of bytes written.
printf("[%d]\n", stdio.Write("Hello"));Hello[5]
When you want to write text without a newline — for example you build a line in several pieces, or you write a prompt for which you wait for a response on the same line.
stdio.WriteLine
stdio.WriteLine(text) -> int
Writes the text to standard output and appends a newline.
| Parameter | Type | Description |
|---|---|---|
| text | string | The text to write. |
The number of bytes written (counting the newline too).
printf("[%d]\n", stdio.WriteLine("Hello"));Hello [6]
The most common output operation: writing a whole line. The return value is meant to include the newline (“Hello” 5 + the newline 1 = 6).
stdio.WriteError
stdio.WriteError(text) -> int
Writes the text to standard error (stderr), without adding a newline.
| Parameter | Type | Description |
|---|---|---|
| text | string | The (error) message to write. |
The number of bytes written.
printf("[%d]\n", stdio.WriteError("error-message"));error-message[13]
For writing error and diagnostic messages that you want to separate from the normal output — for example so they do not mix into the data stream under redirection or in a pipeline.
Reading
Reading a line from standard input and checking the end of the input.
stdio.ReadLine
stdio.ReadLine() -> string
Reads a whole line from standard input, trimming the trailing newline.
This function takes no arguments.
The read line (the trailing \n and the optional \r trimmed). At the end of the input, an empty string.
string $line[256]; $line = stdio.ReadLine(); stdio.WriteLine($line);
(the typed line, without a newline)
For reading interactive input or line-by-line processing (a user response, data arriving via a pipe). It trims the newline automatically, so the resulting text can be processed directly.
stdio.IsEof
stdio.IsEof() -> int
Tells whether standard input has reached its end (EOF).
This function takes no arguments.
1 if the input has reached its end; otherwise 0.
string $line[256];
$line = stdio.ReadLine();
printf("%d\n", stdio.IsEof());0
To stop line-by-line processing of the input: read with ReadLine in a loop, and stop when IsEof is 1. (After reading a single line ending in a newline, IsEof is still 0, because the newline was the end of the line, not the end of the input.)
Flushing
Immediately flushing the output buffers.
stdio.Flush
stdio.Flush() -> int
Flushes the standard output and standard error buffers, so the pending text appears at once.
This function takes no arguments.
Always 1.
stdio.Write("in progress...");
printf("%d\n", stdio.Flush());in progress...1
When you want to be sure all pending output appears — for example before a long operation, or if you also wrote by another route (the print plugin). The stdio write functions flush on their own, so it is not needed for normal use.
Practical notes
What the stdio plugin is good for
Interactive command-line programs: reading input (ReadLine) and writing a response (WriteLine).
Pipeline (pipe) processing: reading standard input line by line to the end (ReadLine + IsEof).
Separating error messages from the normal output (WriteError to stderr).
Knowing the exact number of bytes written (all three write functions return it).
stdout vs stderr
The normal output (data, results) goes to standard output (Write/WriteLine), the error and diagnostic messages to standard error (WriteError). This separation is what lets you redirect the program's output to a file or another program while the errors stay on the screen — or vice versa.
Line reading
ReadLine returns a whole line without the trailing newline (it handles the Windows-style CRLF \r\n pair correctly too), so the resulting text can be processed at once. To iterate over the input line by line, read with ReadLine in a loop and recognize the end of the input with IsEof. At the end of the input ReadLine returns an empty string.
Error handling
A wrong argument count or type, and an actual write or read failure (for example a closed stream) are reported by the runtime as a runtime error, and the script stops. The usual states are signaled by a neutral return value: IsEof gives 0/1, Flush always 1, and the write functions the number of bytes written.
The abi type-convention plugin
A demonstration of plugin parameter type handling (value and reference) — complete function reference