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.
| Limit | Value |
|---|---|
| A file read or written | 16 MB |
| A file one copy takes, streamed rather than held | 4 GB |
| A folder listing | 10,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` wholewrite 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 nowrmdirs 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.
executeruns the program and waits up to 60 seconds. It gives{ exitStatus, stdout, stderr, truncated }.launchAndDetachstarts a program and lets it go.launchstarts a program the script keeps, and gives a handle.stdinis text of at most 1 MB written to the program's input.workingDirectoryis a folder.envadds 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)| Limit | Value |
|---|---|
execute waits | 60 seconds |
| Programs a run starts | 64 |
| Programs alive at once | 16 |
| Unread output kept | 4 MB for each stream |
| Words in a command | 256, each up to 4,096 letters |
| Environment variables a call adds | 64 |
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.