folders
Live file listings of watched folders.
-- `~/` also works; `watched` is keyed by the expanded path
local folder = (os.getenv("HOME") or "") .. "/Pictures/Wallpapers"
mantle.folders:watch(folder, { "jpg", "png" })
list {
items = mantle.folders:map(function(folders)
local listing = folders.watched[folder]
return listing and listing.entries or {}
end),
key = function(entry) return entry.path end,
each = function(entry)
return text { content = entry.name }
end,
}
State
mantle.folders:get() returns FoldersState, nil before the first push. A field marked ? may be absent.
mantle.folders payload.
| Field | Type | Description |
|---|---|---|
watched | table<string, Folder> | One entry per "watch", keyed by its absolute path (~/ expanded) minus trailing slashes; nil until watched. |
FileEntry
| Field | Type | Description |
|---|---|---|
modified | integer | Modification time in Unix seconds; 0 when unavailable. |
name | string | File name, e.g. "sunrise.jpg". |
path | string | Absolute path. |
size | integer | Size in bytes; a symlink reports its target’s size. |
Folder
| Field | Type | Description |
|---|---|---|
entries | FileEntry[] | Files (and symlinks to files) directly inside, minus dotfiles, filtered by extension and sorted case-insensitively by name. Relisted 200 ms after the last change. |
error? | string | Why listing failed, e.g. "No such file or directory (os error 2)"; nil on success. A missing or deleted folder keeps this error until it appears, then lists on its own. |
ready | boolean | false until the first listing lands, then true even when empty or failed. |
Actions
Call each as mantle.folders:<action>(arguments...); ? marks an argument you may omit.
| Action | Arguments | Description |
|---|---|---|
watch | path: string, extensions?: string[] | Keeps watched[path] listing a folder, absolute or ~/ under $HOME. extensions match case-insensitively, dot optional; omitted means every file. |
unwatch | path: string | Stops watching path (absolute or ~/) and removes it from watched. |
Backend
One inotify watch per folder, on the folder only: subfolders are neither listed nor watched. A new
generation drops every watch, so call watch at top level and each evaluation asks again; repeating
a watch with the same extensions only re-pushes the listing.
A missing folder is watched through its nearest existing ancestor: ready is true with error
set until the folder appears, then it lists with error cleared. A watched folder that is deleted
or moved away does the same, and lists again when it comes back.
Gotchas
| Trap | Fix |
|---|---|
watched["~/Pictures"] is nil after watch("~/Pictures") | watched is keyed by the expanded absolute path: watched[os.getenv("HOME") .. "/Pictures"] |
watched[path] is nil after a watch | The key drops trailing slashes: watch("/walls/") lands at watched["/walls"] |
error is set but the folder exists | It is set while the folder is missing and clears on the next listing, up to 200 ms after the folder appears |
See also: file.read to read a file’s contents.