Name

       lua-uri-_util - Utility functions for Lua URI library

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 URI encoding and decoding functions may be more widely useful.

       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.

           local Util = require "uri._util"

Functions

       The following functions can be found in the table returned from "require":

       uri_encode(text, pattern)
           Use URI encoding (or 'percent encoding') to encode any unsafe characters in "text".
           If "pattern" 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 "^"
           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.

               print(Util.uri_encode("foo bar!"))
               ---> foo%20bar!
               print(Util.uri_encode("foo bar!", "^A-Za-z0-9"))
               ---> foo%20bar%21

           The default pattern is: "^A-Za-z0-9%-_.!~*'()"

       uri_decode(text, pattern)
           Decode any URI encoding in "text".  If "pattern" is nil then all encoded characters
           will be decoded.  If a pattern is supplied then it should be in the same form as for
           "uri_encode".  Any character not matched by the pattern will be left encoded as it
           was.

               print(Util.uri_decode("foo%20bar%21"))
               ---> foo bar!
               print(Util.uri_decode("foo%20bar%21", "^!"))
               ---> foo bar%21

       remove_dot_segments(path)
           Removes single and double dot segments from a URI path.

           This is the 'remove_dot_segments' algorithm from "RFC 3986 section 5.2.4".  The value
           of "path" is used as the input buffer, and the contents of the output buffer are
           returned.

       split(pattern, str, max)
           Split the string "str" wherever "pattern" matches it, returning the pieces as
           individual strings in an array.  If "max" is not nil, then stop splitting after that
           many pieces have been created.

       attempt_require(name)
           Calling this function is the same as calling Lua's built in "require" function, except
           that if a module called "name" cannot be found, it returns nil instead of throwing an
           exception.  If loading the module is successful then the result of "require" is
           returned.  An exception is thrown if any error occurs loading the module other than it
           not being found.

       subclass_of(class, baseclass)
           Sets up the metatable and a few other things for the table "class" so that it will be
           a subclass of "baseclass".  This is used by the classes in this library to implement
           inheritance.

       do_class_changing_change(uri, baseclass, changedesc, newvalue, changefunc)
           This is used when a mutator method changes something about a URI which leads it to
           need to belong to a different class.  "uri" is the URI object to change, "baseclass"
           is the class to reset it to before making the change, "changedesc" is a description to
           be included in an error message if necessary, "newvalue" is the new value to be set
           (which must be a string, as it is also included in error messages), and "changefunc"
           is a function which is called with a temporary URI object it should adjust and
           "newvalue".

       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 URN).  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 URI is being validated during the "init" method's execution, it may return
           other things, which can be used to detect disallowed parts in a URI being parsed.