.. index:: registries
.. _registries/0:

.. rst-class:: right

**object**

``registries``
==============

Registry handling predicates.

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

| **Author:** Paulo Moura
| **Version:** 0:60:0
| **Date:** 2024-10-09

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


| **Imports:**
|    ``public`` :ref:`packs_common <packs_common/0>`
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`logtalk <logtalk/0>`
|    :ref:`os <os/0>`
|    :ref:`type <type/0>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`packs_common/0::directory/1`  :ref:`packs_common/0::directory/2`  :ref:`packs_common/0::help/0`  :ref:`packs_common/0::logtalk_packs/0`  :ref:`packs_common/0::logtalk_packs/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`packs_common/0::pin/0`  :ref:`packs_common/0::pin/1`  :ref:`packs_common/0::pinned/1`  :ref:`packs_common/0::prefix/0`  :ref:`packs_common/0::prefix/1`  :ref:`packs_common/0::readme/1`  :ref:`packs_common/0::readme/2`  :ref:`packs_common/0::reset/0`  :ref:`packs_common/0::setup/0`  :ref:`packs_common/0::unpin/0`  :ref:`packs_common/0::unpin/1`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  :ref:`packs_common/0::verify_commands_availability/0`  

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

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

.. index:: list/0
.. _registries/0::list/0:

``list/0``
^^^^^^^^^^

Prints a list of all defined registries, including how defined (``git``, ``archive``, or ``directory``) and  if they are pinned.

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

| **Mode and number of proofs:**
|    ``list`` - ``one``


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

.. index:: describe/1
.. _registries/0::describe/1:

``describe/1``
^^^^^^^^^^^^^^

Prints all registry entries.

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

| **Template:**
|    ``describe(Registry)``
| **Mode and number of proofs:**
|    ``describe(+atom)`` - ``one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``


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

.. index:: defined/4
.. _registries/0::defined/4:

``defined/4``
^^^^^^^^^^^^^

Enumerates by backtracking all defined registries, their definition URL, how they are defined (``git``, ``archive``, or ``directory``), and if they are pinned.

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

| **Template:**
|    ``defined(Registry,URL,HowDefined,Pinned)``
| **Mode and number of proofs:**
|    ``defined(?atom,?atom,?atom,?boolean)`` - ``zero_or_more``

| **Exceptions:**
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``URL`` is neither a variable nor an atom:
|        ``type_error(atom,URL)``
|    ``HowDefined`` is neither a variable nor an atom:
|        ``type_error(atom,HowDefined)``
|    ``Pinned`` is neither a variable nor a boolean:
|        ``type_error(boolean,Pinned)``


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

.. index:: add/3
.. _registries/0::add/3:

``add/3``
^^^^^^^^^

Adds a new registry using the given options. Fails if the registry cannot be added or if it is already defined but not using ``update(true)`` or ``force(true)`` options. A ``file://`` URL can be used for a local directory.

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

| **Template:**
|    ``add(Registry,URL,Options)``
| **Mode and number of proofs:**
|    ``add(+atom,+atom,++list(compound))`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``URL`` is neither a variable nor an atom:
|        ``type_error(atom,URL)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``

| **Remarks:**

    - Registry name: Must be the URL basename when using a git URL or a local directory URL. Must also be the declared registry name in the registry specification object.
    - HTTPS URLs: Must end with either a ``.git`` extension or an archive extension.
    - ``update(Boolean)`` option: Update registry if already defined. Default is ``false``. Overrides the ``force/1`` option.
    - ``force(Boolean)`` option: Force registry re-installation if already defined by first deleting the previous installation. Default is ``false``.
    - ``clean(Boolean)`` option: Clean registry archive after updating. Default is ``false``.
    - ``verbose(Boolean)`` option: Verbose adding steps. Default is ``false``.
    - ``downloader(Atom)`` option: Downloader utility. Either ``curl`` or ``wget``. Default is ``curl``.
    - ``curl(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``wget(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``gpg(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``tar(Atom)`` option: Extra command-line options. Default is ``''``.


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

.. index:: add/2
.. _registries/0::add/2:

``add/2``
^^^^^^^^^

Adds a new registry using default options. Fails if the registry cannot be added or if it is already defined. HTTPS URLs must end with either a ``.git`` extension or a an archive extension. A ``file://`` URL can be used for a local directory.

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

| **Template:**
|    ``add(Registry,URL)``
| **Mode and number of proofs:**
|    ``add(+atom,+atom)`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``URL`` is neither a variable nor an atom:
|        ``type_error(atom,URL)``

| **Remarks:**

    - Registry name: Must be the URL basename when using a git URL or a local directory URL. Must also be the declared registry name in the registry specification object.


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

.. index:: add/1
.. _registries/0::add/1:

``add/1``
^^^^^^^^^

Adds a new registry from a git cloning or local directory URL using default options. Fails if the registry cannot be added or if it is already defined. HTTPS URLs must end with a ``.git`` extension. A ``file://`` URL can be used for a local directory.

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

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

