object

# `packs`

Pack handling predicates.

Availability:
`logtalk_load(packs(loader))`
Author: Paulo Moura
Version: 0:84:0
Date: 2025-02-06
Compilation flags:
`static, context_switching_calls`
Imports:
`public` packs_common
`public` options
Uses:
list
logtalk
os
registries
type
user
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 directory/1 directory/2 help/0 logtalk_packs/0 logtalk_packs/1 option/2 option/3 pin/0 pin/1 pinned/1 prefix/0 prefix/1 readme/1 readme/2 reset/0 setup/0 unpin/0 unpin/1 valid_option/1 valid_options/1 verify_commands_availability/0

## Public predicates

### `available/2`

Enumerates, by backtracking, all available packs.

Compilation flags:
`static`
Template:
`available(Registry,Pack)`
Mode and number of proofs:
`available(?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)`

### `available/1`

Lists all the packs that are available for installation from the given registry.

Compilation flags:
`static`
Template:
`available(Registry)`
Mode and number of proofs:
`available(+atom)` - `one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`

### `available/0`

Lists all the packs that are available for installation from all defined registries.

Compilation flags:
`static`
Mode and number of proofs:
`available` - `one`

### `installed/4`

Enumerates by backtracking all installed packs.

Compilation flags:
`static`
Template:
`installed(Registry,Pack,Version,Pinned)`
Mode and number of proofs:
`installed(?atom,?atom,?compound,?boolean)` - `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)`
`Version` is neither a variable nor a compound term:
`type_error(compound,Version)`
`Pinned` is neither a variable nor a boolean:
`type_error(boolean,Pinned)`

### `installed/3`

Enumerates by backtracking all installed packs.

Compilation flags:
`static`
Template:
`installed(Registry,Pack,Version)`
Mode and number of proofs:
`installed(?atom,?atom,?compound)` - `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)`
`Version` is neither a variable nor a compound term:
`type_error(compound,Version)`

### `installed/1`

Lists all the packs that are installed from the given registry. Fails if the registry is unknown.

Compilation flags:
`static`
Template:
`installed(Registry)`
Mode and number of proofs:
`installed(+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`

### `installed/0`

Lists all the packs that are installed.

Compilation flags:
`static`
Mode and number of proofs:
`installed` - `one`

### `outdated/4`

Enumerates by backtracking all installed but outdated packs (together with the current version installed and the latest version available).

Compilation flags:
`static`
Template:
`outdated(Registry,Pack,Version,LatestVersion)`
Mode and number of proofs:
`outdated(?atom,?atom,?compound,?compound)` - `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)`
`Version` is neither a variable nor a compound term:
`type_error(compound,Version)`
`LatestVersion` is neither a variable nor a compound term:
`type_error(compound,LatestVersion)`

### `outdated/1`

Lists all the packs from the given registry that are installed but outdated.

Compilation flags:
`static`
Template:
`outdated(Registry)`
Mode and number of proofs:
`outdated(+atom)` - `one`
Exceptions:
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`

### `outdated/0`

Lists all the packs that are installed but outdated.

Compilation flags:
`static`
Mode and number of proofs:
`outdated` - `one`

### `orphaned/2`

Lists all the packs that are installed but whose registry is no longer defined.

Compilation flags:
`static`
Template:
`orphaned(Registry,Pack)`
Mode and number of proofs:
`orphaned(?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)`

### `orphaned/0`

Lists all the packs that are installed but whose registry is no longer defined.

Compilation flags:
`static`
Mode and number of proofs:
`orphaned` - `one`

### `versions/3`

Returns a list of all available pack versions. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`versions(Registry,Pack,Versions)`
Mode and number of proofs:
`versions(+atom,+atom,-list)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `describe/2`

