expression.js

/*
Fōrmulæ filesystem package. Module for expression definition & visualization.
Copyright (C) 2015-2026 Laurence R. Ugalde

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
*/

"use strict";

export class FileSystem extends Formulae.ExpressionPackage {};

// A handle to a single file.
//
// In a browser the local filesystem is sandboxed: a page cannot read or write
// arbitrary paths. The only access is through handles the user explicitly grants
// via a picker (the File System Access API, Chromium) or, as a read-only fallback,
// a classic <input type="file"> (other browsers). So this literal stores either:
//   - this.handle : a FileSystemFileHandle (read, and write if it was granted
//                   read-write through "Choose file to save") — the modern path; or
//   - this.file   : a plain File object (read-only) — the fallback path.
// Handles are not text-serializable, so across save/reload only the display name
// survives (this._displayName) and the user must re-pick the file.
FileSystem.File = class extends Expression.Literal {
	getTag()      { return "FileSystem.File"; }
	getName()     { return FileSystem.messages.nameFile; }
	getMnemonic() { return FileSystem.messages.mnemonicFile; }

	getLiteral() {
		return "🗒 " + this.getFileName();
	}

	getFileName() {
		if (this.handle !== undefined) return this.handle.name;
		if (this.file   !== undefined) return this.file.name;
		return this._displayName ?? "";
	}

	// A File (Blob) snapshot to read from, or undefined if this is a stale,
	// reloaded reference whose handle/file was lost.
	async getFile() {
		if (this.handle !== undefined) return await this.handle.getFile();
		return this.file;
	}

	// A writable stream, or null when this file is not writable (a read-only
	// <input> File, an open-picker handle, or a stale reloaded reference).
	async createWritable() {
		if (this.handle !== undefined && this.handle.createWritable !== undefined) {
			return await this.handle.createWritable();
		}
		return null;
	}

	set(name, value) {
		if (name === "Value") {
			// A FileSystemFileHandle has kind === "file"; a plain File does not.
			if (value != null && value.kind === "file") {
				this.handle = value;
				this.file = undefined;
			}
			else {
				this.file = value;
				this.handle = undefined;
			}
			return;
		}

		super.set(name, value);
	}

	get(name) {
		if (name === "Value") {
			return this.handle !== undefined ? this.handle : this.file;
		}

		return super.get(name);
	}

	getSerializationNames() {
		return [ "Value" ];
	}

	async getSerializationStrings() {
		return [ this.getFileName() ];   // session-scoped: only the name survives a save
	}

	setSerializationStrings(strings, promises) {
		this._displayName = strings[0];   // display only; the handle/file is gone on reload
	}

	isLineIterator() { return true; }

	// https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader/read
	async *nextLine() {
		const utf8Decoder = new TextDecoder("utf-8");
		let file = await this.getFile();
		let reader = file.stream().getReader();
		let { value: chunk, done: readerDone } = await reader.read();
		chunk = chunk ? utf8Decoder.decode(chunk, { stream: true }) : "";

		let re = /\r?\n/g;
		let startIndex = 0;

		for (;;) {
			let result = re.exec(chunk);

			if (!result) {
				if (readerDone) break;

				let remainder = chunk.substring(startIndex);
				({ value: chunk, done: readerDone } = await reader.read());
				chunk = remainder + (chunk ? utf8Decoder.decode(chunk, { stream: true }) : "");
				startIndex = re.lastIndex = 0;

				continue;
			}

			yield chunk.substring(startIndex, result.index);
			startIndex = re.lastIndex;
		}

		if (startIndex < chunk.length) {
			// last line didn't end in a newline char
			yield chunk.substring(startIndex);
		}
	}
};

// A handle to a directory, obtained via showDirectoryPicker() (Chromium only).
// Enumerable through its handle's async iterator; see the List reducer.
FileSystem.Directory = class extends Expression.Literal {
	getTag()      { return "FileSystem.Directory"; }
	getName()     { return FileSystem.messages.nameDirectory; }
	getMnemonic() { return FileSystem.messages.mnemonicDirectory; }

	getLiteral() {
		return "📁 " + this.getDirectoryName();
	}

	getDirectoryName() {
		if (this.handle !== undefined) return this.handle.name;
		return this._displayName ?? "";
	}

	set(name, value) {
		if (name === "Value") {
			this.handle = value;   // a FileSystemDirectoryHandle (kind === "directory")
			return;
		}

		super.set(name, value);
	}

	get(name) {
		if (name === "Value") {
			return this.handle;
		}

		return super.get(name);
	}

	getSerializationNames() {
		return [ "Value" ];
	}

	async getSerializationStrings() {
		return [ this.getDirectoryName() ];   // session-scoped: only the name survives a save
	}

	setSerializationStrings(strings, promises) {
		this._displayName = strings[0];
	}
};

FileSystem.setExpressions = function(module) {
	const self = this;

	Formulae.setExpression(module, "FileSystem.File",      FileSystem.File);
	Formulae.setExpression(module, "FileSystem.Directory", FileSystem.Directory);

	// Operations, rendered as functions: ReadText(file), WriteText(file, text),
	// List(directory), Name(file | directory). The actual I/O lives in the reducers;
	// these only need the standard f(args) layout.
	[
		[ "ReadText",  1, 1 ],
		[ "WriteText", 2, 2 ],
		[ "List",      1, 1 ],
		[ "Name",      1, 1 ]
	].forEach(([ tag, min, max ]) => {
		Formulae.setExpression(module, "FileSystem." + tag, {
			clazz:        Expression.Function,
			getTag:       () => "FileSystem." + tag,
			getName:      () => self.messages["name" + tag],
			getMnemonic:  () => self.messages["mnemonic" + tag],
			getChildName: index => self.messages["children" + tag][index],
			min:          min,
			max:          max,
			color:        "#006666"
		});
	});
};