Next: , Previous: , Up: Top   [Contents]


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 optain 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 predicates

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

If optional SELECT is non-nil, then it has to be a list of columns of the packages table. In that case the returned value is a list of database rows.

If optional PREDICATES is non-nil, then it has to be a list of package class predicate functions, or a single such function. Valid functions are named either epkg-TYPE-package-p or epkg-TYPE-package--eieio-childp. Only packages are returned for which one of these predicates returns non-nil.

This function is more limited than epkg-sql but it’s often much less verbose. For example (epkgs nil 'epkg-gitlab-package-p) 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 'epkg-gitlab-package)))

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.


Next: , Previous: , Up: Top   [Contents]