LUA-URI-FILE(3)

💖 lua-uri-file — the file URI glow-up, bestie edition 💖

okay so real talk: this is the lua-uri-file page from the Lua uri.file module, and it's literally all about making file URIs behave themselves. no cap. 🦋

---

🌸 NAME 🌸

lua-uri-file — file URI support for the Lua URI library. that's the whole vibe. 🎀

---

✨ DESCRIPTION ✨

so the class uri.file is what you use for URIs with the file scheme, and it inherits from the uri class (iykyk, it gets all the family traits 💅).

here's the tea: a file URI without an authority doesn't have a well defined meaning. this library straight up considers those invalid when they have a path that doesn't start with / — think file:foo/bar. and honestly? it's likely that any such URI should really be a relative URI reference. but if the path does start with a slash, the library will attempt to 'repair' the URI by adding an empty authority part, so that file:/foo/bar gets changed automatically to file:///foo/bar. glow-up complete, periodt. ✨

a host value of localhost is normalized to an empty host, so file://localhost/foo becomes file:///foo. and an empty path is normalized to /. iconic behavior honestly.

the path part is always considered to be case sensitive, so no case folding happens — not even when you're converting to a filesystem path for Windows. the path does NOT care. 🫶

query parts and fragments? the library leaves them alone, but they are not used in converting URIs to filesystem paths. they're just vibing in the corner. 🙈

---

🦋 Converting between URIs and filesystem paths 🦋

🎀 uri → path (the filesystem_path method)

you can turn a uri.file object into an absolute path suitable for use on a particular operating system by calling the filesystem_path method:

local uri = assert(URI:new("file:///foo/bar"))
print(uri:filesystem_path("unix"))  -- /foo/bar
print(uri:filesystem_path("win32")) -- \foo\bar

this method will throw an exception if the path cannot be converted. for example, a file URI containing a host name cannot be represented on a Unix filesystem, but on a Win32 system it will be converted to a UNC path:

local uri = assert(URI:new("file://server/path"))
print(uri:filesystem_path("unix"))  -- error
print(uri:filesystem_path("win32")) -- \\server\path

🌈 path → uri (the make_file_uri class method)

to convert a filesystem path into a URI, call the class method make_file_uri:

local FileURI = require "uri.file"
local uri = FileURI.make_file_uri("/foo/bar", "unix")
print(uri)      -- file:///foo/bar
uri = FileURI.make_file_uri("C:\foo\bar", "win32")
print(uri)      -- file:///C:/foo/bar

🧚 relative references, the plot twist

to convert a relative URI reference (a uri._relative object) into a filesystem path, you should first resolve it against an appropriate file URI, and then call the filesystem_path method on that. two steps, bestie, don't skip step one. 💅

---

👑 METHODS 👑

all the methods defined in lua-uri(3) are supported. here's the extra rules for this class specifically:

• the userinfo and port methods will always return nil, and will throw an exception when passed anything other than nil.
• the host method will normalize localhost to an empty host name, and will throw an exception if given a new value of nil.
• the path method will normalize an empty path or nil value to /.

and in addition to the standard methods, file URIs support the filesystem_path method, and the uri.file class contains the make_file_uri function — both of which are described above, so scroll back up if you skipped it, no judgment. 🫶

---

🌟 Operating systems supported 🌟

the conversion between a file URI and a path suitable for use on a particular operating system is defined in additional classes, which are loaded automatically based on the operating system name supplied to the two conversion functions. so like, passing the string "win32" to the functions will invoke the implementation in the class uri.file.win32. an exception will be thrown if no class exists to support a given operating system. the following operating system classes are provided:

• uri.file.unix — a URI containing a host name will cause an exception to be thrown, as there is no obvious way for these to be represented in Unix paths. if the path contains an encoded null byte (%00) or encoded slash (%2F) then an exception will be thrown. also: attempting to convert a relative path to a URI will cause an exception.
• uri.file.win32 — forward slashes (/) in URIs will be converted to backslashes (\) in paths, and vice versa. URIs containing host names will be converted to UNC paths, starting with a \\ followed by the hostname and then the path part. if the path part of a URI appears to begin with a drive letter, then the first slash will be removed so that the resulting path starts with the letter. encoded pipe characters (%7C) will be recognized as equivalent to colons for the purpose of identifying drive letters, since they have been historically used in that way — but I believe they are not allowed to occur in the path unencoded in a URI nowadays.

also important: the operating system names are case insensitive, and are folded to lowercase before being converted into a Lua module name.

and ngl, currently there is no way for this library to recognise the operating system it is running on, since Lua has no built-in way of providing that information. tragic, but that's the situation. 😭

---

🍓 REFERENCES 🍓

• the most up to date IETF standard for the file URI scheme is still RFC 1738 section 3.10 — but it does not specify exactly how to convert between URIs and filesystem paths on particular platforms. it does however specify the equivalence between localhost and an empty host, so that part slays. ✨
• the correct form of file URI to represent a Windows filesystem path is described in a blog article: <http://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx>
• there is a standard of sorts describing the conversion between Unix paths and file URIs: <http://equinox-project.org/spec/file-uri-spec.txt>

---

💖 that's the whole page bestie, go forth and convert your URIs with confidence 💖

this was version 1.1, dated 2012-00-00, and it lives at the very bottom of the page as LUA-URI-FILE(3) — consider this your cute little sign-off. mwah. 💅🌸🦋