Scripts: File and Folder read files in the script's own folder

Scripts get the File and Folder classes as built-ins of the script
engine. A script run from a file can test whether files exist, read
their properties, list folders with getFiles (a mask or a function),
and open files to read them with read, readln, readch, seek and tell.

- Reads stay inside the script's folder and, when automation read
  roots are set, inside them too. A script given as text reads no
  files. Network and device paths, and paths outside the folder by
  their names, are refused before anything is looked up. Links and
  junctions that lead out are refused, and getFiles leaves them out.
- The encoding comes from the byte order mark, then the encoding the
  script set, then UTF-8 when the bytes are valid, then CP1252.
- Limits: 8 MiB a file, 32 MiB a run, 256 files open at once, 2,048
  getFiles entries and 65,536 names looked at, and paths of at most
  32,767 characters.
- Writing, the file dialogs and execute are not available yet: they
  return false or null and set error.

The report's hostCallCounts gains fileCalls and fileExecutes.
Docs: docs/mcp.md, docs/target-app-parity.md.
This commit is contained in:
dotCooCoo
2026-11-11 07:46:33 -08:00
parent f242b0752f
commit b7a6196994
15 changed files with 2489 additions and 5 deletions
File diff suppressed because one or more lines are too long
+127
View File
@@ -430,6 +430,133 @@ impl ScriptScope {
}
Ok((real, bytes))
}
/// The first granted folder, as people read it (`None` for a script given as text).
pub(crate) fn folder(&self) -> Option<PathBuf> {
self.roots.first().map(|r| crate::cmd::findfiles::plain(r.clone()))
}
/// Does the absolute path `path` name a granted folder or a place inside one, by its names
/// alone, without regard to case? A path that does not is refused before the file system is
/// asked anything about it.
fn names_inside(&self, path: &Path) -> bool {
let lower = |c: Component| c.as_os_str().to_string_lossy().to_lowercase();
path.is_absolute()
&& self.roots.iter().any(|r| {
let root = crate::cmd::findfiles::plain(r.clone());
let mut names = path.components();
root.components().all(|c| names.next().is_some_and(|n| lower(n) == lower(c)))
})
}
/// The real path of the file or folder at `path`, which must be absolute: refused as
/// [`ScriptScope::read`] refuses a path, and also when its names alone place it outside every
/// granted folder, in which case the file system is not asked about it.
pub(crate) fn locate(&self, path: &Path) -> Result<PathBuf, ScriptRead> {
if self.roots.is_empty() || Self::refused_by_name(path) || !self.names_inside(path) {
return Err(ScriptRead::Refused);
}
probed();
if check_read(&path.to_string_lossy()).is_err() {
return Err(ScriptRead::Refused);
}
let real = match std::fs::canonicalize(path) {
Ok(real) => real,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
return Err(if std::fs::symlink_metadata(path).is_ok() { ScriptRead::Refused } else { ScriptRead::Missing });
}
Err(e) => return Err(ScriptRead::Failed(e.to_string())),
};
if !self.roots.iter().any(|r| inside(&real, r)) {
return Err(ScriptRead::Refused);
}
Ok(real)
}
/// What the file or folder at `path` is, located as [`ScriptScope::locate`] locates it.
pub(crate) fn stat(&self, path: &Path) -> Result<ScriptEntry, ScriptRead> {
let real = self.locate(path)?;
let meta = std::fs::metadata(&real).map_err(|e| ScriptRead::Failed(e.to_string()))?;
let link = std::fs::symlink_metadata(path).is_ok_and(|m| m.file_type().is_symlink());
#[cfg(windows)]
let hidden = std::os::windows::fs::MetadataExt::file_attributes(&meta) & 2 != 0;
#[cfg(not(windows))]
let hidden = real.file_name().is_some_and(|n| n.to_string_lossy().starts_with('.'));
Ok(ScriptEntry {
dir: meta.is_dir(),
file: meta.is_file(),
len: meta.len(),
created: meta.created().ok(),
modified: meta.modified().ok(),
hidden,
readonly: meta.permissions().readonly(),
link,
})
}
/// The names in the folder at `path` that `keep` keeps, with whether each is a folder, in the
/// order of their names. A name whose links lead out of every granted folder, or out of the
/// automation read roots in force, is left out. More
/// than `max` names kept, or more than [`MAX_LISTED`] names looked at, is
/// [`ScriptRead::TooLarge`].
pub(crate) fn list(&self, path: &Path, max: usize, keep: impl Fn(&str) -> bool) -> Result<Vec<(String, bool)>, ScriptRead> {
let real = self.locate(path)?;
let entries = std::fs::read_dir(&real).map_err(|e| ScriptRead::Failed(e.to_string()))?;
let mut out = Vec::new();
for (n, entry) in entries.enumerate() {
if n >= MAX_LISTED {
return Err(ScriptRead::TooLarge);
}
let Ok(entry) = entry else { continue };
let name = entry.file_name().to_string_lossy().into_owned();
if !keep(&name) {
continue;
}
let Ok(target) = std::fs::canonicalize(entry.path()) else { continue };
if !self.roots.iter().any(|r| inside(&target, r)) || check_read(&entry.path().to_string_lossy()).is_err() {
continue;
}
if out.len() >= max {
return Err(ScriptRead::TooLarge);
}
out.push((name, target.is_dir()));
}
out.sort();
Ok(out)
}
}
/// The most names [`ScriptScope::list`] looks at in one folder.
pub(crate) const MAX_LISTED: usize = 65_536;
/// A file or folder as [`ScriptScope::stat`] gives it.
#[derive(Clone, Debug)]
pub(crate) struct ScriptEntry {
pub dir: bool,
/// A regular file.
pub file: bool,
pub len: u64,
pub created: Option<std::time::SystemTime>,
pub modified: Option<std::time::SystemTime>,
pub hidden: bool,
pub readonly: bool,
/// The path itself is a symbolic link.
pub link: bool,
}
thread_local! {
/// How many paths [`ScriptScope::locate`] has asked the file system about on this thread.
static PROBES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}
fn probed() {
PROBES.with(|p| p.set(p.get().saturating_add(1)));
}
/// How many paths [`ScriptScope::locate`] has asked the file system about on this thread.
#[cfg(test)]
pub(crate) fn script_probes() -> usize {
PROBES.with(std::cell::Cell::get)
}
#[cfg(test)]
File diff suppressed because it is too large Load Diff
+5
View File
@@ -251,6 +251,11 @@ impl Files {
self.include_path.join(";")
}
/// The folders the run's own files are read from.
pub(crate) fn scope(&self) -> &ScriptScope {
&self.scope
}
/// The script's own text, `text`, with its preprocessor lines read.
pub(crate) fn expand_script(&mut self, text: &str) -> Result<Expanded, Failure> {
self.bytes = self.bytes.saturating_add(text.len());
+14 -1
View File
@@ -35,6 +35,8 @@
//!
//! `alert`, `confirm` and `prompt` open dialogs ([`dialogs`]): in the app the run waits for the
//! person's answer, and a run with nobody to ask takes its answers from `script.run`'s `answers`.
//!
//! `File` and `Folder` read files inside the script's own folder ([`files`]).
pub mod console;
pub mod dialogs;
@@ -56,6 +58,7 @@ use crate::{
Clipboard, DocState, DrawMode, EngineError, Journal, NodeId, PaintDefaults, Result, Session, cmd, command_specs, guard, waits_for_tool_edit,
};
pub mod files;
pub mod folder;
/// The most bytes of source a run takes, as a file or as `source`.
@@ -492,6 +495,8 @@ struct Host {
dialogs: dialogs::Dialogs,
/// The files the run reads: its includes and `$.evalFile`'s.
files: RefCell<include::Files>,
/// What `File` and `Folder` have open and have read.
disk: RefCell<files::Disk>,
/// Where the lines of the script's expanded source came from.
script_map: RefCell<include::SourceMap>,
/// The same for each source `$.evalFile` gave, in order.
@@ -511,6 +516,10 @@ struct Counts {
command_list_reads: Cell<u64>,
vc_log: Cell<u64>,
console_writes: Cell<u64>,
/// Calls of `File` and `Folder` that reach the host ([`files`]).
file_calls: Cell<u64>,
/// `execute` calls, which open nothing.
file_executes: Cell<u64>,
}
impl Counts {
@@ -521,6 +530,8 @@ impl Counts {
"commandListReads": self.command_list_reads.get(),
"vcLog": self.vc_log.get(),
"consoleWrites": self.console_writes.get(),
"fileCalls": self.file_calls.get(),
"fileExecutes": self.file_executes.get(),
})
}
}
@@ -1082,7 +1093,7 @@ fn kind_id(kind: &RunErrorKind) -> &'static str {
/// `message`, with what to do about a failure that comes from a script written for another program.
fn explained(kind: &RunErrorKind, message: &str) -> String {
const HOST_OBJECTS: &[&str] = &["app", "File", "Folder", "Window", "BridgeTalk", "activeDocument", "documents"];
const HOST_OBJECTS: &[&str] = &["app", "Window", "BridgeTalk", "activeDocument", "documents"];
let names_host_object =
message.strip_prefix("ReferenceError: ").is_some_and(|m| HOST_OBJECTS.iter().any(|o| m.split_whitespace().next() == Some(o)));
if *kind == RunErrorKind::Thrown && names_host_object {
@@ -1311,6 +1322,7 @@ impl Session {
commands: RefCell::default(),
run_nanos: Cell::new(0),
dialogs: dialogs::Dialogs::new(self.script_frames, &realm, request.answers),
disk: RefCell::new(files::Disk::new(files.scope())),
files: RefCell::new(files),
script_map: RefCell::default(),
eval_maps: RefCell::default(),
@@ -1330,6 +1342,7 @@ impl Session {
.define_host_object("vc", vc_object(&host, args))
.and_then(|()| realm.define_host_object("$", dollar_object(&host)))
.and_then(|()| dialogs::install(&mut realm, &host))
.and_then(|()| files::install(&mut realm, &host))
.and_then(|()| realm.start(&expanded.source))
.map_err(|e| located(&host, realm.error_source(), realm.error_mark(), &e))
}
+1
View File
@@ -154,6 +154,7 @@ mod script_console;
mod script_dialogs;
mod script_folder;
mod script_include;
mod script_io;
mod script_run;
mod scripts;
mod select_ids_first;
+4 -1
View File
@@ -137,7 +137,10 @@ fn the_result_and_the_report_agree_and_count_each_kind_of_host_call() {
try { vc.run('no.such', {}); } catch (e) {} var d = vc.document; var c = vc.commands; vc.log({a: 1}); vc.log('two\\nlines'); $.writeln('w');";
let r = run(&mut s, source).unwrap();
assert_eq!(&r, s.script_report().unwrap());
assert_eq!(r["hostCallCounts"], json!({"vcRun": 3, "documentReads": 1, "commandListReads": 1, "vcLog": 2, "consoleWrites": 1}));
assert_eq!(
r["hostCallCounts"],
json!({"vcRun": 3, "documentReads": 1, "commandListReads": 1, "vcLog": 2, "consoleWrites": 1, "fileCalls": 0, "fileExecutes": 0})
);
assert_eq!(r["timingAvailable"], true);
assert!(r["runTimeMs"].is_u64());
let slow = r["slowestCommands"].as_array().unwrap();
+398
View File
@@ -0,0 +1,398 @@
//! `File` and `Folder` in a script: their classes and names, reading inside the script's own folder,
//! the paths refused before anything is looked up, the read limits, and the parts that write, which
//! are not available.
use std::path::{Path, PathBuf};
use serde_json::{Value, json};
use crate::file_access::{AutomationRoots, confine, script_probes};
use crate::*;
const DENIED: &str = "Script file access denied";
/// A fresh folder for test `name`, with a `main` folder inside it for the script.
fn folder(name: &str) -> PathBuf {
let base = std::env::temp_dir().join(format!("vc-script-io-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&base);
std::fs::create_dir_all(base.join("main")).unwrap();
base
}
fn write(path: &Path, bytes: &[u8]) {
if let Some(dir) = path.parent() {
std::fs::create_dir_all(dir).unwrap();
}
std::fs::write(path, bytes).unwrap();
}
/// Runs `main/main.jsx` in `base`, with the text `text`.
fn run(base: &Path, text: &str) -> Value {
let main = base.join("main/main.jsx");
write(&main, text.as_bytes());
Session::new().execute("script.run", &json!({"path": main.to_string_lossy()})).unwrap()
}
/// The values the run of `text` logged.
fn logged(base: &Path, text: &str) -> Value {
run(base, text)["log"].clone()
}
#[test]
fn file_constructor_identity_and_folder_path() {
let base = folder("identity");
write(&base.join("main/data.txt"), b"x");
std::fs::create_dir_all(base.join("main/sub")).unwrap();
let log = logged(
&base,
"var a = new File('data.txt'), b = new File('data.txt');\n\
vc.log([a === b, a instanceof File, a instanceof Folder, File('sub') instanceof Folder, new File('sub') instanceof File,\n\
Folder('data.txt') instanceof File, new Folder('data.txt') instanceof Folder, File('nope') instanceof File,\n\
a.parent instanceof Folder, a.name, a.parent.fsName === Folder.current.fsName, String(a) === a.absoluteURI,\n\
a.exists, new File('nope').exists, a.length, a.created instanceof Date, Folder('sub').exists, new File().exists]);",
);
assert_eq!(log, json!([[false, true, false, true, true, true, true, true, true, "data.txt", true, true, true, false, 1, true, true, false]]));
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn file_names_are_uri_encoded_and_current_relative() {
let base = folder("names");
std::fs::create_dir_all(base.join("main/sub")).unwrap();
let log = logged(
&base,
"var f = new File('caf%C3%A9 x.txt');\n\
var sep = File.fs === 'Windows' ? '\\\\' : '/';\n\
vc.log([f.name, f.displayName, f.relativeURI, f.fsName === Folder.current.fsName + sep + 'caf\\u00e9 x.txt',\n\
File.encode('\\u00e9 /'), File.decode('%C3%A9'), new File('sub/../sub/./y.txt').relativeURI,\n\
new File('~/z').fsName === new Folder('~').fsName + sep + 'z', new File('a/b').path === new Folder('a').absoluteURI]);\n\
Folder.current = new Folder('sub');\n\
vc.log([new File('w').parent.name, new File('w').relativeURI, new File('../w').getRelativeURI(Folder.current.parent)]);\n\
var l = new File('literal%2520name.txt'); Folder.current = new Folder('p%2541');\n\
vc.log([l.displayName, l.name, l.absoluteURI.slice(-20), l.fsName === new File(l).fsName, Folder.current.displayName, new File('x').parent.displayName]);",
);
assert_eq!(
log,
json!([
["caf%C3%A9%20x.txt", "caf\u{e9} x.txt", "caf%C3%A9%20x.txt", true, "%C3%A9%20%2F", "\u{e9}", "sub/y.txt", true, true],
["sub", "w", "w"],
["literal%20name.txt", "literal%2520name.txt", "literal%2520name.txt", true, "p%41", "p%41"]
])
);
if cfg!(windows) {
let log = logged(&base, "vc.log([new File('/c/a b/x.txt').fsName, new File('C:/a/x.txt').absoluteURI, new File('d:\\\\q').fsName]);");
assert_eq!(log, json!([["C:\\a b\\x.txt", "/c/a/x.txt", "D:\\q"]]));
}
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_without_scope_cannot_probe_home() {
let base = folder("home");
let source = "var f = File('~/.ssh/id_test'); var g = new Folder('~');\n\
vc.log([f instanceof File, f.exists, f.open('r'), f.error, g.getFiles(), g.error, f.modified, f.length]);";
let denied = json!([[true, false, false, "Script file access denied", null, "Script file access denied", null, 0]]);
let before = script_probes();
let r = Session::new().execute("script.run", &json!({"source": source})).unwrap();
assert_eq!(r["log"], denied, "a script given as text reads nothing");
assert_eq!(script_probes(), before, "nothing was looked up");
// A script run from a file is held to its folder.
let before = script_probes();
assert_eq!(logged(&base, source), denied);
assert_eq!(script_probes(), before, "the home folder lies outside the script's folder by its names alone");
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_unc_rejected_before_lookup() {
let base = folder("unc");
let before = script_probes();
let log = logged(
&base,
"var out = [];\n\
var paths = ['\\\\\\\\host\\\\s\\\\x.txt', '//host/s/x.txt', '\\\\\\\\?\\\\C:\\\\x.txt', '\\\\\\\\.\\\\pipe\\\\x'];\n\
for (var i = 0; i < paths.length; i++) { var f = new File(paths[i]); out.push(f.exists, f.open('r'), new Folder(paths[i]).getFiles()); }\n\
vc.log(out);",
);
assert_eq!(log, json!([[false, false, null, false, false, null, false, false, null, false, false, null]]));
assert_eq!(script_probes(), before, "no network or device path was looked up");
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_link_escape_refused() {
let base = folder("links");
write(&base.join("outside/secret.txt"), b"secret");
write(&base.join("main/own.txt"), b"own");
std::fs::create_dir_all(base.join("main/inner")).unwrap();
// A folder link: a symbolic link, or on Windows a junction, which needs no privilege.
let link_folder = |target: &Path, link: &Path| {
#[cfg(unix)]
std::os::unix::fs::symlink(target, link).unwrap();
#[cfg(windows)]
{
let made = std::process::Command::new("cmd").args(["/C", "mklink", "/J"]).arg(link).arg(target).output().unwrap();
assert!(made.status.success(), "mklink /J: {}", String::from_utf8_lossy(&made.stderr));
}
};
link_folder(&base.join("outside"), &base.join("main").join("away"));
link_folder(&base.join("main").join("inner"), &base.join("main").join("near"));
let log = logged(
&base,
"var away = new Folder('away'); var s = new File('away/secret.txt');\n\
vc.log([away.exists, away.getFiles(), away.error, away.resolve(), s.exists, s.open('r'), s.error,\n\
Folder.current.getFiles().map(function (f) { return f.name; }), new Folder('near').alias, new Folder('near').resolve().name]);",
);
assert_eq!(log, json!([[false, null, DENIED, null, false, false, DENIED, ["inner", "main.jsx", "near", "own.txt"], true, "inner"]]));
#[cfg(unix)]
let made = |target: &Path, link: &Path| std::os::unix::fs::symlink(target, link).is_ok();
#[cfg(windows)]
let made = |target: &Path, link: &Path| std::os::windows::fs::symlink_file(target, link).is_ok();
#[cfg(not(any(unix, windows)))]
let made = |_: &Path, _: &Path| false;
// Windows needs Developer Mode or elevation to make a link to a file.
if !made(&base.join("outside/secret.txt"), &base.join("main/leak.txt")) {
eprintln!("skipped: links to files can't be made here");
let _ = std::fs::remove_dir_all(base);
return;
}
assert!(made(&base.join("main/own.txt"), &base.join("main/alias.txt")));
let log = logged(
&base,
"var leak = new File('leak.txt');\n\
vc.log([leak.exists, leak.open('r'), leak.error, leak.resolve(), new File('away/secret.txt').exists, new Folder('away').getFiles(),\n\
Folder.current.getFiles().map(function (f) { return f.name; }), new File('alias.txt').alias, new File('alias.txt').resolve().name]);",
);
assert_eq!(log, json!([[false, false, DENIED, null, false, null, ["alias.txt", "inner", "main.jsx", "near", "own.txt"], true, "own.txt"]]));
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_oversize_refused_before_read() {
let base = folder("oversize");
let big = std::fs::File::create(base.join("main/big.bin")).unwrap();
big.set_len(9 << 20).unwrap();
drop(big);
write(&base.join("main/small.txt"), b"ok");
let r =
run(&base, "var f = new File('big.bin'); var s = new File('small.txt'); vc.log([f.length, f.open('r'), f.error, s.open('r'), s.read()]);");
assert_eq!(r["log"], json!([[9437184, false, "Script file exceeds 8 MiB", true, "ok"]]));
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_files_read_at_most_32_mib_in_a_run() {
let base = folder("total");
write(&base.join("main/seven.bin"), &vec![b'a'; 7 << 20]);
let mut s = Session::new();
let main = base.join("main/main.jsx");
write(&main, b"var f = new File('seven.bin'); for (var i = 0; i < 5; i++) { f.open('r'); vc.log(i); }");
let e = s.execute("script.run", &json!({"path": main.to_string_lossy()}));
assert!(e.is_err(), "the fifth open passes 32 MiB");
let report = s.script_report().unwrap();
assert_eq!(report["log"], json!([0, 1, 2, 3]));
assert!(report["message"].as_str().unwrap().contains("32 MiB"), "{report}");
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_files_have_at_most_256_open() {
let base = folder("open");
write(&base.join("main/empty.txt"), b"");
let log = logged(
&base,
"var all = [], fails = 0, error = '';\n\
for (var i = 0; i < 300; i++) { var f = new File('empty.txt'); if (f.open('r')) all.push(f); else { fails++; error = f.error; } }\n\
var closed = all[0].close(); var again = new File('empty.txt');\n\
vc.log([all.length, fails, error, closed, again.open('r'), all[1].open('r'), new File('empty.txt').open('r')]);",
);
assert_eq!(log, json!([[256, 44, "Script has 256 files open", true, true, true, false]]));
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_folder_getfiles_stays_inside_scope() {
let base = folder("list");
for name in ["a.jsx", "b.txt", "C.JSX"] {
write(&base.join("main").join(name), b"");
}
std::fs::create_dir_all(base.join("main/sub")).unwrap();
write(&base.join("outside.jsx"), b"");
let log = logged(
&base,
"var d = Folder.current; var names = function (l) { var o = []; for (var i = 0; i < l.length; i++) o.push(l[i].name); return o; };\n\
vc.log(names(d.getFiles('*.jsx')));\n\
vc.log(names(d.getFiles(function (f) { return f instanceof Folder; })));\n\
var up = d.parent; vc.log([names(d.getFiles('?.txt')), d.getFiles().length, up.getFiles(), up.error]);\n\
try { d.getFiles(function () { throw new Error('stop'); }); } catch (e) { vc.log(e.message); }\n\
vc.log([new Folder('nope').getFiles(), d.getFiles('*.jsx')[0] instanceof File]);",
);
assert_eq!(log, json!([["C.JSX", "a.jsx", "main.jsx"], ["sub"], [["b.txt"], 5, null, DENIED], "stop", [null, true]]));
let many = base.join("main/many");
for i in 0..=crate::script::files::MAX_ENTRIES {
write(&many.join(format!("{i:04}.txt")), b"");
}
let log = logged(&base, "var m = new Folder('many'); vc.log([m.getFiles(), m.error, m.getFiles('0001.*').length]);");
assert_eq!(log, json!([[null, "Script folder has more than 2,048 entries", 1]]));
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_bom_and_line_read() {
let base = folder("lines");
write(&base.join("main/lines.txt"), b"\xEF\xBB\xBFone\r\ntwo\n\rthree\rfour\nfin");
write(&base.join("main/e.txt"), "\u{e9}t\u{e9}".as_bytes());
let log = logged(
&base,
"var f = new File('lines.txt'); var out = [f.eof, f.open('r'), f.encoding, f.tell()];\n\
var lines = []; while (!f.eof) lines.push(f.readln()); out.push(lines, f.tell());\n\
out.push(f.seek(3), f.read(3), f.seek(-3, 2), f.read(), f.seek(1, 1), f.seek(100), f.seek(-1), f.tell());\n\
f.seek(6); out.push(f.readch(), f.readch(), f.tell(), f.close(), f.read(), f.error, f.eof);\n\
var e = new File('e.txt'); e.open(); out.push(e.read(1), e.tell(), e.read(5), e.tell());\n\
vc.log(out);",
);
assert_eq!(
log,
json!([[
true,
true,
"UTF-8",
3,
["one", "two", "three", "four", "fin"],
27,
true,
"one",
true,
"fin",
false,
false,
false,
27,
"\n",
"t",
9,
true,
"",
"Script file is not open",
true,
"\u{e9}",
2,
"t\u{e9}",
5
]])
);
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_encoding_binary_ascii() {
let base = folder("encodings");
write(&base.join("main/bytes.bin"), &[0xE8, 0x41]);
write(&base.join("main/euro.txt"), &[0x80]);
let log = logged(
&base,
"var b = new File('bytes.bin'); b.encoding = 'BINARY'; b.open('r'); var t = b.read();\n\
var a = new File('bytes.bin'); a.encoding = 'ASCII'; a.open('r');\n\
var out = [t.charCodeAt(0), t.charAt(1), b.encoding, a.read(), a.error, a.tell()];\n\
a.encoding = 'binary'; out.push(a.encoding, a.read().length);\n\
var c = new File('euro.txt'); c.open('r'); out.push(c.encoding, c.read().charCodeAt(0));\n\
var k = new File('bytes.bin'); k.encoding = 'KLINGON'; out.push(k.open('r'), k.error);\n\
out.push(File.isEncodingAvailable('utf-8'), Folder.isEncodingAvailable('BINARY'), File.isEncodingAvailable('KLINGON'));\n\
vc.log(out);\n\
var m = new File('bytes.bin'); m.encoding = 'BINARY'; m.open('r'); m.encoding = 'KLINGON'; vc.log([m.error, m.encoding, m.read().length]);\n\
var r = new File('bytes.bin'); r.open('r'); r.encoding = 'ASCII'; r.close(); vc.log([r.encoding, r.open('r'), r.read(), r.error]);",
);
let undecodable = "Script file cannot be decoded";
assert_eq!(log[0], json!([232, "A", "BINARY", "", undecodable, 0, "BINARY", 2, "CP1252", 0x20AC, false, undecodable, true, true, false]));
assert_eq!(log[1], json!([undecodable, "BINARY", 2]), "a name that is not an encoding leaves the open file's encoding");
assert_eq!(log[2], json!(["ASCII", true, "", undecodable]), "an encoding set while open is kept after close");
let _ = std::fs::remove_dir_all(base);
}
#[test]
fn script_file_writes_dialogs_and_execute_are_not_available() {
let base = folder("writes");
write(&base.join("main/keep.txt"), b"keep");
let r = run(
&base,
"var f = new File('keep.txt'); var n = new File('new.txt');\n\
var out = [n.open('w'), n.error, f.open('a'), f.open('e'), f.open('x'), f.error, f.write('x'), f.remove(), f.copy('c.txt'), f.rename('r.txt')];\n\
out.push(new Folder('made').create(), f.openDlg(), f.error, File.openDialog(), Folder.selectDialog(), f.execute(), f.error);\n\
f.hidden = true; out.push(f.error, f.hidden); f.error = ''; out.push(f.error);\n\
vc.log(out);",
);
assert_eq!(
r["log"],
json!([[
false,
"Script file writing is not available",
false,
false,
false,
"Script file open mode must be r, w, e or a",
false,
false,
false,
false,
false,
null,
"Script file dialogs are not available",
null,
null,
false,
"Script files cannot be opened in another application",
"Script file writing is not available",
false,
""
]])
);
assert_eq!(r["hostCallCounts"]["fileExecutes"], 1);
assert!(r["hostCallCounts"]["fileCalls"].as_u64().unwrap() > 0);
assert_eq!(std::fs::read(base.join("main/keep.txt")).unwrap(), b"keep");
assert!(!base.join("main/new.txt").exists() && !base.join("main/made").exists() && !base.join("main/c.txt").exists());
let _ = std::fs::remove_dir_all(base);
}
/// A run with automation roots in force reads inside its folder and the read roots, and a run given
/// as text reads nothing even where the roots allow it.
#[test]
fn script_files_read_inside_the_automation_read_roots() {
let base = folder("roots");
write(&base.join("main/data.txt"), b"data");
let source = "var f = new File('data.txt'); vc.log([f.exists, f.open('r'), f.error, f.read()]);";
let roots = AutomationRoots::new(&[&base.join("main")], &[]).unwrap();
assert_eq!(confine(roots.as_ref(), || logged(&base, source)), json!([[true, true, "", "data"]]));
let text = format!("var f = new File({:?}); vc.log([f.exists, f.error]);", base.join("main/data.txt").to_string_lossy());
let r = confine(roots.as_ref(), || Session::new().execute("script.run", &json!({"source": text})).unwrap());
assert_eq!(r["log"], json!([[false, "Script file access denied"]]));
let _ = std::fs::remove_dir_all(base);
}
/// A path longer than 32,767 characters is refused before it is split into names.
#[test]
fn script_file_path_length_is_bounded() {
let base = folder("longpath");
let log = logged(
&base,
"var s = 'a/'; while (s.length < 40000) s += s;\n\
var out = []; try { new File(s); } catch (e) { out.push(e.name, e.message); }\n\
try { new Folder('x').getRelativeURI(s); } catch (e) { out.push(e.name); }\n\
out.push(new File(s.slice(0, 30000)).exists); vc.log(out);",
);
assert_eq!(log, json!([["RangeError", "Script file path exceeds 32,767 characters", "RangeError", false]]));
let _ = std::fs::remove_dir_all(base);
}
/// An error `File` or `Folder` throws is reported at the script's line that called it.
#[test]
fn script_file_errors_are_at_the_calling_line() {
let base = folder("errors");
let mut s = Session::new();
let main = base.join("main/main.jsx");
write(&main, b"\n\n\nnew File('x').read(-1);");
assert!(s.execute("script.run", &json!({"path": main.to_string_lossy()})).is_err());
let report = s.script_report().unwrap();
assert!(report["message"].as_str().unwrap().contains("RangeError: File.read: the count must be a finite number"), "{report}");
assert_eq!(report["line"].as_u64(), Some(4), "{report}");
let _ = std::fs::remove_dir_all(base);
}
+864
View File
@@ -0,0 +1,864 @@
//! `File` and `Folder`, the classes the help pages
//! <https://extendscript.docsforadobe.dev/file-system-access/file-object/> and
//! <https://extendscript.docsforadobe.dev/file-system-access/folder-object/> describe, as built-ins
//! whose file system work a host does ([`crate::Realm::define_file_classes`]).
//!
//! The constructors build their objects with and without `new`: `new File(path)` is always a
//! `File` and `new Folder(path)` always a `Folder`, while `File(path)` gives a `Folder` when the
//! host's `stat` says the path is a folder, and `Folder(path)` a `File` when it is a file. Two
//! objects for one path are different objects. An object keeps its path in the host's platform
//! form, its `error` text, the id of the file it has open (or -1), the encoding set before `open`
//! and its line feed, in properties that are not enumerable; every name the getters give comes from
//! the host's `parse` of that path. `Folder.current` is kept in the realm and starts at the host's
//! `current`.
//!
//! A method whose host call fails sets `error` and returns `false`, `null` or an empty string. A
//! count or position that is not a finite number, a negative count and a seek mode other than 0, 1
//! or 2 throw a `RangeError`; a method called on an object that is not a `File` or `Folder` throws
//! a `TypeError`. `getFiles` with a function calls it with each entry and keeps those it returns a
//! true value for; every entry takes fuel.
use crate::HostItem;
use crate::builtins::{arg, constructor, data, method, native, put_at};
use crate::heap::{CONFIGURABLE, Class, HIDDEN, NativeFn, NativeKind, OBJECT_BYTES, ObjId, Object, PROP_BYTES, Prop, key, string_bytes};
use crate::interp::{Abrupt, ErrorType, Interp, JsResult};
use crate::value::Value;
/// The objects of `File` and `Folder`, kept by the realm, and `Folder.current`.
#[derive(Clone, Debug)]
pub(crate) struct Classes {
file_proto: ObjId,
folder_proto: ObjId,
host: ObjId,
current: Value,
}
impl Classes {
/// The objects a collection keeps.
pub(crate) fn objects(&self) -> [ObjId; 3] {
[self.file_proto, self.folder_proto, self.host]
}
}
const PATH: &str = "__vcPath";
const ERROR: &str = "__vcError";
const HANDLE: &str = "__vcHandle";
const ENCODING: &str = "__vcEncoding";
const LINE_FEED: &str = "__vcLineFeed";
/// The locations `Folder` has as properties, each read from the host's `locations` when it is read.
const PLACES: [&str; 10] = ["appData", "appPackage", "commonFiles", "desktop", "myDocuments", "startup", "system", "temp", "trash", "userData"];
fn classes(i: &Interp) -> JsResult<Classes> {
i.files.clone().ok_or_else(|| Abrupt::Internal("File and Folder are not installed".into()))
}
/// Calls the host function `name` with `args`.
fn host(i: &mut Interp, name: &str, args: &[Value]) -> JsResult<Value> {
let c = classes(i)?;
let f = i.get_value(&Value::Object(c.host), &key(name))?;
i.call(&f, &Value::Undefined, args)
}
/// The host's message `name`.
fn message(i: &mut Interp, name: &str) -> JsResult<Value> {
let c = classes(i)?;
let text = i.get_value(&Value::Object(c.host), &key("text"))?;
i.get_value(&text, &key(name))
}
fn field(i: &mut Interp, v: &Value, name: &str) -> JsResult<Value> {
i.get_value(v, &key(name))
}
/// The value of the own data property `name` of `o`, `undefined` when it has none.
fn slot(i: &Interp, o: ObjId, name: &str) -> JsResult<Value> {
Ok(match i.get_own_property(o, &key(name))? {
Some(Prop::Data { value, .. }) => value,
_ => Value::Undefined,
})
}
fn set_slot(i: &mut Interp, o: ObjId, name: &str, value: Value) -> JsResult<()> {
if let Value::String(s) = &value {
i.rooted(std::slice::from_ref(&value), |i| i.reserve_heap(PROP_BYTES + string_bytes(s.len())))?;
}
i.define(o, key(name), Prop::Data { value, flags: HIDDEN })
}
/// The object `this` and its path, or a `TypeError` naming `what` when it is not a `File` or
/// `Folder`.
fn this_path(i: &mut Interp, this: &Value, what: &str) -> JsResult<(ObjId, Value)> {
if let Some(o) = this.as_object()
&& let path @ Value::String(_) = slot(i, o, PATH)?
{
return Ok((o, path));
}
Err(i.type_error(&format!("{what}: the object is not a File or a Folder")))
}
/// The path `x` names, and whether it is already in the platform's form: the path of a `File` or
/// `Folder`, or `String(x)`, which may hold URI escapes.
fn path_text(i: &mut Interp, x: &Value) -> JsResult<(Value, bool)> {
if let Some(o) = x.as_object()
&& let path @ Value::String(_) = slot(i, o, PATH)?
{
return Ok((path, true));
}
let s = i.to_str(x)?;
Ok((Value::String(s), false))
}
/// The host's `parse` of the path `x` names, from `Folder.current`.
fn parse(i: &mut Interp, x: &Value) -> JsResult<Value> {
let (text, platform) = path_text(i, x)?;
parse_text(i, text, platform)
}
/// The host's `parse` of `text`, from `Folder.current`; its URI escapes are decoded unless it is
/// already a `platform` path.
fn parse_text(i: &mut Interp, text: Value, platform: bool) -> JsResult<Value> {
let current = classes(i)?.current;
host(i, "parse", &[text, current, Value::Bool(platform)])
}
fn parsed(i: &mut Interp, this: &Value, what: &str, name: &str) -> JsResult<Value> {
let (_, path) = this_path(i, this, what)?;
let p = parse_text(i, path, true)?;
i.rooted(std::slice::from_ref(&p), |i| field(i, &p, name))
}
/// A new object with prototype `proto` for the path `fs`, already in the platform's form.
fn instance(i: &mut Interp, proto: ObjId, fs: Value) -> JsResult<Value> {
let line_feed = host_value(i, "lineFeed")?;
i.rooted(&[fs.clone(), line_feed.clone()], |i| {
i.reserve_heap(OBJECT_BYTES + 5 * PROP_BYTES)?;
let o = i.heap.alloc_object(Object::new(Class::Ordinary, Some(proto)));
i.rooted(&[Value::Object(o)], |i| {
set_slot(i, o, PATH, fs.clone())?;
set_slot(i, o, ERROR, Value::str(""))?;
set_slot(i, o, HANDLE, Value::Number(-1.0))?;
set_slot(i, o, ENCODING, Value::str(""))?;
set_slot(i, o, LINE_FEED, line_feed.clone())?;
Ok(Value::Object(o))
})
})
}
fn host_value(i: &mut Interp, name: &str) -> JsResult<Value> {
let c = classes(i)?;
i.get_value(&Value::Object(c.host), &key(name))
}
/// The host's `stat` of the object's path, or `None` after setting `error` when it failed.
fn stat(i: &mut Interp, this: &Value, what: &str) -> JsResult<Option<Value>> {
let (o, path) = this_path(i, this, what)?;
let r = host(i, "stat", &[path])?;
i.rooted(std::slice::from_ref(&r), |i| {
let error = field(i, &r, "error")?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
return Ok(None);
}
Ok(Some(r.clone()))
})
}
/// The field `name` of the object's `stat`, when it exists, or `missing`.
fn stat_field(i: &mut Interp, this: &Value, what: &str, name: &str, missing: Value) -> JsResult<Value> {
let Some(r) = stat(i, this, what)? else { return Ok(missing) };
i.rooted(std::slice::from_ref(&r), |i| {
if !field(i, &r, "exists")?.truthy() && name != "exists" {
return Ok(missing);
}
field(i, &r, name)
})
}
/// The result of a host read: its `text`, or `failed` after setting `error`.
fn text_result(i: &mut Interp, o: ObjId, r: Value, failed: Value) -> JsResult<Value> {
i.rooted(std::slice::from_ref(&r), |i| {
let error = field(i, &r, "error")?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
return Ok(failed);
}
field(i, &r, "text")
})
}
/// The id of the object's open file, or `None` after setting `error` when it has none.
fn opened(i: &mut Interp, o: ObjId) -> JsResult<Option<Value>> {
let h = slot(i, o, HANDLE)?;
if matches!(h, Value::Number(n) if n >= 0.0) {
return Ok(Some(h));
}
let m = message(i, "notOpen")?;
set_slot(i, o, ERROR, m)?;
Ok(None)
}
fn is_open(i: &Interp, o: ObjId) -> JsResult<Option<Value>> {
let h = slot(i, o, HANDLE)?;
Ok(matches!(h, Value::Number(n) if n >= 0.0).then_some(h))
}
/// Closes the object's open file, if it has one.
fn close_open(i: &mut Interp, o: ObjId) -> JsResult<()> {
if let Some(h) = is_open(i, o)? {
host(i, "close", &[h])?;
}
set_slot(i, o, HANDLE, Value::Number(-1.0))
}
fn date(i: &mut Interp, ms: Value) -> JsResult<Value> {
let Value::Number(t) = ms else { return Ok(Value::Null) };
i.reserve_heap(OBJECT_BYTES)?;
let proto = i.intrinsics.date_proto;
Ok(Value::Object(i.heap.alloc_object(Object::new(Class::Date(t), Some(proto)))))
}
/// A count of characters: `None` for `undefined`, else a whole number 0 or more.
fn count(i: &mut Interp, v: &Value, what: &str) -> JsResult<Option<f64>> {
if matches!(v, Value::Undefined) {
return Ok(None);
}
let n = i.to_number(v)?;
if !n.is_finite() || n < 0.0 {
return Err(i.throw(ErrorType::Range, &format!("{what}: the count must be a finite number, 0 or more")));
}
Ok(Some(n.floor()))
}
// ---- constructors ----
fn file_ctor(i: &mut Interp, _: Value, args: &[Value], construct: bool) -> JsResult<Value> {
make(i, args, construct, true)
}
fn folder_ctor(i: &mut Interp, _: Value, args: &[Value], construct: bool) -> JsResult<Value> {
make(i, args, construct, false)
}
/// `new File(path)`, `File(path)`, `new Folder(path)` or `Folder(path)`.
fn make(i: &mut Interp, args: &[Value], construct: bool, file: bool) -> JsResult<Value> {
let c = classes(i)?;
let (own, other) = if file { (c.file_proto, c.folder_proto) } else { (c.folder_proto, c.file_proto) };
let (path, platform) = match arg(args, 0) {
Value::Undefined if file => (host(i, "tempName", &[])?, true),
Value::Undefined => (c.current.clone(), true),
v => (v, false),
};
let fs = i.rooted(std::slice::from_ref(&path), |i| {
let p = if platform { parse_text(i, path.clone(), true)? } else { parse(i, &path)? };
i.rooted(std::slice::from_ref(&p), |i| field(i, &p, "fs"))
})?;
let proto = if construct {
own
} else {
let st = i.rooted(std::slice::from_ref(&fs), |i| host(i, "stat", std::slice::from_ref(&fs)))?;
let flip = i.rooted(&[fs.clone(), st.clone()], |i| {
let error = field(i, &st, "error")?;
let exists = field(i, &st, "exists")?.truthy();
let dir = field(i, &st, "dir")?.truthy();
Ok(matches!(error, Value::Undefined) && exists && dir == file)
})?;
if flip { other } else { own }
};
instance(i, proto, fs)
}
// ---- both classes ----
fn absolute_uri(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
parsed(i, &this, "absoluteURI", "uri")
}
fn fs_name(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
Ok(this_path(i, &this, "fsName")?.1)
}
fn relative_uri(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (_, path) = this_path(i, &this, "relativeURI")?;
let current = classes(i)?.current;
host(i, "relative", &[path, current])
}
fn name(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
parsed(i, &this, "name", "name")
}
fn display_name(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
parsed(i, &this, "displayName", "display")
}
fn path(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
parsed(i, &this, "path", "path")
}
fn parent(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let up = parsed(i, &this, "parent", "parent")?;
if matches!(up, Value::Null | Value::Undefined) {
return Ok(Value::Null);
}
let proto = classes(i)?.folder_proto;
instance(i, proto, up)
}
fn exists(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
Ok(Value::Bool(stat_field(i, &this, "exists", "exists", Value::Bool(false))?.truthy()))
}
fn created(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let ms = stat_field(i, &this, "created", "created", Value::Null)?;
date(i, ms)
}
fn modified(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let ms = stat_field(i, &this, "modified", "modified", Value::Null)?;
date(i, ms)
}
fn alias(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let Some(r) = stat(i, &this, "alias")? else { return Ok(Value::Bool(false)) };
let v = i.rooted(std::slice::from_ref(&r), |i| field(i, &r, "alias"))?;
Ok(Value::Bool(v.truthy()))
}
fn get_error(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "error")?;
slot(i, o, ERROR)
}
fn set_error(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "error")?;
let v = match arg(args, 0) {
Value::Undefined | Value::Null => Value::str(""),
v => Value::String(i.to_str(&v)?),
};
set_slot(i, o, ERROR, v)?;
Ok(Value::Undefined)
}
fn get_relative_uri(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (_, path) = this_path(i, &this, "getRelativeURI")?;
let base = match arg(args, 0) {
Value::Undefined => classes(i)?.current,
b => {
let p = i.rooted(std::slice::from_ref(&path), |i| parse(i, &b))?;
i.rooted(std::slice::from_ref(&p), |i| field(i, &p, "fs"))?
}
};
host(i, "relative", &[path, base])
}
fn change_path(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "changePath")?;
close_open(i, o)?;
let p = parse(i, &arg(args, 0))?;
let fs = i.rooted(std::slice::from_ref(&p), |i| field(i, &p, "fs"))?;
set_slot(i, o, PATH, fs)?;
Ok(Value::Bool(true))
}
fn resolve(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, path) = this_path(i, &this, "resolve")?;
let r = host(i, "resolve", &[path])?;
let (error, fs, dir) = i.rooted(std::slice::from_ref(&r), |i| Ok((field(i, &r, "error")?, field(i, &r, "fs")?, field(i, &r, "dir")?)))?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
return Ok(Value::Null);
}
if !matches!(fs, Value::String(_)) {
return Ok(Value::Null);
}
let c = classes(i)?;
instance(i, if dir.truthy() { c.folder_proto } else { c.file_proto }, fs)
}
fn execute(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, path) = this_path(i, &this, "execute")?;
let r = host(i, "execute", &[path])?;
let error = i.rooted(std::slice::from_ref(&r), |i| field(i, &r, "error"))?;
set_slot(i, o, ERROR, error)?;
Ok(Value::Bool(false))
}
fn to_string(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
parsed(i, &this, "toString", "uri")
}
/// A method that writes: it sets `error` and returns `false`.
fn no_writes(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "write")?;
let m = message(i, "noWrites")?;
set_slot(i, o, ERROR, m)?;
Ok(Value::Bool(false))
}
/// A setter that writes: it sets `error` and changes nothing.
fn no_writes_setter(i: &mut Interp, this: Value, args: &[Value], construct: bool) -> JsResult<Value> {
no_writes(i, this, args, construct)?;
Ok(Value::Undefined)
}
/// A dialog method: it sets `error` and returns `null`.
fn no_picker(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "dialog")?;
let m = message(i, "noPicker")?;
set_slot(i, o, ERROR, m)?;
Ok(Value::Null)
}
fn null_static(_: &mut Interp, _: Value, _: &[Value], _: bool) -> JsResult<Value> {
Ok(Value::Null)
}
fn text_static(i: &mut Interp, name: &str, args: &[Value]) -> JsResult<Value> {
let s = i.to_str(&arg(args, 0))?;
host(i, name, &[Value::String(s)])
}
fn encode(i: &mut Interp, _: Value, args: &[Value], _: bool) -> JsResult<Value> {
text_static(i, "encode", args)
}
fn decode(i: &mut Interp, _: Value, args: &[Value], _: bool) -> JsResult<Value> {
text_static(i, "decode", args)
}
fn encoding_available(i: &mut Interp, _: Value, args: &[Value], _: bool) -> JsResult<Value> {
text_static(i, "encodingAvailable", args)
}
// ---- File ----
fn length(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let Some(r) = stat(i, &this, "length")? else { return Ok(Value::Number(0.0)) };
i.rooted(std::slice::from_ref(&r), |i| {
let regular = field(i, &r, "exists")?.truthy() && field(i, &r, "file")?.truthy();
if regular { field(i, &r, "length") } else { Ok(Value::Number(0.0)) }
})
}
fn hidden(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
Ok(Value::Bool(stat_field(i, &this, "hidden", "hidden", Value::Bool(false))?.truthy()))
}
fn readonly(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
Ok(Value::Bool(stat_field(i, &this, "readonly", "readonly", Value::Bool(false))?.truthy()))
}
fn four_question_marks(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
this_path(i, &this, "creator")?;
Ok(Value::str("????"))
}
fn eof(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "eof")?;
match is_open(i, o)? {
Some(h) => host(i, "eof", &[h]),
None => Ok(Value::Bool(true)),
}
}
fn get_line_feed(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "lineFeed")?;
slot(i, o, LINE_FEED)
}
fn set_line_feed(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "lineFeed")?;
let v = i.to_str(&arg(args, 0))?;
set_slot(i, o, LINE_FEED, Value::String(v))?;
Ok(Value::Undefined)
}
fn get_encoding(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "encoding")?;
if let Some(h) = is_open(i, o)? {
return host(i, "encoding", &[h]);
}
Ok(match slot(i, o, ENCODING)? {
Value::String(s) if s.len() != 0 => Value::String(s),
_ => Value::str("UTF-8"),
})
}
fn set_encoding(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "encoding")?;
let v = Value::String(i.to_str(&arg(args, 0))?);
match is_open(i, o)? {
Some(h) => {
let r = i.rooted(std::slice::from_ref(&v), |i| host(i, "setEncoding", &[h, v.clone()]))?;
let error = i.rooted(std::slice::from_ref(&r), |i| field(i, &r, "error"))?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
} else {
set_slot(i, o, ENCODING, v)?;
}
}
None => set_slot(i, o, ENCODING, v)?,
}
Ok(Value::Undefined)
}
fn open(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, path) = this_path(i, &this, "open")?;
let mode = match arg(args, 0) {
Value::Undefined => "r".to_string(),
m => i.to_str(&m)?.to_rust_string().to_lowercase(),
};
let refusal = match mode.as_str() {
"r" => None,
"w" | "e" | "a" => Some("noWrites"),
_ => Some("badMode"),
};
if let Some(name) = refusal {
let m = message(i, name)?;
set_slot(i, o, ERROR, m)?;
return Ok(Value::Bool(false));
}
close_open(i, o)?;
let encoding = slot(i, o, ENCODING)?;
let r = host(i, "open", &[path, encoding])?;
let (error, id) = i.rooted(std::slice::from_ref(&r), |i| Ok((field(i, &r, "error")?, field(i, &r, "id")?)))?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
return Ok(Value::Bool(false));
}
set_slot(i, o, HANDLE, id)?;
Ok(Value::Bool(true))
}
fn close(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "close")?;
if opened(i, o)?.is_none() {
return Ok(Value::Bool(false));
}
close_open(i, o)?;
Ok(Value::Bool(true))
}
fn read(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "read")?;
let n = count(i, &arg(args, 0), "File.read")?;
let Some(h) = opened(i, o)? else { return Ok(Value::str("")) };
let r = host(i, "read", &[h, n.map_or(Value::Number(-1.0), Value::Number)])?;
text_result(i, o, r, Value::str(""))
}
fn read_line(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "readln")?;
let Some(h) = opened(i, o)? else { return Ok(Value::str("")) };
let r = host(i, "readln", &[h])?;
text_result(i, o, r, Value::str(""))
}
fn read_char(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "readch")?;
let Some(h) = opened(i, o)? else { return Ok(Value::str("")) };
let r = host(i, "readch", &[h])?;
text_result(i, o, r, Value::str(""))
}
fn seek(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "seek")?;
let pos = i.to_number(&arg(args, 0))?;
if !pos.is_finite() {
return Err(i.throw(ErrorType::Range, "File.seek: the position must be a finite number"));
}
let mode = match arg(args, 1) {
Value::Undefined => 0.0,
m => i.to_number(&m)?,
};
if mode != 0.0 && mode != 1.0 && mode != 2.0 {
return Err(i.throw(ErrorType::Range, "File.seek: the mode must be 0, 1 or 2"));
}
let Some(h) = opened(i, o)? else { return Ok(Value::Bool(false)) };
host(i, "seek", &[h, Value::Number(pos.floor()), Value::Number(mode)])
}
fn tell(i: &mut Interp, this: Value, _: &[Value], _: bool) -> JsResult<Value> {
let (o, _) = this_path(i, &this, "tell")?;
let Some(h) = opened(i, o)? else { return Ok(Value::Number(-1.0)) };
host(i, "tell", &[h])
}
// ---- Folder ----
fn get_files(i: &mut Interp, this: Value, args: &[Value], _: bool) -> JsResult<Value> {
let (o, path) = this_path(i, &this, "getFiles")?;
let mask = arg(args, 0);
let call = i.is_callable(&mask);
let pattern = if call || matches!(mask, Value::Undefined) { Value::str("*") } else { Value::String(i.to_str(&mask)?) };
let r = host(i, "list", &[path, pattern])?;
i.rooted(&[r.clone(), mask.clone()], |i| {
let error = field(i, &r, "error")?;
if matches!(error, Value::String(_)) {
set_slot(i, o, ERROR, error)?;
return Ok(Value::Null);
}
let entries = field(i, &r, "entries")?;
let length = field(i, &entries, "length")?;
let n = i.to_number(&length)?;
i.reserve_heap(OBJECT_BYTES)?;
let proto = i.intrinsics.array_proto;
let out = i.heap.alloc_object(Object::new(Class::Array { length: 0, length_writable: true }, Some(proto)));
i.rooted(&[Value::Object(out)], |i| {
let c = classes(i)?;
let mut kept = 0.0;
let mut at = 0.0;
while at < n {
i.use_fuel()?;
let e = i.get_value(&entries, &crate::value::number_to_str(at).flat())?;
let (fs, dir) = i.rooted(std::slice::from_ref(&e), |i| Ok((field(i, &e, "fs")?, field(i, &e, "dir")?.truthy())))?;
let item = instance(i, if dir { c.folder_proto } else { c.file_proto }, fs)?;
let keep = if call {
i.rooted(std::slice::from_ref(&item), |i| i.call(&mask, &Value::Undefined, std::slice::from_ref(&item)))?.truthy()
} else {
true
};
if keep {
put_at(i, out, kept, item)?;
kept += 1.0;
}
at += 1.0;
}
Ok(Value::Object(out))
})
})
}
fn get_current(i: &mut Interp, _: Value, _: &[Value], _: bool) -> JsResult<Value> {
let c = classes(i)?;
instance(i, c.folder_proto, c.current)
}
fn set_current(i: &mut Interp, _: Value, args: &[Value], _: bool) -> JsResult<Value> {
let p = parse(i, &arg(args, 0))?;
let fs = i.rooted(std::slice::from_ref(&p), |i| field(i, &p, "fs"))?;
if let Some(c) = i.files.as_mut() {
c.current = fs;
}
Ok(Value::Undefined)
}
/// `Folder.<place>`: a new `Folder` for the host's location `place`, or `null`.
fn place(i: &mut Interp, place: &str) -> JsResult<Value> {
let all = host(i, "locations", &[])?;
let fs = i.rooted(std::slice::from_ref(&all), |i| field(i, &all, place))?;
if !matches!(fs, Value::String(_)) {
return Ok(Value::Null);
}
let proto = classes(i)?.folder_proto;
instance(i, proto, fs)
}
macro_rules! places {
($($f:ident => $name:literal),* $(,)?) => {
$(fn $f(i: &mut Interp, _: Value, _: &[Value], _: bool) -> JsResult<Value> {
place(i, $name)
})*
/// The getter of each of [`PLACES`], in its order.
const PLACE_GETTERS: [NativeFn; 10] = [$($f),*];
};
}
places!(
app_data => "appData",
app_package => "appPackage",
common_files => "commonFiles",
desktop => "desktop",
my_documents => "myDocuments",
startup => "startup",
system => "system",
temp => "temp",
trash => "trash",
user_data => "userData",
);
// ---- install ----
/// Defines the accessor `name` on `on`, not enumerable, as the help pages' objects have them.
fn accessor(i: &mut Interp, on: ObjId, name: &'static str, get: NativeFn, set: Option<NativeFn>) -> JsResult<()> {
let g = native(i, name, get, 0, NativeKind::Plain, false)?;
i.rooted(&[Value::Object(g)], |i| {
let s = match set {
Some(f) => Some(native(i, name, f, 1, NativeKind::Plain, false)?),
None => None,
};
i.define(on, key(name), Prop::Accessor { get: Some(g), set: s, flags: CONFIGURABLE })
})
}
/// What `File` and `Folder` both have.
fn common(i: &mut Interp, ctor: ObjId, proto: ObjId) -> JsResult<()> {
accessor(i, proto, "absoluteURI", absolute_uri, None)?;
accessor(i, proto, "fullName", absolute_uri, None)?;
accessor(i, proto, "fsName", fs_name, None)?;
accessor(i, proto, "relativeURI", relative_uri, None)?;
accessor(i, proto, "name", name, None)?;
accessor(i, proto, "displayName", display_name, None)?;
accessor(i, proto, "path", path, None)?;
accessor(i, proto, "parent", parent, None)?;
accessor(i, proto, "exists", exists, None)?;
accessor(i, proto, "created", created, None)?;
accessor(i, proto, "modified", modified, None)?;
accessor(i, proto, "alias", alias, None)?;
accessor(i, proto, "error", get_error, Some(set_error))?;
method(i, proto, "toString", to_string, 0)?;
method(i, proto, "getRelativeURI", get_relative_uri, 1)?;
method(i, proto, "changePath", change_path, 1)?;
method(i, proto, "resolve", resolve, 0)?;
method(i, proto, "execute", execute, 0)?;
method(i, proto, "remove", no_writes, 0)?;
method(i, proto, "rename", no_writes, 1)?;
method(i, ctor, "encode", encode, 1)?;
method(i, ctor, "decode", decode, 1)?;
method(i, ctor, "isEncodingAvailable", encoding_available, 1)?;
let system = host_value(i, "system")?;
data(i, ctor, "fs", system, HIDDEN)
}
fn file_members(i: &mut Interp, ctor: ObjId, proto: ObjId) -> JsResult<()> {
accessor(i, proto, "length", length, Some(no_writes_setter))?;
accessor(i, proto, "hidden", hidden, Some(no_writes_setter))?;
accessor(i, proto, "readonly", readonly, Some(no_writes_setter))?;
accessor(i, proto, "creator", four_question_marks, None)?;
accessor(i, proto, "type", four_question_marks, None)?;
accessor(i, proto, "eof", eof, None)?;
accessor(i, proto, "lineFeed", get_line_feed, Some(set_line_feed))?;
accessor(i, proto, "encoding", get_encoding, Some(set_encoding))?;
method(i, proto, "open", open, 1)?;
method(i, proto, "close", close, 0)?;
method(i, proto, "read", read, 1)?;
method(i, proto, "readln", read_line, 0)?;
method(i, proto, "readch", read_char, 0)?;
method(i, proto, "seek", seek, 2)?;
method(i, proto, "tell", tell, 0)?;
method(i, proto, "write", no_writes, 1)?;
method(i, proto, "writeln", no_writes, 1)?;
method(i, proto, "copy", no_writes, 1)?;
method(i, proto, "createAlias", no_writes, 1)?;
method(i, proto, "openDlg", no_picker, 0)?;
method(i, proto, "saveDlg", no_picker, 0)?;
method(i, ctor, "openDialog", null_static, 0)?;
method(i, ctor, "saveDialog", null_static, 0)
}
fn folder_members(i: &mut Interp, ctor: ObjId, proto: ObjId) -> JsResult<()> {
method(i, proto, "getFiles", get_files, 1)?;
method(i, proto, "create", no_writes, 0)?;
method(i, proto, "selectDlg", no_picker, 0)?;
method(i, ctor, "selectDialog", null_static, 0)?;
accessor(i, ctor, "current", get_current, Some(set_current))?;
for (place, get) in PLACES.into_iter().zip(PLACE_GETTERS) {
accessor(i, ctor, place, get, None)?;
}
Ok(())
}
/// Adds `File` and `Folder` to the global object, their work done by the host functions in
/// `items` ([`crate::Realm::define_file_classes`]).
pub(crate) fn install(i: &mut Interp, items: Vec<(String, HostItem)>) -> JsResult<()> {
let host_obj = i.host_object("File", items)?;
let object_proto = i.intrinsics.object_proto;
i.rooted(&[Value::Object(host_obj)], |i| {
i.reserve_heap(2 * OBJECT_BYTES)?;
let file_proto = i.heap.alloc_object(Object::new(Class::Ordinary, Some(object_proto)));
let folder_proto = i.heap.alloc_object(Object::new(Class::Ordinary, Some(object_proto)));
i.files = Some(Classes { file_proto, folder_proto, host: host_obj, current: Value::str("") });
let start = host(i, "current", &[])?;
if let Some(c) = i.files.as_mut() {
c.current = start;
}
let file = native(i, "File", file_ctor, 1, NativeKind::Plain, true)?;
constructor(i, "File", file, file_proto)?;
let folder = native(i, "Folder", folder_ctor, 1, NativeKind::Plain, true)?;
constructor(i, "Folder", folder, folder_proto)?;
common(i, file, file_proto)?;
common(i, folder, folder_proto)?;
file_members(i, file, file_proto)?;
folder_members(i, folder, folder_proto)
})
}
#[cfg(test)]
mod tests {
use std::rc::Rc;
use crate::{Data, HostItem, JsValue, Realm};
/// A host whose paths are `/` and a name, where `/d` is a folder holding `a` and `b` and every
/// other path is missing.
fn realm() -> Realm {
let f = |g: fn(&[Data]) -> Data| HostItem::Function(Rc::new(move |a: Vec<Data>| Ok(g(&a))));
let text = |a: &[Data], i: usize| match a.get(i) {
Some(Data::String(s)) => s.clone(),
_ => String::new(),
};
let obj = |fields: Vec<(&str, Data)>| Data::Object(fields.into_iter().map(|(k, v)| (k.to_string(), v)).collect());
let parse = move |a: &[Data]| {
let t = text(a, 0);
let fs = if t.starts_with('/') { t } else { format!("/{t}") };
let name = fs.trim_start_matches('/').to_string();
obj(vec![
("fs", Data::String(fs.clone())),
("uri", Data::String(fs)),
("name", Data::String(name.clone())),
("display", Data::String(name)),
("path", Data::String("/".into())),
("parent", Data::String("/".into())),
])
};
let messages = ["notOpen", "noWrites", "noPicker", "badMode"].map(|k| (k.to_string(), HostItem::Value(Data::String(k.into()))));
let stat = move |a: Vec<Data>| -> Result<Data, crate::HostError> {
let dir = text(&a, 0) == "/d";
Ok(obj(vec![("exists", Data::Bool(dir)), ("dir", Data::Bool(dir))]))
};
let list = move |_: Vec<Data>| -> Result<Data, crate::HostError> {
let e = |n: &str| obj(vec![("fs", Data::String(format!("/d/{n}"))), ("dir", Data::Bool(false))]);
Ok(obj(vec![("entries", Data::Array(vec![e("a"), e("b")]))]))
};
let mut r = Realm::new();
let items: Vec<(String, HostItem)> = vec![
("text".into(), HostItem::Object(messages.to_vec())),
("system".into(), HostItem::Value(Data::String("Unix".into()))),
("lineFeed".into(), HostItem::Value(Data::String("Unix".into()))),
("current".into(), f(|_| Data::String("/".into()))),
("parse".into(), HostItem::Function(Rc::new(move |a: Vec<Data>| Ok(parse(&a))))),
("stat".into(), HostItem::Function(Rc::new(stat))),
("list".into(), HostItem::Function(Rc::new(list))),
("tempName".into(), f(|_| Data::String("/tmp1".into()))),
("locations".into(), f(|_| Data::Object(vec![]))),
];
r.define_file_classes(items).unwrap();
r
}
#[test]
fn objects_keep_their_classes_through_collections() {
let mut r = realm();
r.run("var kept = new File('x'); var listed = new Folder('d').getFiles(); File = null; Folder = null;").unwrap();
r.collect_garbage();
r.run("var many = []; for (var i = 0; i < 2000; i++) many.push(kept.parent);").unwrap();
r.collect_garbage();
let v = r.run(
"[kept.name, kept.fsName, listed.length, listed[1].name, kept.parent.getFiles(function (f) { return f.name === 'd/a'; }).length].join()",
);
assert_eq!(v.unwrap(), JsValue::String("x,/x,2,d/b,1".into()));
}
#[test]
fn the_constructor_picks_the_class_only_without_new() {
let mut r = realm();
let v = r.run(
"var F = File, D = Folder; [F('d') instanceof D, new F('d') instanceof F, D('x') instanceof D, \
typeof Object.keys(new F('x')).length, Object.keys(new F('x')).length].join()",
);
assert_eq!(v.unwrap(), JsValue::String("true,true,true,number,0".into()));
let e = r.run("File.prototype.read.call({})").unwrap_err();
assert!(e.message.contains("is not a File or a Folder"), "{e:?}");
}
}
+1 -1
View File
@@ -462,7 +462,7 @@ impl Interp {
self.define(global, key(name), Prop::Data { value: Value::Object(o), flags: 0 })
}
fn host_object(&mut self, path: &str, items: Vec<(String, HostItem)>) -> JsResult<ObjId> {
pub(crate) fn host_object(&mut self, path: &str, items: Vec<(String, HostItem)>) -> JsResult<ObjId> {
let o = self.new_object();
let mark = self.temp_roots.len();
self.temp_roots.push(Value::Object(o));
+4
View File
@@ -175,6 +175,8 @@ pub(crate) struct Interp {
pub(crate) held_bytes: usize,
/// Why installing the built-ins failed; a realm with this set runs no script.
pub(crate) install_error: Option<String>,
/// `File` and `Folder`, once a host has added them ([`crate::Realm::define_file_classes`]).
pub(crate) files: Option<crate::file_classes::Classes>,
/// The clock and time zone `Date` reads.
pub(crate) date_host: crate::date_builtins::DateHost,
/// The bytes native code holds outside the heap's cells through [`HeldBytes`].
@@ -395,6 +397,7 @@ impl Interp {
join_stack: Vec::new(),
held_bytes: 0,
install_error: None,
files: None,
date_host: crate::date_builtins::DateHost::default(),
held: Rc::default(),
pause: Rc::default(),
@@ -587,6 +590,7 @@ impl Interp {
}
roots.objects.push(self.global);
roots.objects.extend(self.intrinsics.all());
roots.objects.extend(self.files.iter().flat_map(crate::file_classes::Classes::objects));
roots.envs.push(self.global_env);
self.heap.collect(&roots);
// The collection counts the live total again, so bytes already released are not in it.
+1
View File
@@ -46,6 +46,7 @@ mod chars;
mod compiler;
mod date_builtins;
mod error;
mod file_classes;
mod heap;
mod host;
mod interp;
+14
View File
@@ -398,6 +398,20 @@ impl Realm {
}
}
/// Adds the global constructors `File` and `Folder`, whose file system work the host functions
/// in `items` do: `parse`, `relative`, `tempName`, `stat`, `open`, `close`, `read`, `readln`,
/// `readch`, `seek`, `tell`, `eof`, `encoding`, `setEncoding`, `list`, `resolve`, `execute`,
/// `encode`, `decode`, `encodingAvailable`, `current` and `locations`, with the values `system`
/// and `lineFeed` and the messages `text.notOpen`, `text.noWrites`, `text.noPicker` and
/// `text.badMode`. Each object keeps its path, its `error` text, its open file's id, its
/// encoding and its line feed in properties that are not enumerable.
pub fn define_file_classes(&mut self, items: Vec<(String, crate::HostItem)>) -> Result<(), RunError> {
match crate::file_classes::install(&mut self.interp, items) {
Ok(()) => Ok(()),
Err(e) => self.outcome(Err(e)).map(drop),
}
}
/// Defines the global function `name`, whose arguments arrive converted as `args` says
/// ([`crate::HostItem::Converted`]). Unlike a host object, a script may replace or delete it, as
/// it may a built-in function.
+53 -1
View File
@@ -1661,6 +1661,8 @@ VectorCraft sets these limits itself:
| A dialog's message, title and prompt preset | 16 KiB, 256 bytes and 16 KiB |
| `answers` | 10,000 answers and 1 MiB as JSON |
| `dialogs` in the report | 10,000 dialogs and 1 MiB as JSON |
| Files `File.open` reads | 8 MiB a file, 32 MiB in a run, 256 open at once |
| `Folder.getFiles` | 2,048 entries, 65,536 names looked at |
| Growth before a person is asked | 100,000 objects and 512 MiB of new document data |
In the app, a script past the growth limit stops at a question to continue or to stop and undo. Stop, Escape and
@@ -1673,7 +1675,9 @@ another file than the script) and `fuelLeft`.
- `runTimeMs` is the time the script ran, its commands included. Waits between frames and for a person's answer are
left out. `timingAvailable` is false on the web, where `runTimeMs` is 0.
- `hostCallCounts` is `{vcRun, documentReads, commandListReads, vcLog, consoleWrites}`.
- `hostCallCounts` is `{vcRun, documentReads, commandListReads, vcLog, consoleWrites, fileCalls, fileExecutes}`.
`fileCalls` counts the calls `File` and `Folder` make to the app, and `fileExecutes` the `execute` calls, which open
nothing.
- `slowestCommands` lists at most 5 commands as `{id, calls, totalMs, maxMs}`, the longest in all first, then by id.
- `console` is `{lines, droppedLines, truncatedLines}`: the run's own output, `vc.log` lines and uncaught error, as
text.
@@ -1732,6 +1736,54 @@ empty object are the same.
vectorcraft-cli run --cmd script.run --params '{"source": "if (confirm(\"Add a frame?\")) vc.log(prompt(\"Name\", \"Frame\"));", "answers": [{"kind": "confirm", "value": true}, {"kind": "prompt", "value": "Border"}]}'
```
The help pages https://extendscript.docsforadobe.dev/file-system-access/file-object/ and
https://extendscript.docsforadobe.dev/file-system-access/folder-object/ describe the `File` and `Folder` objects. A
script reads files with them:
- `new File(path)` and `new Folder(path)` name a path without looking it up. A path is a platform path or a URI
path: a relative path is taken from `Folder.current`, which starts at the script's folder, `~` is the home folder,
`%xx` escapes are read as UTF-8, and on Windows `/` and `\` both separate names and `/c/` names drive C. `File(path)`
without `new` gives a `Folder` for an existing folder, and `Folder(path)` gives a `File` for an existing file. Two
objects for the same path are different objects.
- `name`, `displayName`, `fsName`, `absoluteURI`, `fullName`, `relativeURI`, `path`, `parent` and `toString()` come
from the path. `exists`, `length`, `created`, `modified`, `hidden`, `readonly` and `alias` read the file system.
`File.encode`, `File.decode` and `File.isEncodingAvailable` (and the same on `Folder`), `File.fs`, and the folders
`Folder.temp`, `Folder.desktop`, `Folder.myDocuments`, `Folder.userData` and the others are there too.
- `open('r')` opens a file to read, and `read([chars])`, `readln()`, `readch()`, `seek(pos[, mode])`, `tell()`, `eof`
and `close()` read it. `read`, `readln` and `readch` count characters, and `seek` and `tell` count bytes. `readln`
and `readch` take CR, LF, CRLF and LF CR as one line end. `folder.getFiles([mask])` lists a folder, sorted by name;
the mask matches `*` and `?` without regard to case, and a function as the mask keeps the entries it returns true
for.
- A method that fails returns `false`, `null` or an empty string and sets `error`, such as `Script file access
denied`, `Script file does not exist` or `Script file is not open`. A count or a position that is not a finite
number, or a negative count, throws a `RangeError`.
VectorCraft reads files by these rules of its own:
- A script run from a file reads only in that file's folder and the folders below it, as its includes are read, and
a script given as `source` reads no files. When automation read roots are set, as for a run over MCP or the command
line, the files must also be inside them. A path outside, a Windows network path (`\\host\share`) and a device path
(`\\?\`, `\\.\`) are refused before anything is looked up: `exists` is `false`, the dates and `getFiles` give `null`,
and `error` is `Script file access denied`. A path that leads out through a link or a junction is refused too, and
`getFiles` leaves such an entry out.
- `open` reads the whole file. A file larger than 8 MiB is refused from its size before any of it is read, with
`Script file exceeds 8 MiB`, and a run that opens more than 32 MiB in all ends with an error. A run has at most 256
files open at once; another `open` returns `false` with `Script has 256 files open` until one is closed.
- The encoding is the one the file's byte order mark gives (UTF-8, UTF-16LE or UTF-16BE), otherwise the `encoding`
the script set before `open`, otherwise UTF-8 when the bytes are valid UTF-8, otherwise CP1252. `BINARY` reads each
byte as one character. A byte the encoding cannot read, such as one above 127 in `ASCII`, fails the read with
`Script file cannot be decoded` and leaves the position where it was.
- `getFiles` gives at most 2,048 entries and looks at most 65,536 names; past that it gives `null` with `Script folder
has more than 2,048 entries`. A mask that takes more than 16,777,216 steps to match against the names of one
folder gives `null` with `Script folder mask takes too many steps to match`.
- A path longer than 32,767 characters throws a `RangeError` (`Script file path exceeds 32,767 characters`) when a
`File` or `Folder` is made from it.
- Writing is not available yet: `open('w')`, `open('e')`, `open('a')`, `write`, `writeln`, `copy`, `remove`,
`rename`, `create` and `createAlias` return `false` with `Script file writing is not available`, and setting
`length`, `hidden` or `readonly` sets `error` to that message and changes nothing. The file
and folder dialogs return `null`, and `execute` opens nothing and returns `false`. In the web build every lookup
fails with `Script file access is unavailable on the web`.
Window › Script Console shows the session's script lines, oldest first: each run's start, its `$.write` and
`$.writeln` output, its `vc.log` entries, its uncaught error as `name:line:column: message` (or `name: file:line:column: message` when the error is in another
file), its end, and a report of
+1
View File
@@ -734,6 +734,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur
- Scripts: Window › Script Console shows each run's `$.write` and `$.writeln` output, `vc.log` entries, uncaught error with the script's name, line and column, and a report of its time, host calls and slowest commands, keeping at most 2,048 lines and counting the lines it dropped. `script.run`'s report carries the same data, and `script.console`, `script.console.clear` and `ui.copyScriptConsole` read, clear and copy it. `crates/engine/src/tests/script_console.rs`.
- Scripts: an error `$.evalFile` throws for a file it cannot run is reported at that file's line and column only while no `catch` has taken it. Caught and thrown again later, in the script or in another file, it is reported where it was thrown again, and a new error whose message holds its text is reported where that error was thrown. VectorCraft's own rule. `crates/engine/src/tests/script_include.rs`, `crates/js/src/host_tests.rs`.
- Scripts: a run reads its preprocessor lines before any of it runs: `#include` and `//@include` put another file in place of the line, looked for beside the including file, in the `#includepath` folders and in `JSINCLUDE`; `#script` names the run; `#target` and `#strict off` are taken, `#strict on` turns on strict write checks (below), and `#targetengine` and `#engine` are refused. `$.evalFile` runs a file with the same globals and returns its last value, and `$.fileName` and `$.includePath` give the file being run and the include folders. A script run from a file reads these files only in its folder and below, without `..` names or links that lead out, and an error in one is reported at its own file, line and column ([preprocessor directives](https://extendscript.docsforadobe.dev/extendscript-tools-features/preprocessor-directives/), [the `$` object](https://extendscript.docsforadobe.dev/extendscript-tools-features/dollar-object/); `crates/engine/src/tests/script_include.rs`).
- Scripts: `File` and `Folder` ([File object](https://extendscript.docsforadobe.dev/file-system-access/file-object/), [Folder object](https://extendscript.docsforadobe.dev/file-system-access/folder-object/)) name files and folders by platform or URI path, with `name`, `fsName`, `absoluteURI`, `relativeURI`, `parent`, `Folder.current` and `encode`/`decode`, and read them: `exists`, `length`, the dates, `getFiles` with a mask or a function, and `open('r')` with `read`, `readln`, `readch`, `seek`, `tell` and `close`, decoding by byte order mark, `encoding`, UTF-8 or CP1252. VectorCraft's own rules: a script reads only in its own folder and below (and inside the automation read roots when they are set); any other path and a network or device path are refused before anything is looked up, and a link that leads out is refused as well (`false` or `null`, with `error` set); a file is read whole up to 8 MiB and a run reads up to 32 MiB; writing, the file dialogs and `execute` are not available yet. `crates/engine/src/tests/script_io.rs`.
- Scripts: `#strict on` (and `//@strict on`) runs the script with the checks the [`$` object](https://extendscript.docsforadobe.dev/extendscript-tools-features/dollar-object/) help page gives for `$.strict`: an assignment to a read-only property throws a `TypeError`, and so does a new property on an object that takes none. VectorCraft's own rules: a getter-only property counts as read-only, the objects that take no new properties are the non-extensible ones (`Object.preventExtensions`, `seal`, `freeze`, and the frozen `vc` and `$` objects), the last `#strict` line of the script and its includes sets the whole run, a file `$.evalFile` runs keeps its own line's checks for its code, and the rest of ES5 strict mode stays with `'use strict'`. Without the line, runs are unchanged. `crates/engine/src/tests/script_include.rs` (`strict_on_*`, `strict_mode_in_eval_file_is_scoped`), `crates/js/src/interp_tests.rs` (`strict_writes_are_separate_from_es5_strict`).
- Scripts folder: File › Scripts lists the `.js` and `.jsx` files of the `Scripts` folder next to the preferences, each named after its file without the extension, with each subfolder as a submenu, above Check Script… and Other Script… (https://helpx.adobe.com/illustrator/desktop/automate-visualize-data/automate-actions/install-and-run-scripts.html). VectorCraft's own rules: the folder is read again when the window becomes active and when the File menu opens, links are not followed, and one read stops at 2,048 entries, 512 scripts, 128 subfolders, 4 levels or 250 ms. `script.listInstalled` returns the listing. `crates/engine/src/tests/script_folder.rs`, `crates/ui-egui/src/tests/scripts_menu.rs`.
- Open Recent Files under `--automation-read-root`: the control channel's `ui.menu.list` and `file.recentFiles` leave out the recent files outside the read roots, the other rows keep their ids, and `file.openRecentN` for one outside them answers `no such recent file`, as an empty slot does. `crates/ui-egui/src/tests/automation.rs`.