components

3.3 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. \* Make a directory and every missing parent. Already-there is SUCCESS: the
77. caller wants the directory to exist, not to be the one who created it.
78. `mode` defaults to 0700. *\
79. mkDir(String path, Number mode) {
80. return __native("fs.mk_dir", path, mode)
81. }
83. \* Delete a path. IDEMPOTENT: true when the path is gone on return, and a path
84. that was already gone counts. A sweep must not fail because something else
85. deleted the file first. *\
86. remove(String path) {
87. return __native("fs.remove", path)
88. }