Files
vectorcraft/docs
dotCooCoo 4716646c6b Scripts: File and Folder objects write files inside a script's scope, with per-script grants and pickers
A script's File and Folder objects now open files for writing, appending
and editing, and copy, rename, remove and create files and folders. A
script reads and writes its run's temporary folder (Folder.temp) and its
own data folder (Folder.userData), kept between runs for a script run
from a file and inside Folder.temp for a script given as text. It reads
its own folder, and reaches other places only through File.openDialog,
File.saveDialog, Folder.selectDialog and the objects' openDlg, saveDlg and
selectDlg.

- A file dialog asks first. The person picks the file or folder with
  Choose..., then allows it once or, for a script run from a file, always.
  A kept grant is bound to the script's path, the SHA-256 of its text and
  every source the run evaluated. It is withdrawn when a later run of the
  script evaluates other code, including code an earlier run left in the
  same named engine. It stays on the real path that was granted, so a
  link put in that place later does not carry it elsewhere.
- A dialog's filter is a string of file types or a function that is
  called with each file picked; multiSelect gives an array of the files
  picked, at most 2,048, and the dialog says when more were left out.
- A folder's selectDlg opens the host's folder dialog in that folder,
  also where the host shows file dialogs in line. Enter in the file
  dialog denies, unless it goes to the focused Choose... button.
  script.grants.revoke is refused with the busy error while a script
  runs, as the run keeps the grants it started with.
- The paths a file dialog allows come only from the host's file dialog:
  ui.dialog.set cannot set them. Only the person at the keyboard allows
  access; Allow Once and Always Allow sent by automation are refused. The
  dialog describes the access the run asked for, whatever its fields say.
- No grant reaches the settings folder, also when the script's own folder
  holds it.
- A file left open is not written through a link put in place of its
  folder since it was opened, and Folder.userData is null when the data
  folder or the script's folder in it is a link.
- copy onto another link to the same file (a hard link) leaves the file's
  bytes as they are, after the source's open objects have written what
  they hold. Files are compared by identity (device and inode on Unix,
  volume and file index on Windows).
- Folder.temp and Folder.userData check each folder they make against the
  automation write roots first, and Folder.create() makes nothing when a
  missing folder above the target is outside the places the script may
  write.
- An open file holds at most 8 MiB, a run writes at most 32 MiB and keeps
  at most 256 files open, and the files a run left open are written in
  the order they were opened. Setting length and copying a file count the
  bytes every open object of that file takes, and write checks the joined
  text against the limit while joining it. The report names at most 4,096
  written files and sets writtenMore when there were more.
- Errors a script sees are translated in every complete message catalog.
2026-11-13 05:42:56 -08:00
..
…