Describes a registered pack, including installed version if applicable. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`describe(Registry,Pack)`
Mode and number of proofs:
`describe(+atom,+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `describe/1`

Describes a registered pack, including installed version if applicable. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`describe(Pack)`
Mode and number of proofs:
`describe(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `search/1`

Searches packs whose name or description includes the search term (case sensitive).

Compilation flags:
`static`
Template:
`search(Term)`
Mode and number of proofs:
`search(+atom)` - `one`
Exceptions:
`Term` is a variable:
`instantiation_error`
`Term` is neither a variable nor an atom:
`type_error(atom,Term)`

### `install/4`

Installs a new pack using the specified options. Fails if the pack is unknown or already installed but not using `update(true)` or `force(true)` options. Fails also if the pack version is unknown.

Compilation flags:
`static`
Template:
`install(Registry,Pack,Version,Options)`
Mode and number of proofs:
`install(+atom,+atom,++compound,++list(compound))` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`
`Version` is a variable:
`instantiation_error`
`Version` is neither a variable nor a valid version:
`type_error(pack_version,Version)`
`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:

> - `update(Boolean)` option: Update pack if already installed. Default is `false`. Overrides the `force/1` option.

> - `force(Boolean)` option: Force pack re-installation if already installed. Default is `false`.

> - `compatible(Boolean)` option: Restrict installation to compatible packs. Default is `true`.

> - `clean(Boolean)` option: Clean pack archive after installation. Default is `false`.

> - `verbose(Boolean)` option: Verbose installing steps. Default is `false`.

> - `checksum(Boolean)` option: Verify pack archive checksum. Default is `true`.

> - `checksig(Boolean)` option: Verify pack archive signature. Default is `false`.

> - `git(Atom)` option: Extra command-line options. Default is `''`.

> - `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 `''`.

### `install/3`

Installs the specified version of a pack from the given registry using default options. Fails if the pack is already installed or unknown. Fails also if the pack version is unknown.

Compilation flags:
`static`
Template:
`install(Registry,Pack,Version)`
Mode and number of proofs:
`install(+atom,+atom,?compound)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`
`Version` is a variable:
`instantiation_error`
`Version` is neither a variable nor a valid version:
`type_error(pack_version,Version)`

### `install/2`

Installs the latest version of a pack from the given registry using default options. Fails if the pack is already installed or unknown.

Compilation flags:
`static`
Template:
`install(Registry,Pack)`
Mode and number of proofs:
`install(+atom,+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `install/1`

Installs a pack (if its name is unique among all registries) using default options. Fails if the pack is already installed or unknown. Fails also if the pack is available from multiple registries.

Compilation flags:
`static`
Template:
`install(Pack)`
Mode and number of proofs:
`install(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is not an atom:
`type_error(atom,Pack)`

### `update/3`

Updates an outdated pack to the specified version using the specified options. Fails if the pack or the pack version is unknown or if the pack is not installed. Fails also if the pack is orphaned or pinned and not using a `force(true)` option.

Compilation flags:
`static`
Template:
`update(Pack,Version,Options)`
Mode and number of proofs:
`update(+atom,++callable,++list(callable))` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`
`Version` is a variable:
`instantiation_error`
`Version` is neither a variable nor a valid version:
`type_error(pack_version,Version)`
`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:

> - `install(Boolean)` option: Install pack latest version if not already installed. Default is `false`.

> - `force(Boolean)` option: Force update if the pack is pinned or breaks installed packs. Default is `false`.

> - `compatible(Boolean)` option: Restrict updating to compatible packs. Default is `true`.

> - `clean(Boolean)` option: Clean pack archive after updating. Default is `false`.

> - `verbose(Boolean)` option: Verbose updating steps. Default is `false`.

> - `checksum(Boolean)` option: Verify pack archive checksum. Default is `true`.

> - `checksig(Boolean)` option: Verify pack archive signature. Default is `false`.

> - `git(Atom)` option: Extra command-line options. Default is `''`.

> - `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 `''`.

### `update/2`

Updates an outdated pack to its latest version using the specified options. Fails if the pack is orphaned, unknown, or not installed. Fails also if the pack is pinned and not using a `force(true)` option.

Compilation flags:
`static`
Template:
`update(Pack,Options)`
Mode and number of proofs:
`update(+atom,++list(callable))` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`
`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:

> - `install(Boolean)` option: Install pack latest version if not already installed. Default is `false`.

> - `force(Boolean)` option: Force update if the pack is pinned or breaks installed packs. Default is `false`.

> - `compatible(Boolean)` option: Restrict updating to compatible packs. Default is `true`.

> - `clean(Boolean)` option: Clean pack archive after updating. Default is `false`.

> - `verbose(Boolean)` option: Verbose updating steps. Default is `false`.

> - `checksum(Boolean)` option: Verify pack archive checksum. Default is `true`.

> - `checksig(Boolean)` option: Verify pack archive signature. Default is `false`.

> - `git(Atom)` option: Extra command-line options. Default is `''`.

> - `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 `''`.

### `update/1`

Updates an outdated pack to its latest version using default options. Fails if the pack is pinned, orphaned, not installed, unknown, or breaks installed packs.

Compilation flags:
`static`
Template:
`update(Pack)`
Mode and number of proofs:
`update(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `update/0`

Updates all outdated packs (that are not pinned) using default options.

Compilation flags:
`static`
Mode and number of proofs:
`update` - `zero_or_one`

### `uninstall/2`

Uninstalls a pack using the specified options. Fails if the pack is unknown or not installed. Fails also if the pack is pinned or have dependents and not using a `force(true)` option.

Compilation flags:
`static`
Template:
`uninstall(Pack,Options)`
Mode and number of proofs:
`uninstall(+atom,++list(compound))` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`
`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 pack is pinned. Default is `false`.

> - `clean(Boolean)` option: Clean pack archive after deleting. Default is `false`.

> - `verbose(Boolean)` option: Verbose uninstalling steps. Default is `false`.

### `uninstall/1`

Uninstalls a pack using default options. Fails if the pack is pinned, have dependents, not installed, or unknown.

Compilation flags:
`static`
Template:
`uninstall(Pack)`
Mode and number of proofs:
`uninstall(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `uninstall/0`

Uninstalls all packs using the `force(true)` option.

Compilation flags:
`static`
Mode and number of proofs:
`uninstall` - `zero_or_one`

### `clean/2`

Cleans all pack archives. Fails if the the pack is unknown.

Compilation flags:
`static`
Template:
`clean(Registry,Pack)`
Mode and number of proofs:
`clean(+atom,+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `clean/1`

Cleans all pack archives. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`clean(Pack)`
Mode and number of proofs:
`clean(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `clean/0`

Cleans all archives for all packs.

Compilation flags:
`static`
Mode and number of proofs:
`clean` - `one`

### `save/2`

Saves a list of all installed packs and registries plus pinning status to a file using the given options. Registries without installed packs are saved when using the option `save(all)` and skipped when using the option `save(installed)` (default).

Compilation flags:
`static`
Template:
`save(File,Options)`
Mode and number of proofs:
`save(+atom,++list(compound))` - `one_or_error`
Exceptions:
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` is an existing file but cannot be written:
`permission_error(open,source_sink,File)`
`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)`

### `save/1`

Saves a list of all installed packs and their registries plus pinning status to a file using default options.

Compilation flags:
`static`
Template:
`save(File)`
Mode and number of proofs:
`save(+atom)` - `one_or_error`
Exceptions:
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` is an existing file but cannot be written:
`permission_error(open,source_sink,File)`

### `restore/2`

Restores a list of registries and packs plus their pinning status from a file using the given options. Fails if restoring is not possible.

Compilation flags:
`static`
Template:
`restore(File,Options)`
Mode and number of proofs:
`restore(+atom,++list(compound))` - `zero_or_one_or_error`
Exceptions:
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` is an atom but not an existing file:
`existence_error(file,File)`
`File` is an existing file but cannot be read:
`permission_error(open,source_sink,File)`
`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 restoring if a registry is already defined or a pack is already installed. Default is `true`.

> - `compatible(Boolean)` option: Restrict installation to compatible packs. Default is `true`.

> - `clean(Boolean)` option: Clean registry and pack archives after restoring. Default is `false`.

> - `verbose(Boolean)` option: Verbose restoring steps. Default is `false`.

> - `checksum(Boolean)` option: Verify pack archive checksums. Default is `true`.

> - `checksig(Boolean)` option: Verify pack archive signatures. Default is `false`.

> - `git(Atom)` option: Extra command-line options. Default is `''`.

> - `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 `''`.

### `restore/1`

Restores a list of registries and packs plus their pinning status from a file using default options. Fails if restoring is not possible.

Compilation flags:
`static`
Template:
`restore(File)`
Mode and number of proofs:
`restore(+atom)` - `zero_or_one_or_error`
Exceptions:
`File` is a variable:
`instantiation_error`
`File` is neither a variable nor an atom:
`type_error(atom,File)`
`File` is an atom but not an existing file:
`existence_error(file,File)`
`File` is an existing file but cannot be read:
`permission_error(open,source_sink,File)`

### `dependents/3`

Returns a list of all installed packs that depend on the given pack from the given registry. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`dependents(Registry,Pack,Dependents)`
Mode and number of proofs:
`dependents(+atom,+atom,-list(atom))` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `dependents/2`

Prints a list of all installed packs that depend on the given pack from the given registry. Fails if the pack is unknown.

Compilation flags:
`static`
Template:
`dependents(Registry,Pack)`
Mode and number of proofs:
`dependents(+atom,+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `dependents/1`

Prints a list of all installed packs that depend on the given pack if unique from all defined registries. Fails if the pack is unknown or available from multiple registries.

Compilation flags:
`static`
Template:
`dependents(Pack)`
Mode and number of proofs:
`dependents(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `lint/2`

Checks the pack specification. Fails if the pack is unknown or if linting detects errors.

Compilation flags:
`static`
Template:
`lint(Registry,Pack)`
Mode and number of proofs:
`lint(+atom,+atom)` - `zero_or_one`
Exceptions:
`Registry` is a variable:
`instantiation_error`
`Registry` is neither a variable nor an atom:
`type_error(atom,Registry)`
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `lint/1`

Checks the pack specification. Fails if the pack is unknown, or available from multiple registries, or if linting detects errors.

Compilation flags:
`static`
Template:
`lint(Pack)`
Mode and number of proofs:
`lint(+atom)` - `zero_or_one`
Exceptions:
`Pack` is a variable:
`instantiation_error`
`Pack` is neither a variable nor an atom:
`type_error(atom,Pack)`

### `lint/0`

Checks all pack 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)