files
Live file listings of watched folders.
local folder = (os.getenv("HOME") or "") .. "/Pictures/Wallpapers"
mantle.files:watch(folder, { "jpg", "png" })
list {
source = mantle.files:map(function(files)
local listing = files and files.folders[folder]
return listing and listing.entries or {}
end),
key = function(entry) return entry.path end,
itemfn = function(entry)
return text { content = entry.name }
end,
}
State
mantle.files:get() returns FilesState, nil before the first push. A field marked ? may be absent.
mantle.files payload.
| Field | Type | Description |
|---|---|---|
folders | table<string, Folder> | One entry per "watch", keyed by its path 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. |
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 is not watched for reappearing. |
ready | boolean | false until the first listing lands, then true even when empty or failed. |
Actions
Call each as mantle.files:<action>(arguments...); ? marks an argument you may omit.
| Action | Arguments | Description |
|---|---|---|
watch | path: string, extensions?: string[] | Keeps folders[path] listing an absolute folder. extensions match case-insensitively, dot optional; omitted means every file. |
unwatch | path: string | Stops watching path and removes it from folders. |
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.
Gotchas
| Trap | Fix |
|---|---|
watch("~/Pictures") does nothing | Only absolute paths pass; ~ is not expanded. Build the path from os.getenv("HOME") |
folders[path] is nil after a watch | The key drops trailing slashes: watch("/walls/") lands at folders["/walls"] |
A folder created after watch never lists | A missing folder records error and stays unwatched. unwatch, then watch again once it exists |
See also: process.run to read a file’s contents.