Pack prolog_library_collection -- prolog/uri

Extends the support for URIs in the SWI-Prolog standard library.

append_segments(+Segments1:list(atom), +Segments2:list(atom), +Segments3:list(atom)) is semidet

append_segments(+Segments1:list(atom), +Segments2:list(atom), -Segments3:list(atom)) is det

Appends lists of path segments. Empty segments commonly appear at the beginning and end of URI paths.

uri_comp_get(+Kind:oneof([authority,fragment,host,password,path,port,query,scheme,user]), +Uri:uri, +Component:term) is semidet

uri_comp_get(+Kind:oneof([authority,fragment,host,password,path,port,query,scheme,user]), +Uri:uri, -Component:term) is det

uri_comp_set(+Kind:oneof([fragment,query]), +Uri1, +Component, -Uri2) is det

Change a specific URI component.

uri_comps(+Uri, -Components) is det

uri_comps(-Uri, +Components) is det

Components is a compound term of the form `uri(Scheme,Authority,Segments,Query,Fragment)', where:

Authority is either an atom or a compound term of the form `auth(User,Password,Host,Port)'.
Segments is a list of atomic path segments.
Query is (1) a list of unary compound terms, or (2) a list of pairs, or (3) a flat dict (i.e., a dict with non-dict values).

uri_data_directory(+Uri:atom, -Directory:atom) is det

uri_data_file(+Uri:atom, +Local:atom, -File:atom) is det

uri_file_extensions(+Uri:atom, -Extensions:list(atom)) is det

uri_file_is_fresh(+Uri:uri, +File:atom) is det

uri_local_name(+Uri:atom, -Local:atom) is det

uri_media_type(+Uri:atom, -MediaType:media_type) is det

uri_relative_path(+Uri:atom, +Local:atom, -RelativePath:atom) is det

uri_scheme(+Uri:atom, +Scheme:atom) is semidet

uri_scheme(+Uri:atom, -Scheme:atom) is semidet

uri_strip(+Uri1:atom, -Uri2:atom) is det

Uri2 is like Uri1, but without the query and fragment components.

Re-exported predicates

The following predicates are re-exported from other modules

uri_components(+URI, -Components) is det

uri_components(-URI, +Components) is det

Break a URI into its 5 basic components according to the RFC-3986 regular expression:

^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
 12            3  4          5       6  7        8 9

Arguments:

Components - is a term uri_components(Scheme, Authority, Path, Search, Fragment). If a URI is parsed, i.e., using mode (+,-), components that are not found are left uninstantiated (variable). See uri_data/3 for accessing this structure.

uri_data(?Field, +Components, ?Data) is semidet

Provide access the uri_component structure. Defined field-names are: scheme, authority, path, search and fragment

uri_data(+Field, +Components, +Data, -NewComponents) is semidet

NewComponents is the same as Components with Field set to Data.

uri_normalized(+URI, -NormalizedURI) is det

NormalizedURI is the normalized form of URI. Normalization is syntactic and involves the following steps:

6.2.2.1. Case Normalization
6.2.2.2. Percent-Encoding Normalization
6.2.2.3. Path Segment Normalization

iri_normalized(+IRI, -NormalizedIRI) is det

NormalizedIRI is the normalized form of IRI. Normalization is syntactic and involves the following steps:

6.2.2.1. Case Normalization
6.2.2.3. Path Segment Normalization

See also: - This is similar to uri_normalized/2, but does not do normalization of %-escapes.

uri_normalized_iri(+URI, -NormalizedIRI) is det

As uri_normalized/2, but percent-encoding is translated into IRI Unicode characters. The translation is liberal: valid UTF-8 sequences of %-encoded bytes are mapped to the Unicode character. Other %XX-sequences are mapped to the corresponding ISO-Latin-1 character and sole % characters are left untouched.

See also: - uri_iri/2.

