.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "LUA-URI-FILE 3" .TH LUA-URI-FILE 3 "2012-00-00" "1.1" "Lua uri.file module" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "Name" .IX Header "Name" lua-uri-file \- File \s-1URI\s0 support for Lua \s-1URI\s0 library .SH "Description" .IX Header "Description" The class \f(CW\*(C`uri.file\*(C'\fR is used for URIs with the \f(CW\*(C`file\*(C'\fR scheme. It inherits from the uri class. .PP A file \s-1URI\s0 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 \f(CW\*(C`file:foo/bar\*(C'\fR). It is likely that any such \s-1URI\s0 should really be a relative \s-1URI\s0 reference. If the path does start with a slash then this library will attempt to 'repair' the \s-1URI\s0 by adding an empty authority part, so that \f(CW\*(C`file:/foo/bar\*(C'\fR will be changed automatically to \&\f(CW\*(C`file:///foo/bar\*(C'\fR. .PP A host value of \f(CW\*(C`localhost\*(C'\fR is normalized to an empty host, so that \&\f(CW\*(C`file://localhost/foo\*(C'\fR will become \f(CW\*(C`file:///foo\*(C'\fR. An empty path is normalized to '/'. .PP 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. .PP Query parts and fragments are left alone by this library, but are not used in converting URIs to filesystem paths. .SH "Converting between URIs and filesystem paths" .IX Header "Converting between URIs and filesystem paths" A \f(CW\*(C`uri.file\*(C'\fR object can be converted into an absolute path suitable for use on a particular operating system by calling the \f(CW\*(C`filesystem_path\*(C'\fR method: .PP .Vb 3 \& local uri = assert(URI:new("file:///foo/bar")) \& print(uri:filesystem_path("unix")) \-\- /foo/bar \& print(uri:filesystem_path("win32")) \-\- \efoo\ebar .Ve .PP This method will throw an exception if the path cannot be converted. For example, a file \s-1URI\s0 containing a host name cannot be represented on a Unix filesystem, but on a Win32 system it will be converted to a \s-1UNC\s0 path: .PP .Vb 3 \& local uri = assert(URI:new("file://server/path")) \& print(uri:filesystem_path("unix")) \-\- error \& print(uri:filesystem_path("win32")) \-\- \e\eserver\epath .Ve .PP To convert a filesystem path into a \s-1URI,\s0 call the class method \&\f(CW\*(C`make_file_uri\*(C'\fR: .PP .Vb 5 \& 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:\efoo\ebar", "win32") \& print(uri) \-\- file:///C:/foo/bar .Ve .PP To convert a relative \s-1URI\s0 reference (a uri._relative object) into a filesystem path you should first resolve it against an appropriate \f(CW\*(C`file\*(C'\fR \s-1URI,\s0 and then call the \f(CW\*(C`filesystem_path\*(C'\fR method on that. .SH "Methods" .IX Header "Methods" All the methods defined in \fBlua\-uri\fR\|(3) are supported. The \f(CW\*(C`userinfo\*(C'\fR, and \f(CW\*(C`port\*(C'\fR methods will always return nil, and will throw an exception when passed anything other than nil. The \f(CW\*(C`host\*(C'\fR method will normalize \f(CW\*(C`localhost\*(C'\fR to an empty host name, and will throw an exception if given a new value of nil. The \f(CW\*(C`path\*(C'\fR method will normalize an empty path or nil value to '/'. .PP In addition to the standard methods, file URIs support the \f(CW\*(C`filesystem_path\*(C'\fR method, and the \f(CW\*(C`uri.file\*(C'\fR class contains the \f(CW\*(C`make_file_uri\*(C'\fR function, both of which are described above. .SH "Operating systems supported" .IX Header "Operating systems supported" The conversion between a file \s-1URI\s0 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 \f(CW\*(C`win32\*(C'\fR to the functions will invoke the implementation in the class \f(CW\*(C`uri.file.win32\*(C'\fR. An exception will be thrown if no class exists to support a given operating system. The following operating system classes are provided: .ie n .IP """uri.file.unix""" 4 .el .IP "\f(CWuri.file.unix\fR" 4 .IX Item "uri.file.unix" A \s-1URI\s0 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 (\f(CW%00\fR) or encoded slash (\f(CW%2F\fR) then an exception will be thrown. .Sp Attempting to convert a relative path to a \s-1URI\s0 will cause an exception. .ie n .IP """uri.file.win32""" 4 .el .IP "\f(CWuri.file.win32\fR" 4 .IX Item "uri.file.win32" Forward slashes ('/') in URIs will be converted to backslashes ('\e') in paths, and vice versa. .Sp URIs containing host names will be converted to \s-1UNC\s0 paths, starting with a '\e\e' followed by the hostname and then the path part. If the path part of a \s-1URI\s0 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 \s-1URI\s0 nowadays. .PP The operating system names are case insensitive, and are folded to lowercase before being converted into a Lua module name. .PP 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. .SH "References" .IX Header "References" The most up to date \s-1IETF\s0 standard for the \f(CW\*(C`file\*(C'\fR \s-1URI\s0 scheme is still \&\*(L"\s-1RFC 1738\s0 section 3.10\*(R", 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. .PP The correct form of file \s-1URI\s0 to represent a Windows filesystem path is described in a blog article: .PP There is a standard of sorts describing the conversion between Unix paths and file URIs: