src/engine/main.zig

@@ -15,7 +15,7 @@ fn run(app: *sys.AppContext, graphics: *sys.GraphicsContext) anyerror!void {
     defer _ = gpa.deinit();
 
     {
-        var file_access = try app.data().open(try sys.Path.joined(&.{"ona.lua"}), .readonly);
+        var file_access = try (try app.data().joinedPath(&.{"ona.lua"})).open(.readonly);
 
         defer file_access.close();
 

src/engine/sys.zig

@@ -1,5 +1,3 @@
-const Archive = @import("./sys/Archive.zig");
-
 const ext = @cImport({
     @cInclude("SDL2/SDL.h");
 });
@@ -150,7 +148,7 @@ pub const AppContext = opaque {
                 .user_path_prefix = user_path_prefix,
 
                 .data_file_system = .{.archive = .{
-                    .index_cache = try Archive.IndexCache.init(allocator),
+                    .index_cache = try FileSystem.ArchiveIndexCache.init(allocator),
                     .file_access = data_archive_file_access,
                 }},
 
@@ -271,7 +269,40 @@ pub const AppContext = opaque {
 ///
 pub const FileSystem = union(enum) {
     native: []const u8,
-    archive: Archive,
+
+    archive: struct {
+        file_access: ona.io.FileAccess,
+        index_cache: ArchiveIndexCache,
+
+        entry_table: [max_open_entries]ArchiveEntry =
+            std.mem.zeroes([max_open_entries]ArchiveEntry),
+
+        const max_open_entries = 16;
+    },
+
+    ///
+    ///
+    ///
+    const ArchiveEntry = struct {
+        owner: ?*ona.io.FileAccess,
+        cursor: u64,
+        header: oar.Entry,
+    };
+
+    ///
+    ///
+    ///
+    const ArchiveIndexCache = ona.table.Hashed(oar.Path, u64, .{
+        .equals = oar.Path.equals,
+        .hash = oar.Path.hash,
+    });
+
+    ///
+    /// Platform-agnostic mechanism for referencing files and directories on a [FileSystem].
+    ///
+    pub const Path = struct {
+        file_system: *FileSystem,
+        path: oar.Path,
 
         ///
         /// With files typically being backed by a block device, they can produce a variety of
@@ -296,11 +327,11 @@ pub const FileSystem = union(enum) {
         /// [OpenMode.readonly] indicates that an existing file is opened in a read-only state,
         /// disallowing write access.
         ///
-    /// [OpenMode.overwrite] indicates that an empty file has been created or an existing file has
+        /// [OpenMode.overwrite] indicates that an empty file has been created or an existing file
-    /// been completely overwritten into.
+        /// has been completely overwritten into.
         ///
-    /// [OpenMode.append] indicates that an existing file that has been opened for reading from and
+        /// [OpenMode.append] indicates that an existing file that has been opened for reading from
-    /// writing to on the end of existing data.
+        /// and writing to on the end of existing data.
         ///
         pub const OpenMode = enum {
             readonly,
@@ -309,13 +340,38 @@ pub const FileSystem = union(enum) {
         };
 
         ///
-    /// Attempts to open the file identified by `path` with `mode` as the mode for opening the file.
+        /// Returns `true` if the length of `path` is empty, otherwise `false`.
         ///
-    /// Returns a [FileAccess] reference that provides access to the file referenced by `path`or a
+        pub fn isEmpty(path: Path) bool {
-    /// [OpenError] if it failed.
+            return (path.length == 0);
+        }
+
         ///
-    pub fn open(file_system: *FileSystem, path: Path, mode: OpenMode) OpenError!ona.io.FileAccess {
+        /// Returns `true` if `this` is equal to `that`, otherwise `false`.
-        switch (file_system.*) {
+        ///
+        pub fn equals(this: Path, that: Path) bool {
+            return (this.file_system == that.file_system) and
+                std.mem.eql(u8, this.buffer[0 .. this.length], that.buffer[0 .. that.length]);
+        }
+
+        ///
+        /// The maximum possible byte-length of a [Path].
+        ///
+        /// Note that paths are encoded using UTF-8, meaning that a character may be bigger than one
+        /// byte. Because of this, it is not safe to asume that a path may hold [max] individual
+        /// characters.
+        ///
+        pub const max = 255;
+
+        ///
+        /// Attempts to open the file identified by `path` with `mode` as the mode for opening the
+        /// file.
+        ///
+        /// Returns a [FileAccess] reference that provides access to the file referenced by `path`
+        /// or a [OpenError] if it failed.
+        ///
+        pub fn open(path: Path, mode: OpenMode) OpenError!ona.io.FileAccess {
+            switch (path.file_system.*) {
                 .archive => |*archive| {
                     if (mode != .readonly) return error.ModeUnsupported;
 
@@ -323,9 +379,9 @@ pub const FileSystem = union(enum) {
 
                     for (archive.entry_table) |*entry| if (entry.owner == null) {
                         const Implementation = struct {
-                        fn archiveEntryCast(context: *anyopaque) *Archive.Entry {
+                            fn archiveEntryCast(context: *anyopaque) *ArchiveEntry {
-                            return @ptrCast(*Archive.Entry, @alignCast(
+                                return @ptrCast(*ArchiveEntry, @alignCast(
-                                @alignOf(Archive.Entry), context));
+                                    @alignOf(ArchiveEntry), context));
                             }
 
                             fn close(context: *anyopaque) void {
@@ -394,29 +450,24 @@ pub const FileSystem = union(enum) {
                             }
                         };
 
-                    const Header = oar.Entry;
+                        if (archive.index_cache.lookup(path.path)) |index| {
-
-                    if (archive.index_cache.lookup(path)) |index| {
                             archive.file_access.seek(index) catch return error.FileNotFound;
 
                             entry.* = .{
                                 .owner = &archive.file_access,
                                 .cursor = 0,
 
-                            .header = (Header.next(archive.file_access) catch
+                                .header = (oar.Entry.next(archive.file_access) catch return error.FileNotFound) orelse {
-                                return error.FileNotFound) orelse {
-
                                     // Remove cannot fail if lookup succeeded.
-                                std.debug.assert(archive.index_cache.remove(path) != null);
+                                    std.debug.assert(archive.index_cache.remove(path.path) != null);
 
                                     return error.FileNotFound;
                                 },
                             };
                         } else {
-                        while (Header.next(archive.file_access) catch
+                            while (oar.Entry.next(archive.file_access) catch return error.FileNotFound) |entry_header| {
-                            return error.FileNotFound) |entry_header| {
+                                if (entry.header.path.equals(path.path))
-
+                                    entry.* = .{
-                            if (entry.header.path.equals(path)) entry.* = .{
                                         .owner = &archive.file_access,
                                         .cursor = 0,
                                         .header = entry_header,
@@ -448,17 +499,19 @@ pub const FileSystem = union(enum) {
                     if (native.len == 0) return error.FileNotFound;
 
                     var path_buffer = std.mem.zeroes([4096]u8);
-                const seperator_length = @boolToInt(native[native.len - 1] != oar.Path.seperator);
+                    const seperator_length = @boolToInt(native[native.len - 1] != seperator);
 
-                if ((native.len + seperator_length + path.length) >=
+                    if ((native.len + seperator_length + path.path.length) >=
                         path_buffer.len) return error.FileNotFound;
 
                     std.mem.copy(u8, path_buffer[0 ..], native);
 
-                if (seperator_length != 0) path_buffer[native.len] = oar.Path.seperator;
+                    if (seperator_length != 0) path_buffer[native.len] = seperator;
 
                     std.mem.copy(u8, path_buffer[native.len .. path_buffer.
-                    len], path.buffer[0 .. path.length]);
+                        len], path.path.buffer[0 .. path.path.length]);
+
+                    ext.SDL_ClearError();
 
                     const FileAccess = ona.io.FileAccess;
 
@@ -538,8 +591,6 @@ pub const FileSystem = union(enum) {
                         }
                     };
 
-                ext.SDL_ClearError();
-
                     return FileAccess{
                         .context = ext.SDL_RWFromFile(&path_buffer, switch (mode) {
                             .readonly => "rb",
@@ -560,6 +611,67 @@ pub const FileSystem = union(enum) {
                 },
             }
         }
+
+        pub const seperator = '/';
+    };
+
+    ///
+    /// [PathError.TooLong] occurs when creating a path that is greater than the maximum size **in
+    /// bytes**.
+    ///
+    pub const PathError = error {
+        TooLong,
+    };
+
+    ///
+    /// Attempts to create a [Path] with `file_system` as the file-system root and the path
+    /// components in `sequences` as a fully qualified path from the root.
+    ///
+    /// A [Path] value is returned containing the fully qualified path from the file-system root or
+    /// a [PathError] if it could not be created.
+    ///
+    pub fn joinedPath(file_system: *FileSystem, sequences: []const []const u8) PathError!Path {
+        var path = Path{
+            .file_system = file_system,
+            .path = oar.Path.empty,
+        };
+
+        if (sequences.len != 0) {
+            const last_sequence_index = sequences.len - 1;
+
+            for (sequences) |sequence, index| if (sequence.len != 0) {
+                var components = ona.io.Spliterator(u8){
+                    .source = sequence,
+                    .delimiter = "/",
+                };
+
+                while (components.next()) |component| if (component.len != 0) {
+                    for (component) |byte| {
+                        if (path.path.length == Path.max) return error.TooLong;
+
+                        path.path.buffer[path.path.length] = byte;
+                        path.path.length += 1;
+                    }
+
+                    if (components.hasNext()) {
+                        if (path.path.length == Path.max) return error.TooLong;
+
+                        path.path.buffer[path.path.length] = '/';
+                        path.path.length += 1;
+                    }
+                };
+
+                if (index < last_sequence_index) {
+                    if (path.path.length == Path.max) return error.TooLong;
+
+                    path.path.buffer[path.path.length] = '/';
+                    path.path.length += 1;
+                }
+            };
+        }
+
+        return path;
+    }
 };
 
 ///
@@ -633,11 +745,6 @@ pub const Log = enum(u32) {
     }
 };
 
-///
-/// Path to a file on a [FileSystem].
-///
-pub const Path = oar.Path;
-
 ///
 /// [RunError.InitFailure] occurs if a necessary resource fails to be acquired or allocated.
 ///
@@ -691,7 +798,7 @@ pub fn runGraphics(comptime Error: anytype,
     defer ext.SDL_DestroyRenderer(renderer);
 
     var cwd_file_system = FileSystem{.native ="./"};
-    var data_access = try cwd_file_system.open(try Path.joined(&.{"./data.oar"}), .readonly);
+    var data_access = try (try cwd_file_system.joinedPath(&.{"./data.oar"})).open(.readonly);
 
     defer data_access.close();
 

src/engine/sys/Archive.zig

@@ -1,29 +0,0 @@
-const oar = @import("oar");
-const ona = @import("ona");
-const std = @import("std");
-
-file_access: ona.io.FileAccess,
-index_cache: IndexCache,
-entry_table: [max_open_entries]Entry = std.mem.zeroes([max_open_entries]Entry),
-
-///
-/// Hard limit on the maximum number of entries open at once.
-///
-const max_open_entries = 16;
-
-///
-/// Stateful extension of an [oar.Entry].
-///
-pub const Entry = struct {
-    owner: ?*ona.io.FileAccess,
-    cursor: u64,
-    header: oar.Entry,
-};
-
-///
-/// Table cache for associating [oar.Path] values with offsets to entries in a given file.
-///
-pub const IndexCache = ona.table.Hashed(oar.Path, u64, .{
-    .equals = oar.Path.equals,
-    .hash = oar.Path.hash,
-});

src/oar/main.zig

@@ -55,14 +55,6 @@ pub const Path = extern struct {
     buffer: [255]u8,
     length: u8,
 
-    ///
-    /// [Error.TooLong] occurs when creating a path that is greater than the maximum path size **in
-    /// bytes**.
-    ///
-    pub const Error = error {
-        TooLong,
-    };
-
     ///
     /// An empty [Path] with a length of `0`.
     ///
@@ -82,63 +74,6 @@ pub const Path = extern struct {
     pub fn hash(path: Path) usize {
         return ona.io.hashBytes(path.buffer[0 .. path.length]);
     }
-
-    ///
-    /// Attempts to create a [Path] with the path components in `sequences` as a fully qualified
-    /// path from root.
-    ///
-    /// A [Path] value is returned containing the fully qualified path from the file-system root or
-    /// a [Error] if it could not be created.
-    ///
-    pub fn joined(sequences: []const []const u8) Error!Path {
-        var path = empty;
-
-        if (sequences.len != 0) {
-            const last_sequence_index = sequences.len - 1;
-
-            for (sequences) |sequence, index| if (sequence.len != 0) {
-                var components = ona.io.Spliterator(u8){
-                    .source = sequence,
-                    .delimiter = "/",
-                };
-
-                while (components.next()) |component| if (component.len != 0) {
-                    for (component) |byte| {
-                        if (path.length == max) return error.TooLong;
-
-                        path.buffer[path.length] = byte;
-                        path.length += 1;
-                    }
-
-                    if (components.hasNext()) {
-                        if (path.length == max) return error.TooLong;
-
-                        path.buffer[path.length] = '/';
-                        path.length += 1;
-                    }
-                };
-
-                if (index < last_sequence_index) {
-                    if (path.length == max) return error.TooLong;
-
-                    path.buffer[path.length] = '/';
-                    path.length += 1;
-                }
-            };
-        }
-
-        return path;
-    }
-
-    ///
-    /// Maximum number of **bytes** in a [Path].
-    ///
-    pub const max = 255;
-
-    ///
-    /// Textual separator between components of a [Path].
-    ///
-    pub const seperator = '/';
 };
 
 ///