| **Exceptions:**
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``URL`` is neither a variable nor an atom:
|        ``type_error(atom,URL)``

| **Remarks:**

    - Limitations: Cannot be used for archive download URLs.
    - Registry name: Taken from the URL basename.


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

.. index:: update/2
.. _registries/0::update/2:

``update/2``
^^^^^^^^^^^^

Updates a defined registry using the specified options. Fails if the registry is not defined.

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

| **Template:**
|    ``update(Registry,Options)``
| **Mode and number of proofs:**
|    ``update(+atom,++list(compound))`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``

| **Remarks:**

    - ``force(Boolean)`` option: Force update if the registry is pinned. Default is ``false``.
    - ``clean(Boolean)`` option: Clean registry archive after updating. Default is ``false``.
    - ``verbose(Boolean)`` option: Verbose updating steps. Default is ``false``.
    - ``downloader(Atom)`` option: Downloader utility. Either ``curl`` or ``wget``. Default is ``curl``.
    - ``curl(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``wget(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``gpg(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``tar(Atom)`` option: Extra command-line options. Default is ``''``.


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

.. index:: update/1
.. _registries/0::update/1:

``update/1``
^^^^^^^^^^^^

Updates a defined registry using default options. Fails if the registry is not defined.

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

| **Template:**
|    ``update(Registry)``
| **Mode and number of proofs:**
|    ``update(+atom)`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``


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

.. index:: update/0
.. _registries/0::update/0:

``update/0``
^^^^^^^^^^^^

Updates all defined registries using default options.

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

| **Mode and number of proofs:**
|    ``update`` - ``zero_or_one``


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

.. index:: delete/2
.. _registries/0::delete/2:

``delete/2``
^^^^^^^^^^^^

Deletes a registry using the specified options (if not pinned).

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

| **Template:**
|    ``delete(Registry,Options)``
| **Mode and number of proofs:**
|    ``delete(+atom,++list(compound))`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``

| **Remarks:**

    - ``force(Boolean)`` option: Force deletion if the registry is pinned or there are installed registry packs. Default is ``false``.
    - ``clean(Boolean)`` option: Clean registry archive after deleting. Default is ``false``.
    - ``verbose(Boolean)`` option: Verbose deleting steps. Default is ``false``.
    - ``downloader(Atom)`` option: Downloader utility. Either ``curl`` or ``wget``. Default is ``curl``.
    - ``curl(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``wget(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``gpg(Atom)`` option: Extra command-line options. Default is ``''``.
    - ``tar(Atom)`` option: Extra command-line options. Default is ``''``.


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

.. index:: delete/1
.. _registries/0::delete/1:

``delete/1``
^^^^^^^^^^^^

Deletes a registry using default options.

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

| **Template:**
|    ``delete(Registry)``
| **Mode and number of proofs:**
|    ``delete(+atom)`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``


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

.. index:: delete/0
.. _registries/0::delete/0:

``delete/0``
^^^^^^^^^^^^

Deletes all registries using the ``force(true)`` option.

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

| **Mode and number of proofs:**
|    ``delete`` - ``zero_or_one``


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

.. index:: clean/1
.. _registries/0::clean/1:

``clean/1``
^^^^^^^^^^^

Cleans all registry archives. Fails if the registry is not defined.

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

| **Template:**
|    ``clean(Registry)``
| **Mode and number of proofs:**
|    ``clean(+atom)`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``


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

.. index:: clean/0
.. _registries/0::clean/0:

``clean/0``
^^^^^^^^^^^

Cleans all archives for all registries.

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

| **Mode and number of proofs:**
|    ``clean`` - ``one``


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

.. index:: provides/2
.. _registries/0::provides/2:

``provides/2``
^^^^^^^^^^^^^^

Enumerates by backtracking all packs provided by a registry.

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

| **Template:**
|    ``provides(Registry,Pack)``
| **Mode and number of proofs:**
|    ``provides(?atom,?atom)`` - ``zero_or_more``

| **Exceptions:**
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``
|    ``Pack`` is neither a variable nor an atom:
|        ``type_error(atom,Pack)``


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

.. index:: lint/1
.. _registries/0::lint/1:

``lint/1``
^^^^^^^^^^

Checks the registry specification. Fails if the registry is not defined or if linting detects errors.

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

| **Template:**
|    ``lint(Registry)``
| **Mode and number of proofs:**
|    ``lint(+atom)`` - ``zero_or_one``

| **Exceptions:**
|    ``Registry`` is a variable:
|        ``instantiation_error``
|    ``Registry`` is neither a variable nor an atom:
|        ``type_error(atom,Registry)``


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

.. index:: lint/0
.. _registries/0::lint/0:

``lint/0``
^^^^^^^^^^

Checks all registry specifications.

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

| **Mode and number of proofs:**
|    ``lint`` - ``one``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

