url

This module provides classes and functions for parsing and processing URLs. This module supports username and passwords in URLs in order to support an arbitrary number of RFC combinations but this does not strictly conform to RFC1738.

The scope of URL in this module have not been limited to HTTP or any protocol for that matter. However, where deductible, the module tries to conform to the most appropriate URL for the specified scheme.

Constructing a URL is vey simple. Here is an example.

Example

%> import url
%> var link = url.Url('https', 'example.com', 9000)
%> link.absolute_url()
'https://example.com:9000'

What each function and class method does are easy to deduce from their names.

For example, we can use the parse() function to convert a URL string into a URL instance like below.

%> link = url.parse('https://example.com:9000')
%> link.scheme
'https'
%> link.port
'9000'

Functions

url.encode(url, strict)

URL-encodes a string

This function is convenient when encoding a string to be used in a query part of a URL, as a convenient way to pass variables to the next page. If strict mode is enabled, space character is encoded with the percent (%) sign in order to conform with RFC 3986. Otherwise, is is encoded with the plus (+) sign in order to align with the default encoding used by modern browsers.

• @params:
  • string url
  • bool? strict Default value is false

• @returns: string

url.decode(url)

Decodes URL-encoded string. This function decodes any %## encoding in the given string and plus symbols ('+') to a space character.

• @params:
  • string url

• @returns: string

url.parse(url, strict)

Parses given url string into a Url object. If the strict argument is set to true, the parser will raise an Exception when it encounters a malformed url.

• @params:
  • string url
  • bool? strict Default value is false

• @returns: Url

Classes

class UrlMalformedException < Exception

Exception thrown when a url is malformed

.UrlMalformedException(message) ➝ Constructor

url.UrlMalformedException constructor

• @params:
  • string message

class Url

The Url class provides functionalities for parsing and processing URLs.

@printable, @serializable

.scheme

The url scheme e.g. http, https, ftp, tcp etc.

.host

The host information contained in the url

.port

The port information contained in the url whenever the url doesn't indicate, we try to make a best guess based on the scheme.

.path

The path of the URL. @default /

.hash

Hash information contained in the url and it's beginning is indicated by the hash (#) sign. This value is especially relevant to some http/https urls and are usually references to the content of the document at the given url

.query

Query/Search information contained in the url and it's beginning is indicated by the question (?) sign. This value is especially relevant to some http/https urls and are usually used to convey data to endpoint based on the GET method.

.username

Username information for authentication are sometimes embedded in urls. When such information exist, this property holds the information

.password

Password information for authentication are sometimes embedded in urls. When such information exist, this property holds the information

.has_slash

true if the url contains the 😕/ section. false otherwise.

.empty_path ➝ bool

true if the original url contains a path segment even if its just an / and false if the path value of / was implied.

.Url(scheme, host, port, path, query, hash, username, password, has_slash, empty_path) ➝ Constructor

url.Url constructor

• @params:
  • string scheme
  • string host
  • string? port
  • string? path
  • string? query
  • string? hash
  • string? username
  • string? password
  • bool? has_slash
  • bool? empty_path

.authority()

Returns the url authority.

The authority component is preceded by a double slash ("//") and is terminated by the next slash ("/"), question mark ("?"), or number sign ("#") character, or by the end of the URI.

@notes:

• mailto scheme does not have an authority. For this reason, mailto schemes return an empty string as authority.

• @returns: string

.host_is_ipv4()

Returns true if the host of the url is a valid ipv4 address and false otherwise.

• @returns: bool

.host_is_ipv6()

Returns true if the host of the url is a valid ipv6 address and false otherwise.

• @returns: bool

.absolute_url()

Returns absolute url string of the url object.

• @returns: string

.to_string()

Returns a string representation of the url object. This will only be the same as the absolute url if the original string is an absolute url.

• @returns: string