feat(stdlib): add Fs.* / Path.* / Mime.* — filesystem, paths, content types (#10)
All checks were successful
docs / build-and-deploy (push) Successful in 2s

A cohesive filesystem & IO library — the foundation for saves, config, mods, and
asset loading — wrapping the bare file_* builtins into one safe, ergonomic API a
non-expert can use without touching a file descriptor or a byte buffer.

  Path.*  join / dir / base / ext / stem / normalize   (pure lexical string ops)
  Fs.*    exists / is_dir / read_text / write_text / append_text / remove /
          size / mkdir / copy / list
  Mime.*  of (extension table) / sniff (magic bytes: PNG/JPEG/GIF/PDF)

Pure string IR for Path.*; libc (fopen/access/mkdir/rename/opendir…) for Fs.*;
C-free, emitted on demand (g_uses_fsrt). Safety and determinism baked in:
- write_text and copy are atomic (write a temp file, then rename over the target)
  so a crash mid-write never corrupts the previous file;
- mkdir creates parents (mkdir -p);
- list is sorted for a stable, reproducible directory walk;
- fallible calls return values (null / false / -1), never crashes — ready for a
  first-class try/else when the error-handling work lands.

Complements Os.* (#21): Os supplies per-user locations, Fs the operations. v1
targets the native macOS/BSD filesystem with "/" separators; Windows separators,
a sandboxed wasm virtual FS, recursive directory copy, and richer magic-byte
sniffing are documented follow-ups.

- examples/library/fs.ludic: 32 assertions across pure Path ops (incl. normalize
  resolving ./ .. and duplicate slashes), a real create/read/append/copy/list/
  remove cycle under build/, and Mime by-extension + by-magic (GIF signature vs a
  .bin extension). Wired into `x test` (now 56 passed).
- docs: new Path, Fs, and Mime sections + 18 per-symbol pages; inventory updated;
  every fence passes check-docs; site builds via docgen.
- seed regenerated; `x bootstrap-cfree` fixpoint holds.

Closes #10

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Orkun ÇAKILKAYA 2026-08-30 22:43:50 +03:00
parent bad6cd1ac9
commit dd4f5a26ad
30 changed files with 14298 additions and 10448 deletions

View file

@ -0,0 +1,9 @@
---
id: mime
title: Mime
order: 6
---
Content-type detection for assets and downloads: map a filename to its MIME type, or refine the guess by peeking at a file's leading bytes. Useful for deciding how to load a dropped-in mod file, labelling an export, or picking a decoder.
<a href="mime-of"><code>of</code></a> is a pure lookup by extension; <a href="mime-sniff"><code>sniff</code></a> reads the first bytes and recognises a few well-known signatures (PNG, JPEG, GIF, PDF), falling back to the extension when nothing matches. The extension table is deliberately compact and documented; richer magic-byte coverage is a follow-up.

View file

@ -0,0 +1,25 @@
---
id: mime-of
name: Mime.of
category: mime
kind: namespace-method
tokens: Mime.of
sig: Mime.of(path) -> string
tip: MIME type from a file extension.
order: 1
ns: Mime
member: of
---
Returns the MIME type inferred from the file extension (e.g. <code>hero.png</code> → <code>image/png</code>), or <code>application/octet-stream</code> for an unknown extension. A pure lookup — it does not open the file.
Parameters:
- `path` — the path or filename
```ludic
program MimeOf {
entry {
if Mime.of("hero.png") == "image/png" { print(1) }
}
}
```

View file

@ -0,0 +1,26 @@
---
id: mime-sniff
name: Mime.sniff
category: mime
kind: namespace-method
tokens: Mime.sniff
sig: Mime.sniff(path) -> string
tip: MIME type refined by magic bytes.
order: 2
ns: Mime
member: sniff
---
Reads the file's leading bytes and recognises well-known signatures (PNG, JPEG, GIF, PDF), so a mislabelled or extension-less file is still identified. Falls back to <a href="mime-of"><code>Mime.of</code></a> when no signature matches or the file cannot be read.
Parameters:
- `path` — the path to inspect
```ludic
program MimeSniff {
entry {
let kind = Mime.sniff("download.bin")
print(len(kind))
}
}
```