---

6 Using Epkg Objects

Most users won’t have to access the Epkg objects directly and can just use the commands described in the preceding sections, but if you would like to extend Epkg, then you should know about the following functions.

Epkg objects are implemented using Eieio, which more or less is an implementation of CLOS. It’s useful to learn about that, but to get started you may just use oref to obtain information about a package, e.g., (oref (epkg "magit") url).

Function: epkg name ¶

This function returns an epkg-package object for the package named NAME. NAME is the name of a package, a string.

Function: epkgs &optional select types ¶

This function returns a list of epkg-package objects, column values or database rows. The list is ordered by the package names in ascending order.

If optional SELECT is non-nil, then it has to be symbol naming a column in the packages table or a vector of such columns. In those cases the returned value is a list of column values or a list of database rows. If SELECT is nil, return a list of objects.

If optional TYPES is non-nil, then it has to be a vector of package types, such as github. To include subtypes, add an asterisk to the symbol name, e.g., mirrored*. For backward compatibility, TYPES can also be a list of predicate functions epkg-TYPE-package-p or epkg-TYPE-package--eieio-childp, or a single such function.

This function is more limited than epkg-sql but it’s often much less verbose. For example (epkgs nil [gitlab]) returns the same value as:

(mapcar (apply-partially #'closql--remake-instance
                         'epkg-package (epkg-db))
        (epkg-sql [:select * :from packages
                   :where class :in $v1
                   :order-by [(asc name)]]
                  (closql-where-class-in 'gitlab)))

While it is possible to get a list of provided or required features, or a package’s type using oref, the values of these slots contains additional information, which is mostly useful when maintaining the Emacsmirror, but not in a client. And the required slot only lists features but not the packages that provide them. The following functions return these values in a form that is generally more useful.

Function: epkg-provided package &optional include-bundled ¶

This function returns a list of features provided by the package PACKAGE. PACKAGE is an epkg-package object or a package name, a string.

Bundled features are excluded from the returned list unless optional INCLUDE-BUNDLED is non-nil.

Function: epkg-required package ¶

This function returns a list of packages and features required by the package PACKAGE. PACKAGE is an epkg-package object or a package name, a string.

Each element has the form (DEPENDENCY FEATURES), where DEPENDENCY is the name of a required package, a string, and FEATURES is a list of features provided by DEPENDENCY and required by PACKAGE.

If a feature is represented using a symbol, then that indicates that it is a mandatory dependency; if a string is used, then it is an optional dependency.

There may be a single element (nil FEATURES), which means that it is unknown which package or packages provide the feature or features listed in FEATURES.

Function: epkg-provided-by feature ¶

Return the name of the package provided by FEATURE. FEATURE has to be a symbol.

Function: epkg-reverse-dependencies package ¶

This function returns a list of packages that depend on PACKAGE. PACKAGE is an epkg-package object or a package name, a string.

Each element has the form (DEPENDANT FEATURES), where DEPENDANT is the name of a package that depends on PACKAGE, a string, and FEATURES is a list of features provided by PACKAGE and required by DEPENDANT.

If a feature is represented using a symbol, then that indicates that it is a mandatory dependency; if a string is used, then it is an optional dependency.

Function: epkg-type arg ¶

This function returns the type of the object or class ARG.

ARG has to be the class epkg-package, a subclass of that, an epkg-package object, or an object of a subclass. The type represents the class and is used in the user interface, where it would be inconvenient to instead use the actual class name, because the latter is longer and an implementation detail.

Function: epkg-package-types subtypes ¶

This function returns a list of all package types.

If optional SUBTYPES is non-nil, then it also returns symbols of the form TYPE*, which stands for "TYPE and its subtypes".

Function: epkg-read-type prompt &optional default subtypes ¶

This function reads an Epkg type in the minibuffer and returns it as a symbol.

If optional DEFAULT is non-nil, then that is offered as default choice. If optional CHILDP is non-nil, then entries of the form TYPE*, which stands for "TYPE and its subtypes", are also offered as completion candidates.

Function: epkg-read-package prompt &optional default ¶

This function reads the name of an Epkg package in the minibuffer and returns it as a string.

Optional DEFAULT, if non-nil, is offered as default choice.