notes

4.5 KB

1. file(String path) {
2. return __native("fs.file", path)
3. }
5. readFile(String path) {
6. return __native("fs.read_file", path)
7. }
9. \* Read a whole file as Bytes (ticket #88): every byte as it is on disk,
10. nothing decoded — the way back for what writeFile stored from a Bytes. *\
11. readBytes(String path) {
12. return toBytes(__native("fs.read_file", path))
13. }
15. listDir(String path) {
16. return __native("fs.list_dir", path)
17. }
19. \* Does this path exist? (mission 077) The one call in hl:fs that cannot fail:
20. it answers true/false, never an Error event — probing a path is a question,
21. not an operation. Relative paths resolve against the SCRIPT's directory like
22. every other hl:fs path. *\
23. exists(String path) {
24. return __native("fs.exists", path)
25. }
27. \* Watch a directory tree for changes (the dev-reload bell): an ordinary
28. event-loop source — register it and every save arrives as an event.
30. __native("eventloop.register", watch("."), "changed")
31. on changed(ev) { … ev.name … }
33. `exclude` (2026-08-30) names directories the descent must NOT enter — a
34. path string, or a list of them. Omit it and the whole tree is watched, as
35. it always was. The paths are compared RESOLVED (relative ones against the
36. script's directory, like every hl:fs path) and normalised, so `./sessions`,
37. `sessions` and `var/../sessions` are the same directory, and a sibling
38. named `sessions-old` is NOT inside `sessions`.
40. watch(".", "./sessions")
41. watch(".", ["./sessions", "/var/cache/app"])
43. A program that writes to a directory it also watches needs this: without
44. it the only escape was that the walker skips dot-directories (which it
45. still does — `.git` is the reason), i.e. renaming the directory. *\
46. watch(String path, exclude) {
47. return __native("fs.watch", path, exclude)
48. }
50. \* Write a whole file, ATOMICALLY (2026-08-28). Everything above this line
51. reads; hl:fs could report a file's `chmod` and never set one, which is why
52. nothing in this language could persist anything until now.
54. The write goes to a sibling temp file, is fsynced, and is then renamed over
55. the target — so a concurrent reader sees the whole OLD file or the whole NEW
56. one, never a half of either. That matters more than it sounds: the first
57. caller is the session store, and a truncated session file does not read as
58. an error, it reads as a logged-out user.
60. `mode` defaults to 0600 — a file this program wrote, for this program. Pass
61. one to loosen it; nothing here consults the umask on your behalf.
63. `contents` is a String or a Bytes (ticket #88): a Bytes is written raw,
64. byte for byte — an uploaded image stays an image. *\
65. writeFile(
66. String path
67. contents \\ a String or a Bytes
68. Number mode
69. ) {
70. if (hlTypeName(contents) == 'Bytes') {
71. return __native("fs.write_file_hex", path, contents.hex(), mode)
72. }
73. return __native("fs.write_file", path, contents, mode)
74. }
76. \* Append to a file — the log's shape, not the session store's (2026-09-27, a
77. creator ask after routger's two). Opened O_APPEND, never truncated: the file
78. is created (at `mode`, default 0600, same as writeFile) if it is not there
79. yet, and every call after that lands its bytes after whatever is already on
80. disk. `writeFile`'s atomicity is a RENAME over a temp file — there is no
81. "old" or "new" whole file to swap here, since an append MUTATES the one
82. that is already there — but O_APPEND carries its own, narrower guarantee:
83. the kernel positions a single write() at the CURRENT end of file and
84. performs it as one operation, so two processes each appending one line
85. never interleave their bytes mid-line, and a reader never sees a torn
86. append. That is what "a single write of a line lands whole" buys — call it
87. once per line (or per record) you want that guarantee for.
89. `contents` is a String or a Bytes (ticket #88), same as writeFile: a Bytes
90. is appended raw, byte for byte. *\
91. appendFile(
92. String path
93. contents \\ a String or a Bytes
94. Number mode
95. ) {
96. if (hlTypeName(contents) == 'Bytes') {
97. return __native("fs.append_file_hex", path, contents.hex(), mode)
98. }
99. return __native("fs.append_file", path, contents, mode)
100. }
102. \* Make a directory and every missing parent. Already-there is SUCCESS: the
103. caller wants the directory to exist, not to be the one who created it.
104. `mode` defaults to 0700. *\
105. mkDir(String path, Number mode) {
106. return __native("fs.mk_dir", path, mode)
107. }
109. \* Delete a path. IDEMPOTENT: true when the path is gone on return, and a path
110. that was already gone counts. A sweep must not fail because something else
111. deleted the file first. *\
112. remove(String path) {
113. return __native("fs.remove", path)
114. }