Skip to content

Files, folders and programs

buhayin.file, buhayin.dir, buhayin.process and the limits on them.

A script reaches files, folders and programs only through buhayin.file, buhayin.dir, buhayin.process and buhayin.system. They do what your own account can do, so a script someone sent you is as trusted as a program you run by hand. Read it first.

A relative path starts in the run's folder, which is the folder holding the scene file, or a temporary folder for a scene with no file yet. buhayin.dir.cd moves it.

A script that came with a scene, and not from you, gets no files, folders or programs at all. Every call here throws "This script has no files or programs."

Checks on every path

A path must not be empty, must not hold a null letter, must be at most 1,024 letters, must not contain .. and must not pass through a link that leads nowhere. Only plain files are opened.

LimitValue
A file read or written16 MB
A file one copy takes, streamed rather than held4 GB
A folder listing10,000 names

Files

buhayin.file

await buhayin.file.read(path)             // the whole file as text
await buhayin.file.write(path, text)      // replaces the file; gives the bytes written
await buhayin.file.writeLine(path, text)  // appends text and a newline; makes the file if needed
await buhayin.file.exists(path)           // true for a plain file
await buhayin.file.size(path)             // bytes; throws if there is no file
await buhayin.file.remove(path)           // throws if there is no file
await buhayin.file.copy(from, to)         // streams the file, replacing what is at `to` whole

write replaces the file whole or leaves it as it was. A copy goes to a file beside to first, which is then renamed over it.

const path = "notes.txt"
await buhayin.file.writeLine(path, "Checked " + (await buhayin.scene()).name)
print(await buhayin.file.read(path))

Folders

buhayin.dir

await buhayin.dir.entryList(path, filter?)  // names, in natural order; filter uses * and ?
await buhayin.dir.exists(path)
await buhayin.dir.mkdir(path)
await buhayin.dir.mkdirs(path)              // makes the folders on the way too
await buhayin.dir.rmdir(path)               // the folder must be empty
await buhayin.dir.rmdirs(path)              // the folder and everything in it
await buhayin.dir.rename(from, to)          // throws if something is at `to` already
await buhayin.dir.absPath(path)             // the full path
await buhayin.dir.cd(path)                  // moves the run's folder; gives the new one
await buhayin.dir.cdUp()
await buhayin.dir.path()                    // the run's folder now

rmdirs refuses three things: the drive's root, your home folder, and any folder the run's folder is in now or was in when the run began.

const pictures = await buhayin.dir.entryList("pictures", "*.png")
print(pictures.length + " PNG files")

buhayin.system.getenv(name)

await buhayin.system.getenv(name)

The text of an environment variable, or an empty string when it is not set.

Programs

buhayin.process

await buhayin.process.execute(command, { stdin?, workingDirectory?, env? })
await buhayin.process.launchAndDetach(command, options?)
await buhayin.process.launch(command, options?)

command is a line of text or a list of the program and its arguments. No shell is used. A line is split into words at spaces, and double quotes hold spaces inside a word. A program with a path in its name is taken from the working directory. A bare name is looked for on your computer's path.

  • execute runs the program and waits up to 60 seconds. It gives { exitStatus, stdout, stderr, truncated }.
  • launchAndDetach starts a program and lets it go.
  • launch starts a program the script keeps, and gives a handle.
  • stdin is text of at most 1 MB written to the program's input. workingDirectory is a folder. env adds environment variables as { name: value }.

The handle from launch holds:

handle.pid
await handle.isAlive()
await handle.exitStatus()
await handle.readStdout()      // what is unread
await handle.readStderr()
await handle.writeToStdin(text)
await handle.closeStdin()
await handle.terminate()
await handle.kill()
const result = await buhayin.process.execute(["ls", "-l"], { workingDirectory: "." })
print(result.stdout)
LimitValue
execute waits60 seconds
Programs a run starts64
Programs alive at once16
Unread output kept4 MB for each stream
Words in a command256, each up to 4,096 letters
Environment variables a call adds64

Each program leads a process group of its own, so stopping it stops what it started. Programs end with the run. Stop and a timeout stop them too. A script cannot stop a program it did not start. The time a script spends waiting in execute does not count against its ten seconds.