Peter Siebel - Practical Common Lisp

An existing symbol can be imported into another package by adding it to the package's name-to-symbol table. Thus, the same symbol can be present in multiple packages. Sometimes you'll import symbols simply because you want them to be accessible in the importing package without using their home package. Other times you'll import a symbol because only present symbols can be exported or be shadowing symbols. For instance, if a package needs to use two packages that have external symbols of the same name, one of the symbols must be imported into the using package in order to be added to its shadowing list and make the other symbol inaccessible.

Finally, a present symbol can be uninterned from a package, which causes it to be removed from the name-to-symbol table and, if it's a shadowing symbol, from the shadowing list. You might unintern a symbol from a package to resolve a conflict between the symbol and an external symbol from a package you want to use. A symbol that isn't present in any package is called an uninterned symbol, can no longer be read by the reader, and will be printed using the #:foosyntax.

In the next section I'll show you how to define your own packages, including how to make one package use another and how to export, shadow, and import symbols. But first let's look at a few packages you've been using already. When you first start Lisp, the value of *PACKAGE* is typically the COMMON-LISP-USERpackage, also known as CL-USER. [222] Every package has one official name and zero or more nicknames that can be used anywhere you need to use the package name, such as in package-qualified names or to refer to the package in a DEFPACKAGE or IN-PACKAGE form. CL-USERuses the package COMMON-LISP, which exports all the names defined by the language standard. Thus, when you type an expression at the REPL, all the names of standard functions, macros, variables, and so on, will be translated to the symbols exported from COMMON-LISP, and all other names will be interned in the COMMON-LISP-USERpackage. For example, the name *PACKAGE* is exported from COMMON-LISP—if you want to see the value of *PACKAGE* , you can type this:

CL-USER> *package*

#

because COMMON-LISP-USERuses COMMON-LISP. Or you can use a package-qualified name.

CL-USER> common-lisp:*package*

#

You can even use COMMON-LISP's nickname, CL.

CL-USER> cl:*package*

#

But *X*isn't a symbol in COMMON-LISP, so you if type this:

CL-USER> (defvar *x* 10)

*X*

the reader reads DEFVAR as the symbol from the COMMON-LISPpackage and *X*as a symbol in COMMON-LISP-USER.

The REPL can't start in the COMMON-LISPpackage because you're not allowed to intern new symbols in it; COMMON-LISP-USERserves as a "scratch" package where you can create your own names while still having easy access to all the symbols in COMMON-LISP. [223] COMMON-LISP-USER is also allowed to provide access to symbols exported by other implementation-defined packages. While this is intended as a convenience for the user—it makes implementation-specific functionality readily accessible—it can also cause confusion for new Lispers: Lisp will complain about an attempt to redefine some name that isn't listed in the language standard. To see what packages COMMON-LISP-USER inherits symbols from in a particular implementation, evaluate this expression at the REPL: (mapcar #'package-name (package-use-list :cl-user)) And to find out what package a symbol came from originally, evaluate this: (package-name (symbol-package 'some-symbol)) with some-symbol replaced by the symbol in question. For instance: (package-name (symbol-package 'car)) ==> "COMMON-LISP" (package-name (symbol-package 'foo)) ==> "COMMON-LISP-USER" Symbols inherited from implementation-defined packages will return some other value. Typically, all packages you'll define will also use COMMON-LISP, so you don't have to write things like this:

(cl:defun (x) (cl:+ x 2))

The third standard package is the KEYWORD package, the package the Lisp reader uses to intern names starting with colon. Thus, you can also refer to any keyword symbol with an explicit package qualification of keywordlike this:

CL-USER> :a

:A

CL-USER> keyword:a

:A

CL-USER> (eql :a keyword:a)

T

Working in COMMON-LISP-USERis fine for experiments at the REPL, but once you start writing actual programs you'll want to define new packages so different programs loaded into the same Lisp environment don't stomp on each other's names. And when you write libraries that you intend to use in different contexts, you'll want to define separate packages and then export the symbols that make up the libraries' public APIs.

However, before you start defining packages, it's important to understand one thing about what packages do not do. Packages don't provide direct control over who can call what function or access what variable. They provide you with basic control over namespaces by controlling how the reader translates textual names into symbol objects, but it isn't until later, in the evaluator, that the symbol is interpreted as the name of a function or variable or whatever else. Thus, it doesn't make sense to talk about exporting a function or a variable from a package. You can export symbols to make certain names easier to refer to, but the package system doesn't allow you to restrict how those names are used. [224] This is different from the Java package system, which provides a namespace for classes but is also involved in Java's access control mechanism. The non-Lisp language with a package system most like Common Lisp's packages is Perl.

With that in mind, you can start looking at how to define packages and tie them together. You define new packages with the macro DEFPACKAGE , which allows you to not only create the package but to specify what packages it uses, what symbols it exports, and what symbols it imports from other packages and to resolve conflicts by creating shadowing symbols. [225] All the manipulations performed by DEFPACKAGE can also be performed with functions that man- ipulate package objects. However, since a package generally needs to be fully defined before it can be used, those functions are rarely used. Also, DEFPACKAGE takes care of performing all the package manipulations in the right order—for instance, DEFPACKAGE adds symbols to the shadowing list before it tries to use the used packages.

I'll describe the various options in terms of how you might use packages while writing a program that organizes e-mail messages into a searchable database. The program is purely hypothetical, as are the libraries I'll refer to—the point is to look at how the packages used in such a program might be structured.

The first package you'd need is one to provide a namespace for the application—you want to be able to name your functions, variables, and so on, without having to worry about name collisions with unrelated code. So you'd define a new package with DEFPACKAGE .