url

This library implements validation, parsing, generating, and normalization of URLs, which can be represented as atoms, character lists, or code lists. It currently supports the following URL schemes:

Web protocols:

  • http

  • https

  • ws

  • wss

  • gopher

File transfer and version control:

  • ftp

  • ftps

  • sftp

  • git

File access:

  • file

Databases:

  • jdbc

  • mongodb

  • mysql

  • postgresql

Email and news:

  • mailto

  • news

  • nntp

Media streaming:

  • mms

  • rtmp

  • rtsp

Shell access:

  • ssh

  • telnet

Directory services:

  • ldap

  • ldaps

Other protocols:

  • tel

  • urn

The library predicates are defined in the url(_Representation_) parametric object where _Representation_ can be one of:

  • atom - strings are represented as atoms

  • chars - strings are represented as lists of characters

  • codes - strings are represented as lists of character codes

The parameter must be bound when sending messages to the object.

The library also provides an utility predicate, file_path_components/2, for converting a file-system path into file URL components. This predicate also handles Windows drive-letter and UNC paths.

API documentation

Open the ../../apis/library_index.html#url link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(url(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(url(tester)).

Usage

The valid/1 and parse/2 predicates are intended for absolute URLs:

| ?- url(atom)::valid('https://example.com/path?x=1#frag').
true.

| ?- url(atom)::parse('https://example.com/path?x=1#frag', Components).
Components = [scheme(https), authority('example.com'), path('/path'), query('x=1'), fragment(frag)].

For RFC 3986 relative references, use parse/3 or reference_kind/2:

| ?- url(atom)::parse('../users/42?verbose=true#details', Components, Kind).
Components = [path('../users/42'), query('verbose=true'), fragment(details)],
Kind = relative_path.

| ?- url(atom)::reference_kind('//example.com/v1', Kind).
Kind = network_path.

The generate/2 and normalize/2 predicates work with both absolute URLs and relative references:

| ?- url(atom)::generate([authority('example.com'), path('/v1')], Reference).
Reference = '//example.com/v1'.

| ?- url(atom)::normalize('../users/./42', NormalizedReference).
NormalizedReference = '../users/42'.

The resolve/3 predicate resolves a reference against an absolute base URL, while relativize/3 computes a relative reference between compatible URLs:

| ?- url(atom)::resolve('http://example.com/a/b/c', '../d', Resolved).
Resolved = 'http://example.com/a/d'.

| ?- url(atom)::relativize('http://example.com/a/b/c', 'http://example.com/v1', Relative).
Relative = '../../v1'.

The file_path_components/2 predicate converts file-system paths into file URL components and supports both POSIX and Windows paths:

| ?- url(atom)::file_path_components('/home/user/document.txt', Components).
Components = [authority(''), path('/home/user/document.txt')].

| ?- url(atom)::file_path_components('C:\\Temp\\app\\file.txt', Components).
Components = [authority(''), path('/C:/Temp/app/file.txt')].