.. index:: single: url(Representation)
.. _url/1:

.. rst-class:: right

**object**

``url(Representation)``
=======================

* ``Representation`` - URL and is components representation. Valid values are ``atom``, ``codes``, and ``chars``.


URL validating, parsing, and normalizing predicates following RFC3986 nomenclature.

| **Availability:** 
|    ``logtalk_load(url(loader))``

| **Author:** Paulo Moura
| **Version:** 2:0:0
| **Date:** 2026-05-22

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Uses:**
|    :ref:`list <list/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: valid/1
.. _url/1::valid/1:

``valid/1``
^^^^^^^^^^^

True iff the argument is a valid URL, including optional query and fragment components.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid(URL)``
| **Mode and number of proofs:**
|    ``valid(++text)`` - ``zero_or_one``


------------

.. index:: parse/2
.. _url/1::parse/2:

``parse/2``
^^^^^^^^^^^

Parses a URL into a list of its components: ``[scheme(Scheme), authority(Authority), path(Path), query(Query), fragment(Fragment)]``. Fails if the URL is invalid and cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse(URL,Components)``
| **Mode and number of proofs:**
|    ``parse(++text,-list(compound))`` - ``zero_or_one``


------------

.. index:: generate/2
.. _url/1::generate/2:

``generate/2``
^^^^^^^^^^^^^^

Generates a normalized URL or RFC3986 relative reference from a list of components. Component lists headed by ``scheme/1`` generate absolute URLs; lists without ``scheme/1`` generate relative references.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate(Components,URL)``
| **Mode and number of proofs:**
|    ``generate(++list(compound),-text)`` - ``zero_or_one``


------------

.. index:: parse/3
.. _url/1::parse/3:

``parse/3``
^^^^^^^^^^^

Parses a URL or RFC3986 relative reference into a list of its components and classifies it as one of ``url``, ``network_path``, ``absolute_path``, ``relative_path``, ``query``, or ``fragment``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse(Reference,Components,Kind)``
| **Mode and number of proofs:**
|    ``parse(++text,-list(compound),-atom)`` - ``zero_or_one``


------------

.. index:: reference_kind/2
.. _url/1::reference_kind/2:

``reference_kind/2``
^^^^^^^^^^^^^^^^^^^^

Classifies a valid reference as one of ``url``, ``network_path``, ``absolute_path``, ``relative_path``, ``query``, or ``fragment``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``reference_kind(Reference,Kind)``
| **Mode and number of proofs:**
|    ``reference_kind(++text,-atom)`` - ``zero_or_one``


------------

.. index:: equivalent/2
.. _url/1::equivalent/2:

``equivalent/2``
^^^^^^^^^^^^^^^^

True iff both arguments normalize to the same textual representation under the library normalization rules.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``equivalent(Reference1,Reference2)``
| **Mode and number of proofs:**
|    ``equivalent(++text,++text)`` - ``zero_or_one``


------------

.. index:: relativize/3
.. _url/1::relativize/3:

``relativize/3``
^^^^^^^^^^^^^^^^

Relativizes a target absolute hierarchical URL against a base absolute hierarchical URL with the same scheme and authority, returning a non-empty relative reference accepted by the library. Fails when no such non-empty relative reference can be generated.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``relativize(Base,Target,Relative)``
| **Mode and number of proofs:**
|    ``relativize(++text,++text,-text)`` - ``zero_or_one``


------------

.. index:: resolve/3
.. _url/1::resolve/3:

``resolve/3``
^^^^^^^^^^^^^

Resolves a reference against a base absolute hierarchical URL and returns a normalized absolute URL. The first argument must be an absolute hierarchical URL suitable for use as a base. The second argument may be either a relative reference or an absolute URL; when it is already absolute, the result is that absolute URL normalized and returned unchanged apart from normalization.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``resolve(Base,Reference,Resolved)``
| **Mode and number of proofs:**
|    ``resolve(++text,++text,-text)`` - ``zero_or_one``


------------

.. index:: normalize/2
.. _url/1::normalize/2:

``normalize/2``
^^^^^^^^^^^^^^^

Normalizes a URL or RFC3986 relative reference by standardizing its components. Normalization includes converting the scheme to lowercase when present, normalizing the authority, percent-encoding characters that require escaping, and simplifying path dot segments while preserving absolute and relative reference forms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``normalize(Reference,NormalizedReference)``
| **Mode and number of proofs:**
|    ``normalize(++text,-text)`` - ``one``


------------

.. index:: file_path_components/2
.. _url/1::file_path_components/2:

``file_path_components/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts a file-system path into file URL components represented as ``[authority(Authority), path(Path)]``. Windows drive-letter and UNC paths are normalized to RFC3986-compatible file URL components.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``file_path_components(FilePath,Components)``
| **Mode and number of proofs:**
|    ``file_path_components(++text,-list(compound))`` - ``one``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

.. index:: downcase_text/2
.. _url/1::downcase_text/2:

``downcase_text/2``
^^^^^^^^^^^^^^^^^^^

Converts text to lowercase (ASCII only). Only uppercase letters A-Z are converted to lowercase.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``downcase_text(Text,LowerText)``
| **Mode and number of proofs:**
|    ``downcase_text(+text,-text)`` - ``one``


------------

Operators
---------

(none)

