Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Tests for `Uri.fromPath` and `Uri.toPath`, the `file:` URI conversions.
const std = @import("std");const uri = @import("root.zig");
const Uri = uri.Uri;const expectEqual = std.testing.expectEqual;const expectEqualStrings = std.testing.expectEqualStrings;const expectError = std.testing.expectError;
const Case = struct { path: []const u8, /// The URI that path names, as text. text: []const u8, /// What `toPath` gives back. Null when that is the path itself, which is /// every POSIX case and every Windows path already in canonical form. back: ?[]const u8 = null,};
// -- POSIX -----------------------------------------------------------------
const posix_cases = [_]Case{ .{ .path = "/", .text = "file:///" }, .{ .path = "/a", .text = "file:///a" }, .{ .path = "/a/b", .text = "file:///a/b" }, // A trailing separator is a trailing empty segment, which is what makes // the URI name a directory. .{ .path = "/a/b/", .text = "file:///a/b/" }, .{ .path = "/etc/hosts", .text = "file:///etc/hosts" },
// Escaping is the formatter's job: the segments hold the bytes as given. .{ .path = "/home/jeff/a b.txt", .text = "file:///home/jeff/a%20b.txt" }, .{ .path = "/a#b", .text = "file:///a%23b" }, .{ .path = "/a?b", .text = "file:///a%3Fb" }, .{ .path = "/a%b", .text = "file:///a%25b" }, // A backslash is an ordinary character in a POSIX filename, so it stays // inside the one segment it was written in. .{ .path = "/a\\b", .text = "file:///a%5Cb" }, // Bytes are bytes: a path is not required to be UTF-8, and nothing here // interprets it as text. .{ .path = "/\xc3\xa9", .text = "file:///%C3%A9" }, .{ .path = "/\xff", .text = "file:///%FF" },
// Dot segments are part of the path as written. Resolution removes them, // but a path that has them names them, and `fromPath` is not resolution. .{ .path = "/a/../b", .text = "file:///a/../b" }, .{ .path = "/a/./b", .text = "file:///a/./b" },
// An empty segment survives too, since `/a//b` and `/a/b` are the same // file only by convention. .{ .path = "/a//b", .text = "file:///a//b" }, // POSIX leaves a path beginning with exactly two slashes // implementation-defined, so it is preserved rather than folded: the // empty authority takes two slashes and the path keeps its own. .{ .path = "//foo", .text = "file:////foo" },};
test "POSIX paths convert to file URIs and back" { const alloc = std.testing.allocator; for (posix_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .posix }); defer u.deinit();
const text = try u.toText(alloc, .{}); defer alloc.free(text); try expectEqualStrings(case.text, text);
const back = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back); try expectEqualStrings(case.back orelse case.path, back); }}
test "a file URI built from a POSIX path re-parses to the same components" { const alloc = std.testing.allocator; for (posix_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .posix }); defer u.deinit();
const text = try u.toText(alloc, .{}); defer alloc.free(text);
const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); try std.testing.expect(u.eql(reparsed)); }}
// -- Windows ---------------------------------------------------------------
const windows_cases = [_]Case{ // A drive letter is the first path segment, which is what puts the colon // after the three slashes. .{ .path = "C:\\", .text = "file:///C:/" }, .{ .path = "C:\\a", .text = "file:///C:/a" }, .{ .path = "C:\\a\\b", .text = "file:///C:/a/b" }, .{ .path = "C:\\Users\\me\\a b.txt", .text = "file:///C:/Users/me/a%20b.txt" }, // The case of the drive letter is the caller's, not ours. .{ .path = "c:\\a", .text = "file:///c:/a" }, // Forward slashes are accepted on input; backslashes are always written. .{ .path = "C:/a/b", .text = "file:///C:/a/b", .back = "C:\\a\\b" },
// UNC: the server is the URI's host, and the share is just the first // segment of the path. .{ .path = "\\\\server\\share\\x", .text = "file://server/share/x" }, .{ .path = "\\\\server\\share", .text = "file://server/share" }, .{ .path = "\\\\server\\", .text = "file://server/" }, .{ .path = "\\\\server", .text = "file://server/", .back = "\\\\server\\" }, // A server name that is a dotted quad is an address literal, the same as // it would be coming from the parser. .{ .path = "\\\\192.0.2.1\\share", .text = "file://192.0.2.1/share" },
// Rooted on the current drive: not fully qualified, but exactly what // `file:///a/b` reads back as. .{ .path = "\\a\\b", .text = "file:///a/b" }, .{ .path = "\\", .text = "file:///" },};
test "Windows paths convert to file URIs and back" { const alloc = std.testing.allocator; for (windows_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .windows }); defer u.deinit();
const text = try u.toText(alloc, .{}); defer alloc.free(text); try expectEqualStrings(case.text, text);
const back = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(back); try expectEqualStrings(case.back orelse case.path, back); }}
test "a file URI built from a Windows path re-parses to the same components" { const alloc = std.testing.allocator; for (windows_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .windows }); defer u.deinit();
const text = try u.toText(alloc, .{}); defer alloc.free(text);
const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); try std.testing.expect(u.eql(reparsed)); }}
test "the Windows drive forms a URI can carry" { const alloc = std.testing.allocator; const cases = [_]struct { text: []const u8, path: []const u8 }{ .{ .text = "file:///C:/a", .path = "C:\\a" }, // RFC 8089 Appendix E.2: older software wrote the drive with a // vertical bar, and it still turns up. .{ .text = "file:///C|/a", .path = "C:\\a" }, .{ .text = "file:///C%7C/a", .path = "C:\\a" }, // `C:` on its own would be the current directory *on* that drive, // which is not what a URI naming the drive means, so the root // separator is written either way. .{ .text = "file:///C:", .path = "C:\\" }, .{ .text = "file:///C:/", .path = "C:\\" }, // Only the first segment is a drive; anywhere else a colon is just a // character, as in an alternate data stream. .{ .text = "file:///C:/a/D:/b", .path = "C:\\a\\D:\\b" }, .{ .text = "file:///a/b", .path = "\\a\\b" }, .{ .text = "file:///", .path = "\\" }, }; for (cases) |case| { const u = try Uri.parse(alloc, case.text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(path); try expectEqualStrings(case.path, path); }}
// -- the forms of a local file URI ----------------------------------------
test "an empty host and localhost both mean this machine" { const alloc = std.testing.allocator; // RFC 8089 §2. The last of these is the minimal form, with no authority // at all -- legal, never produced here, and the same file. for ([_][]const u8{ "file:///a/b", "file://localhost/a/b", "file://LocalHost/a/b", "file:/a/b", }) |text| { const u = try Uri.parse(alloc, text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/a/b", path); }}
test "a query or fragment names nothing on a filesystem and is ignored" { const alloc = std.testing.allocator; for ([_][]const u8{ "file:///a/b?q=1", "file:///a/b#top", "file:///a/b?q=1#top" }) |text| { const u = try Uri.parse(alloc, text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/a/b", path); }}
test "a percent-encoded path comes back decoded" { const alloc = std.testing.allocator; const u = try Uri.parse(alloc, "file:///home/jeff/a%20b%23c.txt"); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/home/jeff/a b#c.txt", path);}
// -- what has no conversion ------------------------------------------------
test "a path with no file URI is rejected rather than mangled" { const alloc = std.testing.allocator; const cases = [_]struct { path: []const u8, platform: uri.file.Platform, err: anyerror, }{ // Resolving a relative path needs the working directory, which is I/O. .{ .path = "a/b", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = ".", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = "", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = "a\\b", .platform = .windows, .err = error.PathNotAbsolute }, // Relative to a drive's current directory, which is no more absolute // than a bare relative path. .{ .path = "C:a", .platform = .windows, .err = error.PathNotAbsolute }, .{ .path = "C:", .platform = .windows, .err = error.PathNotAbsolute },
// A NUL ends the path for every system call that takes one, so a URI // carrying one would name a different file than it appears to. .{ .path = "/a\x00b", .platform = .posix, .err = error.InvalidPath },
// The Win32 device namespace is not a share, and has no `file:` form. .{ .path = "\\\\?\\C:\\x", .platform = .windows, .err = error.InvalidPath }, .{ .path = "\\\\.\\PhysicalDrive0", .platform = .windows, .err = error.InvalidPath }, // A UNC path with no server names nothing. .{ .path = "\\\\\\share", .platform = .windows, .err = error.InvalidPath }, // `\\C:` would be written `file:///C:`, which everything reading it // back takes for the drive. A colon cannot appear in a Windows // filename anyway, so the ambiguity is refused rather than written. .{ .path = "\\C:", .platform = .windows, .err = error.InvalidPath }, .{ .path = "\\C:\\a", .platform = .windows, .err = error.InvalidPath }, }; for (cases) |case| { try expectError(case.err, Uri.fromPath(alloc, case.path, .{ .platform = case.platform })); }}
test "a URI with no path is rejected rather than mangled" { const alloc = std.testing.allocator; const cases = [_]struct { text: []const u8, platform: uri.file.Platform = .posix, err: anyerror, }{ .{ .text = "http://x/a", .err = error.NotFileScheme }, .{ .text = "/a/b", .err = error.NotFileScheme }, .{ .text = "file:a/b", .err = error.PathNotAbsolute }, .{ .text = "file://", .err = error.PathNotAbsolute },
// POSIX has no way to name a file on another machine. .{ .text = "file://server/share/x", .err = error.NonLocalHost }, // Windows does -- but not one addressed by an IPv6 literal, which it // spells as a name under `ipv6-literal.net` instead. .{ .text = "file://[::1]/share", .platform = .windows, .err = error.NonLocalHost },
// One segment holding a separator is one file; writing it out would // name two. .{ .text = "file:///a%2Fb", .err = error.InvalidPath }, .{ .text = "file:///a%5Cb", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file:///a%00b", .err = error.InvalidPath },
// A Windows path opening with two separators is a UNC prefix, which // an empty authority says this is not. .{ .text = "file:////a", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file:////", .platform = .windows, .err = error.InvalidPath }, // And `\\.\` and `\\?\` are the device namespace rather than a // server, so those two hosts have no UNC path either. .{ .text = "file://./share", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file://%3F/share", .platform = .windows, .err = error.InvalidPath }, }; for (cases) |case| { const u = try Uri.parse(alloc, case.text); defer u.deinit(); try expectError(case.err, u.toPath(alloc, .{ .platform = case.platform })); }}
test "a backslash is a filename on POSIX and a separator on Windows" { const alloc = std.testing.allocator; // The same URI, read as each platform's path: one file called `a\b`, or // two path components. The second is why `toPath` rejects it -- a URI // whose segment holds a separator has no Windows path. const u = try Uri.parse(alloc, "file:///a%5Cb"); defer u.deinit();
const posix = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(posix); try expectEqualStrings("/a\\b", posix);
try expectError(error.InvalidPath, u.toPath(alloc, .{ .platform = .windows }));}
// -- the round trip --------------------------------------------------------
test "a POSIX path survives the round trip exactly" { const alloc = std.testing.allocator; // Every byte that means something to a URI parser, plus a few that mean // something to a path, in the one place a path can hold them. const paths = [_][]const u8{ "/", "/a", "/a/", "//", "///", "/a/b/c", "/a//b", "/a/./b", "/a/../b", "/a b", "/a%20b", "/a?b", "/a#b", "/a&b=c", "/a:b", "/a@b", "/a[b]c", "/a\\b", "/a|b", "/.hidden", "/\xff\xfe", "/\xc3\xa9", "/C:/x", "/~jeff/a", "/a/b/../../../../c", }; for (paths) |path| { const u = try Uri.fromPath(alloc, path, .{ .platform = .posix }); defer u.deinit();
const back = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back); try expectEqualStrings(path, back);
// And through the text, which is the trip that actually happens: a // URI is written down somewhere and read back by something else. const text = try u.toText(alloc, .{}); defer alloc.free(text); const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); const back_again = try reparsed.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back_again); try expectEqualStrings(path, back_again); }}
test "a Windows path round-trips in canonical form" { const alloc = std.testing.allocator; // Not byte-for-byte: both separators go in and only `\` comes out. What // has to hold is that converting again changes nothing. const paths = [_][]const u8{ "C:\\", "C:\\a", "C:/a", "C:\\a\\b\\", "C:\\a b\\c#d", "\\\\s\\share", "\\\\s\\a\\b", "\\\\s/a/b", "\\a\\b", "\\", "z:\\a", "C:\\a\\..\\b", }; for (paths) |path| { const u = try Uri.fromPath(alloc, path, .{ .platform = .windows }); defer u.deinit();
const once = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(once);
const again = try Uri.fromPath(alloc, once, .{ .platform = .windows }); defer again.deinit(); const twice = try again.toPath(alloc, .{ .platform = .windows }); defer alloc.free(twice);
try expectEqualStrings(once, twice); try std.testing.expect(u.eql(again)); }}
// -- building on top -------------------------------------------------------
test "a file URI is an ordinary Uri, and click and relativize work on it" { const alloc = std.testing.allocator; const base = try Uri.fromPath(alloc, "/home/jeff/dev/zig-uri/", .{ .platform = .posix }); defer base.deinit();
// What a relative path in a document under that directory names. const target = try base.click(alloc, "src/file.zig"); defer target.deinit();
const path = try target.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/home/jeff/dev/zig-uri/src/file.zig", path);
// And back the other way. const rel = try base.relativize(alloc, target, .{}); defer rel.deinit(); const rel_text = try rel.toText(alloc, .{}); defer alloc.free(rel_text); try expectEqualStrings("src/file.zig", rel_text);}
test "the default platform is the one being built for" { const builtin = @import("builtin"); const expected: uri.file.Platform = if (builtin.os.tag == .windows) .windows else .posix; try expectEqual(expected, (uri.file.Options{}).platform);}