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 #:foo syntax.
Three Standard Packages
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-USER package, also known as CL-USER.[222] CL-USER uses 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-USER package. 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*
#<The COMMON-LISP-USER package>
because COMMON-LISP-USER uses COMMON-LISP. Or you can use a package-qualified name.
CL-USER> common-lisp:*package*
#<The COMMON-LISP-USER package>
You can even use COMMON-LISP's nickname, CL.
CL-USER> cclass="underline" *package*
#<The COMMON-LISP-USER 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-LISP package and *X* as a symbol in COMMON-LISP-USER.
The REPL can't start in the COMMON-LISP package because you're not allowed to intern new symbols in it; COMMON-LISP-USER serves as a "scratch" package where you can create your own names while still having easy access to all the symbols in COMMON-LISP.[223] Typically, all packages you'll define will also use COMMON-LISP, so you don't have to write things like this:
(cclass="underline" defun (x) (cclass="underline" + 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 keyword like this:
CL-USER> :a
:A
CL-USER> keyword:a
:A
CL-USER> (eql :a keyword:a)
T
Defining Your Own Packages
Working in COMMON-LISP-USER is 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]
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]
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.
If the application is simple enough to be written with no libraries beyond the facilities provided by the language itself, you could define a simple package like this:
(defpackage :com.gigamonkeys.email-db
(:use :common-lisp))
This defines a package, named COM.GIGAMONKEYS.EMAIL-DB, that inherits all the symbols exported by the COMMON-LISP package.[226]
You actually have several choices of how to represent the names of packages and, as you'll see, the names of symbols in a DEFPACKAGE. Packages and symbols are named with strings. However, in a DEFPACKAGE form, you can specify the names of packages and symbols with string designators. A string designator is either a string, which designates itself; a symbol, which designates its name; or a character, which designates a one-character string containing just the character. Using keyword symbols, as in the previous DEFPACKAGE, is a common style that allows you to write the names in lowercase—the reader will convert the names to uppercase for you. You could also write the DEFPACKAGE with strings, but then you have to write them in all uppercase, because the true names of most symbols and packages are in fact uppercase because of the case conversion performed by the reader.[227]
(defpackage "COM.GIGAMONKEYS.EMAIL-DB"
(:use "COMMON-LISP"))
You could also use nonkeyword symbols—the names in DEFPACKAGE aren't evaluated—but then the very act of reading the DEFPACKAGE form would cause those symbols to be interned in the current package, which at the very least will pollute that namespace and may also cause problems later if you try to use the package.[228]
To read code in this package, you need to make it the current package with the IN-PACKAGE macro:
(in-package :com.gigamonkeys.email-db)
If you type this expression at the REPL, it will change the value of *PACKAGE*, affecting how the REPL reads subsequent expressions, until you change it with another call to IN-PACKAGE. Similarly, if you include an IN-PACKAGE in a file that's loaded with LOAD or compiled with COMPILE-FILE, it will change the package, affecting the way subsequent expressions in the file are read.[229]
222
Every package has one official name and zero or more DEFPACKAGE or IN-PACKAGE form.
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.
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.
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.
226
In many Lisp implementations the :use clause is optional if you want only to :use COMMON-LISP—if it's omitted, the package will automatically inherit names from an implementation-defined list of packages that will usually include COMMON-LISP. However, your code will be more portable if you always explicitly specify the packages you want to :use. Those who are averse to typing can use the package's nickname and write (:use :cl).
227
Using keywords instead of strings has another advantage—Allegro provides a "modern mode" Lisp in which the reader does no case conversion of names and in which, instead of a COMMON-LISP package with uppercase names, provides a common-lisp package with lowercase names. Strictly speaking, this Lisp isn't a conforming Common Lisp since all the names in the standard are defined to be uppercase. But if you write your DEFPACKAGE forms using keyword symbols, they will work both in Common Lisp and in this near relative.
228
Some folks, instead of keywords, use uninterned symbols, using the #: syntax.
(defpackage #:com.gigamonkeys.email-db
(:use #:common-lisp))
This saves a tiny bit of memory by not interning any symbols in the keyword package—the symbol can become garbage after DEFPACKAGE (or the code it expands into) is done with it. However, the difference is so slight that it really boils down to a matter of aesthetics.
229
The reason to use IN-PACKAGE instead of just SETFing *PACKAGE* is that IN-PACKAGE expands into code that will run when the file is compiled by COMPILE-FILE as well as when the file is loaded, changing the way the reader reads the rest of the file during compilation.