Module socket.url

The url namespace provides functions to parse, protect, and build URLs, as well as functions to compose absolute URLs from base and relative URLs, according to RFC 2396.

To obtain the url namespace, run:

-- loads the URL module 
local url = require("socket.url")

An URL is defined by the following grammar:

<url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>]
<authority> ::= [<userinfo>@]<host>[:<port>]
<userinfo> ::= <user>[:<password>]
<path> ::= {<segment>/}<segment>

Type socket.url

socket.url.absolute(base, relative)	Builds an absolute URL from a base URL and a relative URL.
socket.url.build(parsed_url)	Rebuilds an URL from its parts.
socket.url.build_path(segments, unsafe)	Builds a component from a list of parts.
socket.url.escape(content)	Applies the URL escaping content coding to a string each byte is encoded as a percent character followed by the two byte hexadecimal representation of its integer value.
socket.url.parse(url, default)	Parses an URL given as a string into a Lua table with its components.
socket.url.parse_path(path)	Breaks a URL component into all its parts.
socket.url.unescape(content)	Removes the URL escaping content coding from a string.

Type socket.url

Field(s)

socket.url.absolute(base, relative)

Builds an absolute URL from a base URL and a relative URL.

Note: The rules that govern the composition are fairly complex, and are described in detail in RFC 2396. The example bellow should give an idea of what the rules are.

http://a/b/c/d;p?q

+

g:h      =  g:h
g        =  http://a/b/c/g
./g      =  http://a/b/c/g
g/       =  http://a/b/c/g/
/g       =  http://a/g
//g      =  http://g
?y       =  http://a/b/c/?y
g?y      =  http://a/b/c/g?y
#s       =  http://a/b/c/d;p?q#s
g#s      =  http://a/b/c/g#s
g?y#s    =  http://a/b/c/g?y#s
;x       =  http://a/b/c/;x
g;x      =  http://a/b/c/g;x
g;x?y#s  =  http://a/b/c/g;x?y#s
.        =  http://a/b/c/
./       =  http://a/b/c/
..       =  http://a/b/
../      =  http://a/b/
../g     =  http://a/b/g
../..    =  http://a/
../../   =  http://a/
../../g  =  http://a/g

Parameters

• #string base : The base URL or a parsed URL table.

• #string relative : The relative URL.

Return value

#string: The absolute URL.

socket.url.build(parsed_url)

Rebuilds an URL from its parts.

Parameter

• #table parsed_url : With same components returned by socket.url.parse. Lower level components, if specified, take precedence over high level components of the URL grammar.

Return value

#string: The built URL.

socket.url.build_path(segments, unsafe)

Builds a component from a list of parts.

Before composition, any reserved characters found in a segment are escaped into their protected form, so that the resulting path is a valid URL path component.

Parameters

• #table segments : A list of strings with the parts.

• unsafe : If is anything but nil, reserved characters are left untouched.

Return value

#string: With the built component.

socket.url.escape(content)

Applies the URL escaping content coding to a string each byte is encoded as a percent character followed by the two byte hexadecimal representation of its integer value.

Parameter

• #string content : The #string to be encoded.

Return value

#string: The encoded string.

Usage:

-- load url module
url = require("socket.url")

code = url.escape("/#?;")
-- code = "%2f%23%3f%3b"

socket.url.parse(url, default)

Parses an URL given as a string into a Lua table with its components.

Parameters

• #string url : The URL to be parsed.

• #table default : If present, it is used to store the parsed fields. Only fields present in the URL are overwritten. Therefore, this table can be used to pass default values for each field.

Return value

#table: All the URL components:

parsed_url = {
  url = string,
  scheme = string,
  authority = string,
  path = string,
  params = string,
  query = string,
  fragment = string,
  userinfo = string,
  host = string,
  port = string,
  user = string,
  password = string
}

Usage:

-- load url module
url = require("socket.url")

parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there")
-- parsed_url = {
--   scheme = "http",
--   authority = "www.example.com",
--   path = "/cgilua/index.lua"
--   query = "a=2",
--   fragment = "there",
--   host = "www.puc-rio.br",
-- }

parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
-- parsed_url = {
--   scheme = "ftp",
--   authority = "root:passwd@unsafe.org",
--   path = "/pub/virus.exe",
--   params = "type=i",
--   userinfo = "root:passwd",
--   host = "unsafe.org",
--   user = "root",
--   password = "passwd",
-- }

socket.url.parse_path(path)

Breaks a URL component into all its parts.

Parameter

• #string path : With the path to be parsed.

Return value

Since some characters are reserved in URLs, they must be escaped whenever present in a component. Therefore, before returning a list with all the parsed segments, the function removes escaping from all of them.

socket.url.unescape(content)

Removes the URL escaping content coding from a string.

Parameter

• #string content : The string to be decoded.

Return value

#string: The decoded string.