.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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-_UTIL 3"
.TH LUA-URI-_UTIL 3 "2012-00-00" "1.1" "Lua uri._util 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\-_util \- Utility functions for Lua \s-1URI\s0 library
.SH "Description"
.IX Header "Description"
This module contains various utility functions used by the rest of the
library.  They are mostly intended only for internal use, and are subject
to change in future versions, but the \s-1URI\s0 encoding and decoding functions
may be more widely useful.
.PP
On loading, the module returns a table containing the functions, but like
all the modules in this library it does not install itself into any global
variables.
.PP
.Vb 1
\&    local Util = require "uri._util"
.Ve
.SH "Functions"
.IX Header "Functions"
The following functions can be found in the table returned from \f(CW\*(C`require\*(C'\fR:
.IP "uri_encode(text, pattern)" 4
.IX Item "uri_encode(text, pattern)"
Use \s-1URI\s0 encoding (or 'percent encoding') to encode any unsafe characters
in \f(CW\*(C`text\*(C'\fR.  If \f(CW\*(C`pattern\*(C'\fR is specified then it should be part of a Lua
pattern which can be enclosed in square brackets to make a character class.
Usually it will start with \f(CW\*(C`^\*(C'\fR so that the rest of the characters will be
considered the 'safe' ones, not to be encoded.  Any character matched by the
pattern will be encoded.
.Sp
.Vb 4
\&    print(Util.uri_encode("foo bar!"))
\&    \-\-\-> foo%20bar!
\&    print(Util.uri_encode("foo bar!", "^A\-Za\-z0\-9"))
\&    \-\-\-> foo%20bar%21
.Ve
.Sp
The default pattern is: \f(CW\*(C`^A\-Za\-z0\-9%\-_.!~*\*(Aq()\*(C'\fR
.IP "uri_decode(text, pattern)" 4
.IX Item "uri_decode(text, pattern)"
Decode any \s-1URI\s0 encoding in \f(CW\*(C`text\*(C'\fR.  If \f(CW\*(C`pattern\*(C'\fR is nil then all encoded
characters will be decoded.  If a pattern is supplied then it should be in
the same form as for \f(CW\*(C`uri_encode\*(C'\fR.  Any character not matched by the pattern
will be left encoded as it was.
.Sp
.Vb 4
\&    print(Util.uri_decode("foo%20bar%21"))
\&    \-\-\-> foo bar!
\&    print(Util.uri_decode("foo%20bar%21", "^!"))
\&    \-\-\-> foo bar%21
.Ve
.IP "remove_dot_segments(path)" 4
.IX Item "remove_dot_segments(path)"
Removes single and double dot segments from a \s-1URI\s0 path.
.Sp
This is the 'remove_dot_segments' algorithm from \*(L"\s-1RFC 3986\s0 section 5.2.4\*(R".
The value of \f(CW\*(C`path\*(C'\fR is used as the input buffer, and the contents of the
output buffer are returned.
.IP "split(pattern, str, max)" 4
.IX Item "split(pattern, str, max)"
Split the string \f(CW\*(C`str\*(C'\fR wherever \f(CW\*(C`pattern\*(C'\fR matches it, returning the pieces
as individual strings in an array.  If \f(CW\*(C`max\*(C'\fR is not nil, then stop splitting
after that many pieces have been created.
.IP "attempt_require(name)" 4
.IX Item "attempt_require(name)"
Calling this function is the same as calling Lua's built in \f(CW\*(C`require\*(C'\fR
function, except that if a module called \f(CW\*(C`name\*(C'\fR cannot be found, it returns
nil instead of throwing an exception.  If loading the module is successful
then the result of \f(CW\*(C`require\*(C'\fR is returned.  An exception is thrown if any
error occurs loading the module other than it not being found.
.IP "subclass_of(class, baseclass)" 4
.IX Item "subclass_of(class, baseclass)"
Sets up the metatable and a few other things for the table \f(CW\*(C`class\*(C'\fR so that it
will be a subclass of \f(CW\*(C`baseclass\*(C'\fR.  This is used by the classes in this
library to implement inheritance.
.IP "do_class_changing_change(uri, baseclass, changedesc, newvalue, changefunc)" 4
.IX Item "do_class_changing_change(uri, baseclass, changedesc, newvalue, changefunc)"
This is used when a mutator method changes something about a \s-1URI\s0 which leads it
to need to belong to a different class.  \f(CW\*(C`uri\*(C'\fR is the \s-1URI\s0 object to change,
\&\f(CW\*(C`baseclass\*(C'\fR is the class to reset it to before making the change,
\&\f(CW\*(C`changedesc\*(C'\fR is a description to be included in an error message if necessary,
\&\f(CW\*(C`newvalue\*(C'\fR is the new value to be set (which must be a string, as it is also
included in error messages), and \f(CW\*(C`changefunc\*(C'\fR is a function which is called
with a temporary \s-1URI\s0 object it should adjust and \f(CW\*(C`newvalue\*(C'\fR.
.IP "uri_part_not_allowed (class, method)" 4
.IX Item "uri_part_not_allowed (class, method)"
This should be called in scheme-specific classes where certain parts of URIs
are not allowed to be present (e.g., the 'host' part in a \s-1URN\s0).  It will
override the named method in the class with one which throws an exception
if an attempt is made to set the part to anything other than nil.  If the
rest of the code for the scheme keeps objects internally consistent then the
new method should always return nil, although when a \s-1URI\s0 is being validated
during the \f(CW\*(C`init\*(C'\fR method's execution, it may return other things, which can
be used to detect disallowed parts in a \s-1URI\s0 being parsed.