std: add std.Io (print, println, nl, put_*, put_f, get_c, eof, read, getline) with test, learn example and docs

10 files changed, 146 insertions, 4 deletions

diff --git a/README.md b/README.md
index 6a56945..f6e5ce8 100644
--- a/README.md
+++ b/README.md
@@ -196,9 +196,9 @@ fn main() { rt.put_s(greeting); rt.put_n(answer + table[0]); return 0; }
 
 a unit is read whole and scanned for function signatures before it compiles, so calls can come before definitions, tags included, and prototypes are optional. `main` runs after the whole program has compiled. use `void f()` for a function with no result and `return;` to leave it; value-returning functions use an explicit result type or the inferred `fn` form.
 
-the runtime api lives in the `rt` namespace and requires `include rt;`: `rt.put_c`, `rt.get_c`, `rt.eof`, `rt.put_s`, `rt.put_n`, `rt.halt`, `rt.len_w`, `rt.eq_w`, `rt.copy_w`, `rt.fill_w`, the packed-string helpers `rt.len_s`, `rt.at_s`, `rt.slice_s`, `rt.cat_s`, `rt.eq_s`, `rt.s_to_n`, `rt.n_to_s` and `rt.put_bs`, allocation and ownership helpers such as `rt.new`, `rt.new_t`, `rt.free`, `rt.gc`, `rt.memreport`, and host functions including `rt.syscall` and `rt.readfile`. their signatures and descriptions are in the runtime source comments and built-in hover table. `src/lib/std.zc` declares the `std` namespace; its static groups are called as `std.Group.name(args)`: `std.Text`, `std.Num`, `std.Host`, `std.Bytes`, `std.Arena`, and `std.Buf`. the constructors `std.arena(n)` and `std.bnew(n)` and globals such as `std.argc` and `std.argv` are plain declarations in that namespace. capture uses static functions: `std.capture.start()` begins output capture and `std.capture.end(buf)` ends it and returns the buffer.
+the runtime api lives in the `rt` namespace and requires `include rt;`: `rt.put_c`, `rt.get_c`, `rt.eof`, `rt.put_s`, `rt.put_n`, `rt.halt`, `rt.len_w`, `rt.eq_w`, `rt.copy_w`, `rt.fill_w`, the packed-string helpers `rt.len_s`, `rt.at_s`, `rt.slice_s`, `rt.cat_s`, `rt.eq_s`, `rt.s_to_n`, `rt.n_to_s` and `rt.put_bs`, allocation and ownership helpers such as `rt.new`, `rt.new_t`, `rt.free`, `rt.gc`, `rt.memreport`, and host functions including `rt.syscall` and `rt.readfile`. their signatures and descriptions are in the runtime source comments and built-in hover table. `src/lib/std.zc` declares the `std` namespace; its static groups are called as `std.Group.name(args)`: `std.Io`, `std.Text`, `std.Num`, `std.Host`, `std.Bytes`, `std.Arena`, and `std.Buf`. the constructors `std.arena(n)` and `std.bnew(n)` and globals such as `std.argc` and `std.argv` are plain declarations in that namespace. capture uses static functions: `std.capture.start()` begins output capture and `std.capture.end(buf)` ends it and returns the buffer.
 
-the standard library has seven static groups: `std.capture` (output capture), `std.Text` (char* strings), `std.Num` (integer helpers), `std.Host` (environment, clock, files and raw syscalls; `std.Host.open` returns a `std.File` whose drop closes it), `std.Bytes` (packed byte strings), `std.Arena` (word arenas) and `std.Buf` (byte buffers). the array algorithms `std.array_find`, `std.array_map`, `std.array_reduce` and the others are plain functions in the same namespace. every public declaration in `src/lib/std.zc` has a comment that the language server shows on hover. `examples/std_tour.zc` calls one or two functions from each group and the array algorithms; run it with `build/bin/zy < examples/std_tour.zc`.
+the standard library has eight static groups: `std.capture` (output capture), `std.Io` (the terminal: `print`, `println`, `nl`, `put_c`, `put_s`, `put_n`, `put_hex`, `put_bs`, `put_f`, `get_c`, `eof`, `read`, `getline`; the same operations as the `rt` writers, which stay), `std.Text` (char* strings), `std.Num` (integer helpers), `std.Host` (environment, clock, files and raw syscalls; `std.Host.open` returns a `std.File` whose drop closes it), `std.Bytes` (packed byte strings), `std.Arena` (word arenas) and `std.Buf` (byte buffers). the array algorithms `std.array_find`, `std.array_map`, `std.array_reduce` and the others are plain functions in the same namespace. every public declaration in `src/lib/std.zc` has a comment that the language server shows on hover. `examples/std_tour.zc` calls one or two functions from each group and the array algorithms; run it with `build/bin/zy < examples/std_tour.zc`.
 
 `std.argc` and `std.argv` provide command-line arguments to `main`; `std.envc` and `std.envp` provide environment entries in `NAME=value` form. `std.argc` is an `int`, and `std.argv` is a `char*[?]`; the environment fields have matching types. `std.argv[0]` is the program path, or `<eval>` when source comes from stdin. `std.libinit()` fills all four before `main` when the program includes `std`. Since include dependencies do not import into the caller, runtime calls also require `include rt;`:
 
