ona/source/coral/files.cpp

export module coral.files;

import coral;

export namespace coral {
	/**
	 * [reader] that has a known range of data and may attempt to traverse it freely.
	 */
	struct file_reader : public reader {
		/**
		 * Attempts to seek to the position in the file defined by `offset`, returning the literal absolute position
		 * that was actually sought to or a [io_error] if the operation failed for whatever reason.
		 */
		virtual expected<u64, io_error> seek(u64 offset) = 0;

		/**
		 * Attempts to get the current cursor position in the file, returning the literal absolute position of it or a
		 * [io_error] if the operation failed for whatever reason.
		 */
		virtual expected<u64, io_error> tell() = 0;
	};

	/**
	 * Enumerates a file tree recursively, returning the absolute path of each file within.
	 */
	struct file_walker : public enumerator<expected<slice<char const>, io_error>> {
		virtual ~file_walker() {}

		/**
		 * See [enumerator::enumerate].
		 */
		virtual bool enumerate() = 0;

		/**
		 * Returns the last-enumerated path as a sequence of `char`s or an [io_error] if the last enumeration did not
		 * successfully complete.
		 */
		virtual expected<slice<char const>, io_error> value() = 0;
	};

	/**
	 * [writer] that has a known range of data and may attempt to traverse it freely.
	 */
	struct file_writer : public writer {
		/**
		 * Attempts to seek to the position in the file defined by `offset`, returning the literal absolute position
		 * that was actually sought to or a [io_error] if the operation failed for whatever reason.
		 */
		virtual expected<u64, io_error> seek(u64 offset) = 0;

		/**
		 * Attempts to get the current cursor position in the file, returning the literal absolute position of it or a
		 * [io_error] if the operation failed for whatever reason.
		 */
		virtual expected<u64, io_error> tell() = 0;
	};

	/**
	 * Platform-generalized file system interface.
	 */
	struct file_system {
		virtual ~file_system() {};

		/**
		 * Attempts to read the file in `target_path`, calling `then` if it was successfully opened for reading and
		 * passing the [file_reader] context along.
		 *
		 * See [file_reader] for more information on how to read from the file.
		 */
		virtual void read_file(slice<char const> const & target_path, closure<void(file_reader &)> const & then) {}

		/**
		 * Attempts to walk the file tree from `target_path`, calling `then` if it was successfully opened for walking
		 * and passing the [file_walker] context along.
		 *
		 * See [file_walker] for more information on how to traverse the file tree.
		 */
		virtual void walk_files(slice<char const> const & target_path, closure<void(file_walker &)> const & then) {}

		/**
		 * Attempts to write a file in the file system located at `target_path`, calling `then` if it was successfully
		 * created and / or opened for writing and passing the [file_writer] context along.
		 *
		 * See [file_writer] for more information on how to write to the file.
		 *
		 * *Note*: Any file already existing at `target_path` will be overwritten to create a new file for writing.
		 */
		virtual void write_file(slice<char const> const & target_path, closure<void(file_writer &)> const & then) {}
	};
}