uri_normalized(+URI, +Base, -NormalizedGlobalURI) is det

NormalizedGlobalURI is the normalized global version of URI. Behaves as if defined by:

uri_normalized(URI, Base, NormalizedGlobalURI) :-
        uri_resolve(URI, Base, GlobalURI),
        uri_normalized(GlobalURI, NormalizedGlobalURI).

iri_normalized(+IRI, +Base, -NormalizedGlobalIRI) is det

NormalizedGlobalIRI is the normalized global version of IRI. This is similar to uri_normalized/3, but does not do %-escape normalization.

uri_normalized_iri(+URI, +Base, -NormalizedGlobalIRI) is det

NormalizedGlobalIRI is the normalized global IRI of URI. Behaves as if defined by:

uri_normalized(URI, Base, NormalizedGlobalIRI) :-
        uri_resolve(URI, Base, GlobalURI),
        uri_normalized_iri(GlobalURI, NormalizedGlobalIRI).

uri_resolve(+URI, +Base, -GlobalURI) is det

Resolve a possibly local URI relative to Base. This implements http://labs.apache.org/webarch/uri/rfc/rfc3986.html#relative-transform

uri_is_global(+URI) is semidet

True if URI has a scheme. The semantics is the same as the code below, but the implementation is more efficient as it does not need to parse the other components, nor needs to bind the scheme. The condition to demand a scheme of more than one character is added to avoid confusion with DOS path names.

uri_is_global(URI) :-
        uri_components(URI, Components),
        uri_data(scheme, Components, Scheme),
        nonvar(Scheme),
        atom_length(Scheme, Len),
        Len > 1.

uri_query_components(+String, -Query) is det

uri_query_components(-String, +Query) is det

Perform encoding and decoding of an URI query string. Query is a list of fully decoded (Unicode) Name=Value pairs. In mode (-,+), query elements of the forms Name(Value) and Name-Value are also accepted to enhance interoperability with the option and pairs libraries. E.g.

?- uri_query_components(QS, [a=b, c('d+w'), n-'VU Amsterdam']).
QS = 'a=b&c=d%2Bw&n=VU%20Amsterdam'.

?- uri_query_components('a=b&c=d%2Bw&n=VU%20Amsterdam', Q).
Q = [a=b, c='d+w', n='VU Amsterdam'].

uri_authority_components(+Authority, -Components) is det

uri_authority_components(-Authority, +Components) is det

Break-down the authority component of a URI. The fields of the structure Components can be accessed using uri_authority_data/3.

uri_authority_data(+Field, ?Components, ?Data) is semidet

Provide access the uri_authority structure. Defined field-names are: user, password, host and port

uri_encoded(+Component, +Value, -Encoded) is det

uri_encoded(+Component, -Value, +Encoded) is det

Encoded is the URI encoding for Value. When encoding (Value->Encoded), Component specifies the URI component where the value is used. It is one of query_value, fragment, path or segment. Besides alphanumerical characters, the following characters are passed verbatim (the set is split in logical groups according to RFC3986).

query_value, fragment: "-._~" | "!$'()*,;" | "@" | "/?"
path: "-._~" | "!$&'()*,;=" | "@" | "/"
segment: "-._~" | "!$&'()*,;=" | "@"

uri_file_name(+URI, -FileName) is semidet

uri_file_name(-URI, +FileName) is det

Convert between a URI and a local file_name. This protocol is covered by RFC 1738. Please note that file-URIs use absolute paths. The mode (-, +) translates a possible relative path into an absolute one.

uri_iri(+URI, -IRI) is det

uri_iri(-URI, +IRI) is det

Convert between a URI, encoded in US-ASCII and an IRI. An IRI is a fully expanded Unicode string. Unicode strings are first encoded into UTF-8, after which %-encoding takes place.

Errors: - syntax_error(Culprit) in mode (+,-) if URI is not a legally percent-encoded UTF-8 string.