notesy::files

A folder of the plugin's own, for what it keeps that isn't a setting or a small value (those go in the store): caches, downloads, exports it builds up. It's all of the disk a script can reach. Needs no permission.

rustuse notesy::{files, json, log};

pub fn ready() {
    files::write("cache/today.json", json::text(#{ count: 3 }));
    files::append("history.txt", "opened\n");
    if let Some(text) = files::read("cache/today.json") {
        let today = json::parse(text)?;
        log::info(`${today.count} from the cache`);
    }
    for entry in files::list("") {
        log::info(`${entry.name}: ${entry.size} bytes`);
    }
}
Function What it does
files::read(path) A file's text, Some(text), or None when there's no such file. A file that isn't text is an error: read it with read_bytes.
files::read_bytes(path) A file's bytes, Some(bytes), or None.
files::write(path, data) Writes the file (text or bytes), replacing what was there, and makes the folders it's in.
files::append(path, data) Adds to the file's end, making it when it isn't there.
files::list(folder) What's in a folder ("" for the top), folders first: #{ name, folder, size }.
files::exists(path) Whether there's a file or folder there.
files::remove(path) Deletes a file, or a folder and everything in it.
files::rename(from, to) Moves a file or folder; to mustn't be there already.
files::open(path) Opens one of its files in a tab of its own, in front, for the user to read and edit; what they write is saved back to it. Only a note's kind of file (.md, .markdown, .txt), and it takes ui. Such a tab isn't a note in the vault: no history, tags, search or note events.
files::show(path) The same, only to read: a guide, help, its own changes. Nothing typed, no command and no other plugin changes it, it has no formatting bar, and it's never saved. One already open to be written in is saved first, what was written in it kept. It takes ui.
files::usage() What its files take up: #{ bytes, entries, max_bytes, max_entries }.

#Picked files

With files.pick, a plugin can read what the user picks for it, from anywhere on this computer: notesy's own picker opens each time it asks, and it reads what was picked and nothing else (an importer reading an export).

Function What it does
files::pick(options) Opens the system's picker. options is its title, or #{ title, folder, filters }: folder: true to pick a folder, filters the extensions a file may have (["enex", "md"]). #{ id, name, folder } for what was picked, or None when nothing was.
files::list_picked(id) Every file in a picked folder and the folders in it, as paths in it (Notes/Plan.md), at most 20,000, never through a link; [""] for a picked file.
files::read_picked(id, path) A file in what was picked ("" for a picked file itself) as text, Some(text), or None when there's no such file. Text that isn't UTF-8 is made so. At most 64 MB.
files::read_picked_bytes(id, path) The same, as bytes.

A path with .. in it, or one that leads out of what was picked through a link, is an error. What was picked is forgotten when the script stops.

#Saving a file

With files.save, a plugin can save a file where the user picks.

Function What it does
files::save(options, data) Opens the system's save dialog, then saves data (text or bytes) where the user picks. options is its title, or #{ title, name, filters }: name what the file's called to start with ("Plan.docx"). The name it was saved as, or None when the user didn't save it.

#Zips

Function What it does
files::zip(entries) A zip of [#{ name, data }, …] (data text or bytes, name a path in it), as bytes: what a .docx, an .epub or an .odt is. Entries are stored, not compressed, in the order given. Needs no permission.

#Paths

Relative to the plugin's folder, with / between parts: cache/today.json. A path that could mean anything else is an error, not read another way: one starting with /, with .. or ., a \, a :, a control character, a name ending in a dot or a space, or one Windows keeps for a device (con, nul, com1). At most 16 folders deep.

Nothing in the folder may be a link: a path that goes through one is an error, and list leaves them out. A script can't make one.

#Room

At most 100 MB and 10,000 files and folders together, and 20 MB for one file. A write that would go past that is an error, and nothing is written.

#Where it is

plugin-data/<plugin id>/files in notesy's config folder, beside its store. Removing the plugin with its data deletes it.

Every page