handle14 methods, 1 field
A directory capability. Obtained from datumhue.args.dirs[name], datumhue.package:dir(), an open_button pick, or dir:subdir(rel). Relative paths must stay inside the directory — .., absolute paths, and symlinks that escape the root are all rejected.
Package:dir, datumhue.argsdatumhue.app.spawn, UiElement:open_button, UiElement:save_buttonThe examples on this page start from:
local dir = datumhue.args.dirs.notes| Field | Type | Access | Description |
|---|---|---|---|
name | string | read-only | The user-facing alias for this directory, never a host path. |
Dir:list() -> ListFetchDirect-child names, sorted ascending.
dir:write("b.txt", datumhue.bytes("2")):ready()
dir:write("a.txt", datumhue.bytes("1")):ready()
local names = dir:list():ready().value
print(table.concat(names, ", ")) --> a.txt, b.txtIn the guide: Open, pick and save files
Dir:read(rel: string) -> BytesReturn a file-backed Bytes handle for the file at rel under the directory, at once; the file is read when a decoder method runs, or when the handle is awaited.
dir:write("scores.json", datumhue.bytes.json({ best = 42 })):ready()
-- Nothing is read until a decoder runs.
local scores = dir:read("scores.json"):json()
print(scores.best) --> 42In the guide: Load a table Ask with SQL Chart the answer
Dir:stat(rel: string) -> StatMetadata for rel; a missing rel fails the operation.
dir:write("log.txt", datumhue.bytes("hello")):ready()
local info = dir:stat("log.txt"):ready()
print(info.kind, info.size) --> file 5In the guide: Open, pick and save files
Dir:exists(rel: string) -> BoolFetchWhether rel exists. Only unexpected failures fail the operation.
Dir:create_file(rel: string) -> OpCreate an empty file at rel. Requires rw mode. An already-existing file fails the operation.
Dir:mkdir(rel: string) -> OpCreate a directory at rel. Requires rw mode.
Dir:remove(rel: string) -> OpRemove a file or empty directory at rel. Requires rw mode.
Overwrite rel with bytes. Requires rw mode. A string is not accepted; wrap it with datumhue.bytes first. The write starts immediately; :ready() observes completion or failure.
-- Wrap text in bytes; a plain string is not accepted.
dir:write("hello.txt", datumhue.bytes("Hello")):ready()
dir:write("save.json", datumhue.bytes.json({ level = 3 })):ready()
print(dir:read("hello.txt"):text()) --> HelloIn the guide: Open, pick and save files
Dir:mode() -> app.PreopenModeThe directory's access mode.
In the guide: Open, pick and save files Troubleshooting
Dir:open(rel: string) -> FileMint a new file capability rooted at rel within this directory. Returns immediately; the handle inherits the parent dir's mode.
dir:create_file("log.txt"):ready()
local log = dir:open("log.txt")
log:write(datumhue.bytes("started")):ready()
print(log.name) --> notes/log.txtIn the guide: Open, pick and save files Write a book
Dir:subdir(rel: string) -> DirMint a narrowed directory capability rooted at rel inside this dir. The returned handle sees only files under its own root.
In the guide: Open, pick and save files
Dir:require(rel: string) -> anyLoad the Lua module at exactly rel under the directory and run it once; repeat calls with the same rel hand back the same value. Returns the module's first return value, or true if it returned nothing. A compiled chunk loads only from the Lua files of a sealed package; anywhere else it raises.
dir:write("util.lua", datumhue.bytes("return { answer = 42 }")):ready()
local util = dir:require("util.lua")
print(util.answer) --> 42
-- A second require hands back the same value.
print(dir:require("util.lua") == util) --> trueIn the guide: Modules and dependencies The Lua sandbox
Dir:load_package(rel: string) -> PackageLoad the package at rel under this directory: a regular file loads as a package archive, and a directory as a package folder, which must follow the package layout.
local manifest = [[
name "@me/tools"
version "1.2.0"
api_version "*"
kind "library"
]]
dir:mkdir("tools"):ready()
dir:write("tools/package.kdl", datumhue.bytes(manifest)):ready()
local tools = dir:load_package("tools")
print(tools.name, tools:version()) --> @me/tools 1.2.0In the guide: Launch other apps Packages and identity
Dir:book() -> BookLoad the book rooted at this directory: book.kdl names the title and chapters, each a page file inside the directory. Raises with file:line:col diagnostics on parse or validation errors.
local contents = [[
title "Field notes"
chapter "Birds" file="birds.md"
]]
dir:write("book.kdl", datumhue.bytes(contents)):ready()
dir:write("birds.md", datumhue.bytes("# Birds\n\nA robin.\n")):ready()
local book = dir:book()
print(book.pages, book.title) --> 1 Field notesIn the guide: Write a book
| Value | Description |
|---|---|
"file" | |
"dir" |
Used by: Stat.kind