Name

       lua-uri-file - File URI support for Lua URI library

Description

       The class "uri.file" is used for URIs with the "file" scheme.  It inherits from the uri
       class.

       A file URI without an authority doesn't have a well defined meaning.  This library
       considers such URIs to be invalid when they have a path which does not start with '/' (for
       example "file:foo/bar").  It is likely that any such URI should really be a relative URI
       reference.  If the path does start with a slash then this library will attempt to 'repair'
       the URI by adding an empty authority part, so that "file:/foo/bar" will be changed
       automatically to "file:///foo/bar".

       A host value of "localhost" is normalized to an empty host, so that "file://localhost/foo"
       will become "file:///foo".  An empty path is normalized to '/'.

       The path part is always considered to be case sensitive, so no case folding is done even
       when converting to a filesystem path for Windows.

       Query parts and fragments are left alone by this library, but are not used in converting
       URIs to filesystem paths.

Converting between URIs and filesystem paths

       A "uri.file" object can be converted 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

       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

       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.

Methods

       All the methods defined in lua-uri(3) are supported.  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 '/'.

       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.

Operating systems supported

       The conversion between a file URI and a path suitable for use on a particular operating
       system are defined in additional classes, which are loaded automatically based on the
       operating system name supplied to the two conversion functions.  For example, 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.

           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.

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

       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.

References

       The most up to date IETF standard for the "file" URI scheme is still "RFC 1738 section
       3.10", but this 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.

       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>