ona/source/coral/files.cpp

export module coral.files;

import coral;

export namespace coral {
	/**
	 * Platform-generalized identifier for a resource in a [fs].
	 */
	struct path {
		/**
		 * Maximum path length.
		 */
		static usize const max = u8_max;

		/**
		 * Common path component separator.
		 */
		static char const seperator = '/';

		constexpr path() {
			this->buffer[max] = max;
		}

		template<usize text_size> constexpr path(char const(&text)[text_size]) {
			static_assert(text_size <= max);

			for (usize i = 0; i < text_size; i += 1) this->buffer[i] = text[i];

			this->buffer[max] = max - text_size;
		}

		/**
		 * Returns a weak reference to the [path] as a [slice].
		 */
		constexpr slice<char const> as_slice() const {
			return {this->buffer, this->byte_size()};
		}

		/**
		 * Returns the base pointer of the path name.
		 *
		 * *Note*: the returned buffer pointer is guaranteed to end with a zero terminator.
		 */
		char const * begin() const {
			return reinterpret_cast<char const *>(this->buffer);
		}

		/**
		 * Returns the number of bytes composing the path.
		 */
		constexpr usize byte_size() const {
			return max - this->buffer[max];
		}

		/**
		 * Compares the path to `that`, returning the difference between the two paths or `0` if they are identical.
		 */
		constexpr size compare(path const & that) const {
			return coral::compare(this->as_slice().as_bytes(), that.as_slice().as_bytes());
		}

		/**
		 * Returns the tail pointer of the path name.
		 */
		char const * end() const {
			return this->buffer + this->byte_size();
		}

		/**
		 * Tests the path against `that` for equality, returning `true` if they are identical, otherwise `false`.
		 */
		constexpr bool equals(path const & that) const {
			return coral::equals(this->as_slice().as_bytes(), that.as_slice().as_bytes());
		}

		/**
		 * Returns the path hash code.
		 *
		 * *Note:* the returned hash code is not guaranteed to be unique.
		 */
		constexpr u64 hash() const {
			return coral::hash(this->as_slice().as_bytes());
		}

		/**
		 * Returns a new [path] composed of the current path joined with `text`.
		 *
		 * *Note:* should the new path exceed [max] bytes in size, an empty [path] is returned instead.
		 *
		 * *Note:* should the new path exceed [max] bytes in size, an empty [path] is returned instead.
		 */
		constexpr path joined(slice<char const> const & text) const {
			if (text.length > this->buffer[max]) return path{};

			path joined_path = *this;

			for (char const c : text) {
				joined_path.buffer[joined_path.byte_size()] = c;
				joined_path.buffer[max] -= 1;
			}

			return joined_path;
		}

		private:
		char buffer[max + 1]{0};
	};

	/**
	 * [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;
	};

	/**
	 * [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 fs {
		/**
		 * Errors that may occur while trying to walk a file tree.
		 *
		 * [walk_error::end_of_walk] reports that there are no more paths left in the file tree that to traverse.
		 *
		 * [walk_error::io_unavailable] indicates that an implementation-defined I/O error has occured during traversal
		 * of the file tree and failed to recover the next file tree path as a result.
		 */
		enum class walk_error {
			end_of_walk,
			io_unavailable,
		};

		/**
		 * Supplier of file paths from a file tree walking context created by calling [walk_files].
		 *
		 * Each subsequent invocation will produce either a valid path in the file tree from `target_path` or a
		 * [walk_error], with [walk_error::end_of_walk] signalling that there are no more paths left in the file tree to
		 * traverse. See [walk_error] for more details on potential errors.
		 */
		using walker = closure<expected<path, walk_error>()>;

		virtual ~fs() {};

		/**
		 * Attempts to read the file in `target_path`, calling `then` if it was successfully opened for reading and
		 * passing the [file_reader] context along.
		 */
		virtual void read_file(path 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 [walker] context along.
		 *
		 * See [walker] for more information on how to use it to traverse the file tree.
		 */
		virtual void walk_files(path const & target_path, closure<void(walker const &)> const & then) {}

		/**
		 * Attempts to write the file in the file system located at `target_path`, calling `then` if it was successfully
		 * opened for writing and passing the [file_writer] context along.
		 */
		virtual void write_file(path const & target_path, closure<void(file_writer &)> const & then) {}
	};
}