mirror of https://github.com/sipwise/lua-uri.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
111 lines
4.1 KiB
111 lines
4.1 KiB
=head1 Name
|
|
|
|
lua-uri-_util - Utility functions for Lua URI library
|
|
|
|
=head1 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.
|
|
|
|
=for syntax-highlight lua
|
|
|
|
local Util = require "uri._util"
|
|
|
|
=head1 Functions
|
|
|
|
The following functions can be found in the table returned from C<require>:
|
|
|
|
=over
|
|
|
|
=item uri_encode(text, pattern)
|
|
|
|
Use URI encoding (or 'percent encoding') to encode any unsafe characters
|
|
in C<text>. If C<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 C<^> 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.
|
|
|
|
=for syntax-highlight lua
|
|
|
|
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: C<^A-Za-z0-9%-_.!~*'()>
|
|
|
|
=item uri_decode(text, pattern)
|
|
|
|
Decode any URI encoding in C<text>. If C<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 C<uri_encode>. Any character not matched by the pattern
|
|
will be left encoded as it was.
|
|
|
|
=for syntax-highlight lua
|
|
|
|
print(Util.uri_decode("foo%20bar%21"))
|
|
---> foo bar!
|
|
print(Util.uri_decode("foo%20bar%21", "^!"))
|
|
---> foo bar%21
|
|
|
|
=item remove_dot_segments(path)
|
|
|
|
Removes single and double dot segments from a URI path.
|
|
|
|
This is the 'remove_dot_segments' algorithm from L<RFC 3986 section 5.2.4>.
|
|
The value of C<path> is used as the input buffer, and the contents of the
|
|
output buffer are returned.
|
|
|
|
=item split(pattern, str, max)
|
|
|
|
Split the string C<str> wherever C<pattern> matches it, returning the pieces
|
|
as individual strings in an array. If C<max> is not nil, then stop splitting
|
|
after that many pieces have been created.
|
|
|
|
=item attempt_require(name)
|
|
|
|
Calling this function is the same as calling Lua's built in C<require>
|
|
function, except that if a module called C<name> cannot be found, it returns
|
|
nil instead of throwing an exception. If loading the module is successful
|
|
then the result of C<require> is returned. An exception is thrown if any
|
|
error occurs loading the module other than it not being found.
|
|
|
|
=item subclass_of(class, baseclass)
|
|
|
|
Sets up the metatable and a few other things for the table C<class> so that it
|
|
will be a subclass of C<baseclass>. This is used by the classes in this
|
|
library to implement inheritance.
|
|
|
|
=item 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. C<uri> is the URI object to change,
|
|
C<baseclass> is the class to reset it to before making the change,
|
|
C<changedesc> is a description to be included in an error message if necessary,
|
|
C<newvalue> is the new value to be set (which must be a string, as it is also
|
|
included in error messages), and C<changefunc> is a function which is called
|
|
with a temporary URI object it should adjust and C<newvalue>.
|
|
|
|
=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 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 C<init> method's execution, it may return other things, which can
|
|
be used to detect disallowed parts in a URI being parsed.
|
|
|
|
=back
|
|
|
|
=for comment
|
|
vi:ts=4 sw=4 expandtab
|