refactor(stdlib): consolidate System.* onto Os.*, retire duplicated members
All checks were successful
docs / build-and-deploy (push) Successful in 2s

`System.*` and the newer `Os.*` (added in #21) both covered the environment
around the game, with four members (`arg`, `arg_count`, `env`, `exit`) lowering
byte-for-byte identically and the standard streams overlapping in concern. That
is a user-facing ambiguity (`System.env` vs `Os.env` are indistinguishable) and
a drift hazard (two copy-pasted codegen paths).

Make `Os.*` the single canonical environment/process namespace and retire the
overlapping `System.*` members:

- Remove `System.{arg, arg_count, env, exit, stdout, stderr}` from the namespace
  dispatch (selfhost/emit_expr.ludic). Use `Os.arg`/`Os.arg_count`/`Os.env`/
  `Os.exit` and `Os.stdout_write`/`Os.stderr_write` instead.
- `System.*` now covers only its unique low-level surface: the raw file handles
  (`file_open/read/write/seek/tell/close`), `read_char`, and `run`.
- The bare `arg`/`exit`/`getenv`/`file_stdout`/`file_stderr` intrinsics stay —
  they are the primitive layer the self-hosted compiler itself uses; only the
  redundant *namespaced* sugar is gone.
- Docs: drop the six retired `docs/language/system/*` pages, retune the section
  blurb, update inventory.json and the LSP signature table.
- Secondary finding from the issue: cross-link `Text.upper`/`Text.lower`
  (ASCII-only) to `Unicode.upper`/`Unicode.lower` (full Unicode case mapping).

Reseeded; C-free bootstrap fixpoint holds. All suites green (56 test / 29
selfhost / 29 test-tools); docs cover every implemented feature (291 ns-methods).

Closes #40

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-08-30 22:54:28 +03:00
parent dd4f5a26ad
commit ac1e8d157d
14 changed files with 3762 additions and 3920 deletions

View file

@ -4,4 +4,4 @@ title: System
order: 6
---
Process and OS access — command-line arguments, environment, exit code, running a shell command, and raw file I/O. Outside the deterministic simulation.
Low-level file and process access — raw file handles, reading a character, and running a shell command. Outside the deterministic simulation. For command-line arguments, environment variables, the exit code, and the standard streams, use the <code>Os</code> namespace.

View file

@ -1,14 +0,0 @@
---
id: system-arg
name: System.arg
category: system
kind: namespace-method
tokens: System.arg
sig: System.arg(i) -> string
tip: A command-line argument by index.
order: 0
ns: System
member: arg
---
Returns the <code>i</code>-th command-line argument; index 0 is the program path.

View file

@ -1,14 +0,0 @@
---
id: system-arg_count
name: System.arg_count
category: system
kind: namespace-method
tokens: System.arg_count
sig: System.arg_count() -> int
tip: The number of command-line arguments.
order: 1
ns: System
member: arg_count
---
Returns how many command-line arguments were passed, including the program path.

View file

@ -1,14 +0,0 @@
---
id: system-env
name: System.env
category: system
kind: namespace-method
tokens: System.env
sig: System.env(name) -> string
tip: Read an environment variable.
order: 4
ns: System
member: env
---
Returns the value of environment variable <code>name</code>, or a null string if it is unset.

View file

@ -1,14 +0,0 @@
---
id: system-exit
name: System.exit
category: system
kind: namespace-method
tokens: System.exit
sig: System.exit(code) -> void
tip: End the process with a status code.
order: 2
ns: System
member: exit
---
Terminates the program immediately, returning <code>code</code> to the shell.

View file

@ -1,14 +0,0 @@
---
id: system-stderr
name: System.stderr
category: system
kind: namespace-method
tokens: System.stderr
sig: System.stderr() -> pointer
tip: The standard error handle.
order: 13
ns: System
member: stderr
---
Returns the standard-error file handle, for <code>System.file_write</code>.

View file

@ -1,14 +0,0 @@
---
id: system-stdout
name: System.stdout
category: system
kind: namespace-method
tokens: System.stdout
sig: System.stdout() -> pointer
tip: The standard output handle.
order: 12
ns: System
member: stdout
---
Returns the standard-output file handle, for <code>System.file_write</code>.

View file

@ -11,7 +11,7 @@ ns: Text
member: lower
---
Returns a fresh string with every ASCII letter <code>A</code>-<code>Z</code> turned to lowercase; other bytes pass through unchanged. Pair it with <code>Text.equals</code> for case-insensitive matching by lowercasing both sides. Only ASCII is transformed.
Returns a fresh string with every ASCII letter <code>A</code>-<code>Z</code> turned to lowercase; other bytes pass through unchanged. Pair it with <code>Text.equals</code> for case-insensitive matching by lowercasing both sides. This is ASCII-only — accented and non-Latin letters are left as-is; for full Unicode case mapping use <code>Unicode.lower</code>.
```ludic
program Demo {

View file

@ -11,7 +11,7 @@ ns: Text
member: upper
---
Returns a fresh string with every ASCII letter <code>a</code>-<code>z</code> turned to uppercase; other bytes pass through unchanged. The input is left untouched. Use it to normalize input before comparing, or to shout a label. Only ASCII is transformed.
Returns a fresh string with every ASCII letter <code>a</code>-<code>z</code> turned to uppercase; other bytes pass through unchanged. The input is left untouched. Use it to normalize input before comparing, or to shout a label. This is ASCII-only — accented and non-Latin letters are left as-is; for full Unicode case mapping use <code>Unicode.upper</code>.
```ludic
program Demo {

View file

@ -356,11 +356,11 @@ function emit_ns_call(ns: pointer, meth: pointer, e: Node) -> Val {
if (meth == "local_id") { bare = "local_id" }
}
if (ns == "System") {
if (meth == "arg") { bare = "arg" }
if (meth == "arg_count") { bare = "arg_count" }
if (meth == "exit") { bare = "exit" }
# System.* is the low-level file/process surface only. The environment slice
# (arg/arg_count/env/exit) and the standard streams (stdout/stderr) were
# duplicated by the canonical Os.* namespace and have been retired — see
# Os.arg/arg_count/env/exit and Os.stdout_write/stderr_write (issue #40).
if (meth == "run") { bare = "run" }
if (meth == "env") { bare = "getenv" }
if (meth == "read_char") { bare = "read_char" }
if (meth == "file_open") { bare = "file_open" }
if (meth == "file_read") { bare = "file_read" }
@ -368,8 +368,6 @@ function emit_ns_call(ns: pointer, meth: pointer, e: Node) -> Val {
if (meth == "file_seek") { bare = "file_seek" }
if (meth == "file_tell") { bare = "file_tell" }
if (meth == "file_close") { bare = "file_close" }
if (meth == "stdout") { bare = "file_stdout" }
if (meth == "stderr") { bare = "file_stderr" }
}
if (ns == "Save") {
if (meth == "write") { bare = "save" }

File diff suppressed because it is too large Load diff

View file

@ -14,6 +14,6 @@ program T {
let w = Memory.words(4)
w[0] = 12345
print(w[0]) # 12345
print(System.arg_count()) # 1
print(Os.arg_count()) # 1
}
}

View file

@ -263,20 +263,14 @@
"kw-enum"
],
"system": [
"system-arg",
"system-arg_count",
"system-exit",
"system-run",
"system-env",
"system-read_char",
"system-file_open",
"system-file_read",
"system-file_write",
"system-file_seek",
"system-file_tell",
"system-file_close",
"system-stdout",
"system-stderr"
"system-file_close"
],
"text": [
"text-length",

View file

@ -1377,11 +1377,7 @@ program LudicLsp {
if (meth == "local_id") { return "Network.local_id() -> int" }
}
if (ns == "System") {
if (meth == "arg") { return "System.arg(i) -> string" }
if (meth == "arg_count") { return "System.arg_count() -> int" }
if (meth == "exit") { return "System.exit(code)" }
if (meth == "run") { return "System.run(command) -> int" }
if (meth == "env") { return "System.env(name) -> string" }
if (meth == "read_char") { return "System.read_char() -> int" }
if (meth == "file_open") { return "System.file_open(path, mode) -> pointer" }
if (meth == "file_read") { return "System.file_read(file, buf, n) -> int" }
@ -1389,8 +1385,6 @@ program LudicLsp {
if (meth == "file_seek") { return "System.file_seek(file, offset, whence) -> int" }
if (meth == "file_tell") { return "System.file_tell(file) -> int" }
if (meth == "file_close") { return "System.file_close(file)" }
if (meth == "stdout") { return "System.stdout() -> pointer" }
if (meth == "stderr") { return "System.stderr() -> pointer" }
}
if (ns == "Save") {
if (meth == "write") { return "Save.write()" }