use-package

use-package Function

Syntax:

use-package packages-to-use &optional package → t

Arguments and Values:

packages-to-use—a designator for a list of package designators. The KEYWORD package may not be supplied.

package—a package designator . The default is the current package. The package cannot be the KEYWORD package.

Description:

use-package causes package to inherit all the external symbols of packages-to-use. The inherited symbols become accessible as internal symbols of package.

Packages-to-use are added to the use list of package if they are not there already. All external symbols in packages-to-use become accessible in package as internal symbols. use-package does not cause any new symbols to be present in package but only makes them accessible by inheritance.

use-package checks for name conflicts between the newly imported symbols and those already accessible in package. A name conflict in use-package between two external symbols inherited by package from packages-to-use may be resolved in favor of either symbol by importing one of them into package and making it a shadowing symbol.

Examples:

(export (intern "LAND-FILL" (make-package ’trash)) ’trash) → T 
(find-symbol "LAND-FILL" (make-package ’temp)) → NIL, NIL 
(package-use-list ’temp) → (#<PACKAGE "TEMP">) 
(use-package ’trash ’temp) → T 
(package-use-list ’temp) → (#<PACKAGE "TEMP"> #<PACKAGE "TRASH">) 
(find-symbol "LAND-FILL" ’temp) → TRASH:LAND-FILL, :INHERITED 

Side Effects:

The use list of package may be modified.

See Also:

unuse-package, package-use-list, Section 11.1 (Package Concepts)

Notes:

It is permissible for a package P₁ to use a package P₂ even if P₂ already uses P₁. The using of packages is not transitive, so no problem results from the apparent circularity.

defpackage

Expanded Reference: use-package

Basic Usage: Inheriting Symbols from Another Package

use-package causes a package to inherit all external symbols from the specified package(s).

(defpackage "TOOLS-UP" (:use) (:export "HAMMER" "WRENCH"))
(make-package "WORKSHOP" :use '())

(find-symbol "HAMMER" "WORKSHOP")
=> NIL
=> NIL

(use-package "TOOLS-UP" "WORKSHOP")
=> T

(find-symbol "HAMMER" "WORKSHOP")
;; => TOOLS-UP:HAMMER
;; => :INHERITED

(find-symbol "WRENCH" "WORKSHOP")
;; => TOOLS-UP:WRENCH
;; => :INHERITED

Using Multiple Packages at Once

use-package accepts a list of packages.

(defpackage "PKG-A-UP" (:use) (:export "FOO"))
(defpackage "PKG-B-UP" (:use) (:export "BAR"))
(make-package "PKG-C-UP" :use '())

(use-package '("PKG-A-UP" "PKG-B-UP") "PKG-C-UP")
=> T

(find-symbol "FOO" "PKG-C-UP")
;; => PKG-A-UP:FOO
;; => :INHERITED
(find-symbol "BAR" "PKG-C-UP")
;; => PKG-B-UP:BAR
;; => :INHERITED

The Use List is Updated

(defpackage "LIB-UP" (:use) (:export "FUNC"))
(make-package "CLIENT-UP" :use '())

(package-use-list "CLIENT-UP")
=> ()

(use-package "LIB-UP" "CLIENT-UP")
=> T

(mapcar #'package-name (package-use-list "CLIENT-UP"))
=> ("LIB-UP")

Using a Package That is Already Used is Harmless

(defpackage "ALREADY-UP" (:use) (:export "X"))
(defpackage "USER-UP" (:use "ALREADY-UP"))

;; Using it again is a no-op
(use-package "ALREADY-UP" "USER-UP")
=> T

Only External Symbols are Inherited

Internal symbols of the used package are not accessible in the using package.

(defpackage "PARTIAL-UP" (:use) (:export "VISIBLE"))
(intern "HIDDEN" "PARTIAL-UP")

(make-package "VIEWER-UP" :use '())
(use-package "PARTIAL-UP" "VIEWER-UP")

(find-symbol "VISIBLE" "VIEWER-UP")
;; => PARTIAL-UP:VISIBLE
;; => :INHERITED
(find-symbol "HIDDEN" "VIEWER-UP")
;; => NIL
;; => NIL