diff --git a/docs/LEARN.md b/docs/LEARN.md
index ed12caf..35ee914 100644
--- a/docs/LEARN.md
+++ b/docs/LEARN.md
@@ -531,6 +531,30 @@ output:
 124
 ```
 
+### terminal input and output
+
+`std.Io` groups the terminal: `print(s)` and `println(s)` write a string, `nl()` a line break, and `put_c`, `put_s`, `put_n`, `put_hex`, `put_bs` and `put_f` write a character, a string, a decimal or hexadecimal integer, a packed byte string and a float. `get_c()`, `eof()`, `read(buf, n)` and `getline(buf, n)` read the program input; `getline` drops the line break and returns -1 at the end of the input. zc has no varargs or overloading, so `print` takes a string only and numbers use their own writers. the writers go through `rt.put_c`, so `std.capture` sees them, and the `rt` names (`rt.put_n` and the rest) keep working.
+
+[example source](../examples/learn/35-io.zc):
+
+```zc
+namespace;
+include std;
+fn main() {
+	std.Io.print("total: "); std.Io.put_n(6 * 7); std.Io.nl();
+	std.Io.print("ratio: "); std.Io.put_f(1.0 / 4.0); std.Io.nl();
+	std.Io.println("done");
+}
+```
+
+output:
+
+```text
+total: 42
+ratio: 0.250000
+done
+```
+
 ### host services
 
 `rt.syscall(op, a, b, c)` calls the runtime interface to the vm's syscall gate. the runtime defines names such as `SYS_OPEN`, `SYS_READ`, `SYS_WRITE`, `SYS_GETENV`, and `SYS_TIME`. unsupported operations return -1. `std.Host.now()` wraps the clock request.
diff --git a/examples/learn/35-io.out b/examples/learn/35-io.out
new file mode 100644
index 0000000..9aa7f64
--- /dev/null
+++ b/examples/learn/35-io.out
@@ -0,0 +1,3 @@
+total: 42
+ratio: 0.250000
+done
diff --git a/examples/learn/35-io.zc b/examples/learn/35-io.zc
new file mode 100644
index 0000000..e370daa
--- /dev/null
+++ b/examples/learn/35-io.zc
@@ -0,0 +1,7 @@
+namespace;
+include std;
+fn main() {
+	std.Io.print("total: "); std.Io.put_n(6 * 7); std.Io.nl();
+	std.Io.print("ratio: "); std.Io.put_f(1.0 / 4.0); std.Io.nl();
+	std.Io.println("done");
+}
diff --git a/examples/std_tour.zc b/examples/std_tour.zc
index df4d02b..1ef33f3 100644
--- a/examples/std_tour.zc
+++ b/examples/std_tour.zc
@@ -9,6 +9,9 @@ int dbl(int x) { return x * 2; }
 int add(int a, int b) { return a + b; }
 
 fn main() {
+	// io: the terminal
+	std.Io.print("io "); std.Io.put_n(7); std.Io.put_c(' '); std.Io.put_f(0.5); std.Io.nl();	// io 7 0.500000
+
 	// text: char* strings, one character per word
 	let buf[32];
 	std.Text.itoa(0 - 42, buf); rt.put_s(buf); rt.put_c(10);				// -42
diff --git a/src/lib/std.zc b/src/lib/std.zc
index 745a921..b206888 100644
--- a/src/lib/std.zc
+++ b/src/lib/std.zc
@@ -415,6 +415,84 @@ struct Host {
 	}
 }
 
+// ---- standard input and output ----
+
+// the terminal: printing to the standard output and reading the standard input.
+// called as std.Io.name(args). the writers go through rt.put_c, so a capture
+// (std.capture) sees their text too. the rt names (rt.put_n, rt.put_s and the
+// rest) stay; these are the same operations, grouped with the library.
+// zc has no varargs or overloading, so print takes a string, and numbers have
+// their own writers: std.Io.print("n = "); std.Io.put_n(n); std.Io.nl();
+struct Io {
+	// writes a string.
+	//   s: the text
+	//   returns: 0
+	static int print(char* s) { return rt.put_s(s); }
+	// writes a string and a line break.
+	//   s: the text
+	//   returns: 0
+	static int println(char* s) { rt.put_s(s); return rt.put_c(10); }
+	// writes a line break.
+	//   returns: 0
+	static int nl() { return rt.put_c(10); }
+	// writes one character.
+	//   c: the character
+	//   returns: 0
+	static int put_c(int c) { return rt.put_c(c); }
+	// writes a string, the same as print.
+	//   s: the text
+	//   returns: 0
+	static int put_s(char* s) { return rt.put_s(s); }
+	// writes a number in decimal, with a minus sign when it is negative.
+	//   n: the number
+	//   returns: 0
+	static int put_n(int n) { return rt.put_n(n); }
+	// writes a number in hexadecimal.
+	//   n: the number
+	//   returns: 0
+	static int put_hex(int n) { return rt.put_hex(n); }
+	// writes a packed byte string.
+	//   s: the byte string
+	//   returns: 0
+	static int put_bs(bstr s) { return rt.put_bs(s); }
+	// writes a float with the vm's float printer (six decimals, inf, nan).
+	//   x: the value
+	//   returns: 0
+	static int put_f(float x) { asm { x @ #1220 } return 0; }
+	// reads one character.
+	//   returns: its byte value, -1 at the end of the input
+	static int get_c() { return rt.get_c(); }
+	// true when the input has no more characters.
+	//   returns: 1 at the end of the input, 0 otherwise
+	static int eof() { return rt.eof(); }
+	// reads up to n characters, one to a word, stopping early at the end of the input.
+	//   buf: where they go, room for n words
+	//   n: the most to read
+	//   returns: how many were read, 0 at the end of the input
+	static int read(char* buf, int n) {
+		int i = 0, c;
+		while (i < n) { c = rt.get_c(); if (c < 0 && rt.eof()) break; buf[i] = c; i++; }
+		return i;
+	}
+	// reads one line into buf as a string, without its line break. a line longer
+	// than n - 1 characters is cut short and the rest is left for the next call.
+	//   buf: where the line goes, room for n words, the 0 included
+	//   n: the size of buf in words
+	//   returns: the line's length, or -1 at the end of the input with nothing read
+	static int getline(char* buf, int n) {
+		int i = 0, c;
+		if (n < 1) return -1;
+		while (i < n - 1) {
+			c = rt.get_c();
+			if (c < 0 && rt.eof()) { if (!i) { buf[0] = 0; return -1; } break; }
+			if (c == 10) break;
+			buf[i] = c; i++;
+		}
+		buf[i] = 0;
+		return i;
+	}
+}
+
 // ---- byte strings ----
 
 // the same helpers as Text, for packed byte strings of type bstr (b"..."
diff --git a/src/lsp/server.zc b/src/lsp/server.zc
index 52e5e9a..bc2c967 100644
--- a/src/lsp/server.zc
+++ b/src/lsp/server.zc
@@ -2658,7 +2658,7 @@ char* module_description() {
 	if (hname_is("run")) return "the resident compiler module: compile and evaluate source, inspect tokens and functions, and register syntax or receiver extensions.";
 	if (hname_is("core")) return "the vm host interface: host gates, operand-stack addresses, byte-addressed memory access and program termination.";
 	if (hname_is("lsp")) return "the language server module: document analysis, diagnostics, markdown hovers, completion, navigation and formatting.";
-	if (hname_is("std")) return "the embedded standard library: text and byte strings, numeric helpers, files, buffers, array algorithms and command-line arguments. no file is read and nothing imports it automatically.";
+	if (hname_is("std")) return "the embedded standard library: terminal input and output, text and byte strings, numeric helpers, files, buffers, array algorithms and command-line arguments. no file is read and nothing imports it automatically.";
 	if (hname_is("icon")) return "structured runtime syntax transformations: token templates, balanced captures, expression and block edits, function publication and scalar execution inspection.";
 	return 0;
 }
@@ -2739,7 +2739,7 @@ int hover_instruction(int i) {
 		if (fm_k[t] == 7) break;
 		if (hcursor >= fm_s[t] && hcursor < fm_e[t]) {
 			if (prev >= 0 && fm_is(i, prev, "include") && fm_is(i, t, "std")) {
-				hn = 0; return kw_put("include std;~compiles the embedded standard library here. no file is read and nothing imports it automatically. provides Text, Bytes, Host, Arena, Buf, capture, and command-line helpers.");
+				hn = 0; return kw_put("include std;~compiles the embedded standard library here. no file is read and nothing imports it automatically. provides Io, Text, Bytes, Host, Arena, Buf, capture, and command-line helpers.");
 			}
 			if (!raw || (prev >= 0 && fm_k[prev] == 6 && fm_o[prev] == 8)) return 0;
 			op = -1;
diff --git a/tests/programs/stdio.expected b/tests/programs/stdio.expected
new file mode 100644
index 0000000..4a7fd8a
--- /dev/null
+++ b/tests/programs/stdio.expected
@@ -0,0 +1,8 @@
+hi -42 2.500000
+line
+bytes 0xff s
+8 caught 7
+3:abc
+3:lon
+7 103
+-1 1
diff --git a/tests/programs/stdio.zc b/tests/programs/stdio.zc
new file mode 100644
index 0000000..5a79262
--- /dev/null
+++ b/tests/programs/stdio.zc
@@ -0,0 +1,18 @@
+include rt, std;
+
+// std.Io: the writers, a capture of them, and the line reader over program input.
+fn main() {
+	std.Io.print("hi "); std.Io.put_n(-42); std.Io.put_c(32); std.Io.put_f(2.5); std.Io.nl();
+	std.Io.println("line"); std.Io.put_bs(b"bytes"); std.Io.put_c(32); std.Io.put_hex(255);
+	std.Io.put_c(32); std.Io.put_s("s"); std.Io.nl();
+	let cap = std.capture.start();
+	std.Io.print("caught "); std.Io.put_n(7);
+	std.capture.end(cap);
+	std.Io.put_n(std.Text.len(cap)); std.Io.put_c(32); std.Io.println(cap);
+	char[32] buf; int n = std.Io.getline(buf, 32);
+	std.Io.put_n(n); std.Io.print(":"); std.Io.println(buf);
+	n = std.Io.getline(buf, 4); std.Io.put_n(n); std.Io.print(":"); std.Io.println(buf);
+	n = std.Io.read(buf, 32); std.Io.put_n(n); std.Io.put_c(32); std.Io.put_n(buf[0]); std.Io.nl();
+	n = std.Io.getline(buf, 32); std.Io.put_n(n); std.Io.put_c(32); std.Io.put_n(std.Io.eof()); std.Io.nl();
+	return 0;
+}
diff --git a/tests/test.sh b/tests/test.sh
index 8bf7a9b..7745a66 100755
--- a/tests/test.sh
+++ b/tests/test.sh
@@ -155,6 +155,7 @@ run(){	# $1 = vm command, $2 = label
 	chk "$($vm < tests/programs/use_std.zc)" "42 -7 1" "$l include and the string helpers"
 	chk "$($vm < tests/programs/stdbuf.zc)" "4 1 266 8" "$l stdlib arena and packed byte buffer"
 	chk "$($vm < tests/programs/stdmore.zc)" "$(printf '5 1 0 0 7 copy me 12 -1 0 1 0 1\n9 mixed 123 9 MIXED 123\n11 [padded line]\n42 3 9 10 12 81 9 10 -1 0\n6 1 2 -1 1 0')" "$l stdlib text, byte-string and num helpers"
+	chk "$( (cat tests/programs/stdio.zc; printf '`abc\nlonger\nxyz') | $vm)" "$(cat tests/programs/stdio.expected)" "$l std.Io writers, capture, getline and read"
 	chk "$(ZC_FILE=tests/data/hi.txt $vm < examples/cli.zc)" "6 h" "$l reading a file named by the environment"
 	chk "$(ZC_ARG_TEST=ok $vm < tests/programs/args.zc)" "1 <eval>  <eval> 1 1" "$l argv and envp from the host, argv[0] is <eval> on stdin"
 	chk "$(ZC_ARG_TEST=ok $vm < tests/programs/capture.zc)" "0