Peter Siebel - Practical Common Lisp

(defpackage :com.gigamonkeys.email-db

(:use :common-lisp :com.gigamonkeys.text-db)

(:import-from :com.acme.email :parse-email-address))

Now anywhere the name parse-email-addressappears in code read in the COM.GIGAMONKEYS.EMAIL-DBpackage, it will be read as the symbol from COM.ACME.EMAIL. If you need to import more than one symbol from a single package, you can include multiple names after the package name in a single :import-fromclause. A DEFPACKAGE can also include multiple :import-fromclauses in order to import symbols from different packages.

Occasionally you'll run into the opposite situation—a package may export a bunch of names you want to use and a few you don't. Rather than listing all the symbols you do want to use in an :import-fromclause, you can instead :usethe package and then list the names you don't want to inherit in a :shadowclause. For instance, suppose the COM.ACME.TEXTpackage exports a bunch of names of functions and classes used in text processing. Further suppose that most of these functions and classes are ones you'll want to use in your code, but one of the names, build-index, conflicts with a name you've already used. You can make the build-indexfrom COM.ACME.TEXTinaccessible by shadowing it.

(defpackage :com.gigamonkeys.email-db

(:use

:common-lisp

:com.gigamonkeys.text-db

:com.acme.text)

(:import-from :com.acme.email :parse-email-address)

(:shadow :build-index))

The :shadowclause causes a new symbol named BUILD-INDEXto be created and added directly to COM.GIGAMONKEYS.EMAIL-DB's name-to-symbol map. Now if the reader reads the name BUILD-INDEX, it will translate it to the symbol in COM.GIGAMONKEYS.EMAIL-DB's map, rather than the one that would otherwise be inherited from COM.ACME.TEXT. The new symbol is also added to a shadowing symbols list that's part of the COM.GIGAMONKEYS.EMAIL-DBpackage, so if you later use another package that also exports a BUILD-INDEXsymbol, the package system will know there's no conflict—that you want the symbol from COM.GIGAMONKEYS.EMAIL-DBto be used rather than any other symbols with the same name inherited from other packages.

A similar situation can arise if you want to use two packages that export the same name. In this case the reader won't know which inherited name to use when it reads the textual name. In such situations you must resolve the ambiguity by shadowing the conflicting names. If you don't need to use the name from either package, you could shadow the name with a :shadowclause, creating a new symbol with the same name in your package. But if you actually want to use one of the inherited symbols, then you need to resolve the ambiguity with a :shadowing-import-fromclause. Like an :import-fromclause, a :shadowing-import-fromclause consists of a package name followed by the names to import from that package. For instance, if COM.ACME.TEXTexports a name SAVEthat conflicts with the name exported from COM.GIGAMONKEYS.TEXT-DB, you could resolve the ambiguity with the following DEFPACKAGE :

(defpackage :com.gigamonkeys.email-db

(:use

:common-lisp

:com.gigamonkeys.text-db

:com.acme.text)

(:import-from :com.acme.email :parse-email-address)

(:shadow :build-index)

(:shadowing-import-from :com.gigamonkeys.text-db :save))

That covers the basics of how to use packages to manage namespaces in several common situations. However, another level of how to use packages is worth discussing—the raw mechanics of how to organize code that uses different packages. In this section I'll discuss a few rules of thumb about how to organize code—where to put your DEFPACKAGE forms relative to the code that uses your packages via IN-PACKAGE .

Because packages are used by the reader, a package must be defined before you can LOAD or COMPILE-FILE a file that contains an IN-PACKAGE expression switching to that package. Packages also must be defined before other DEFPACKAGE forms can refer to them. For instance, if you're going to :use COM.GIGAMONKEYS.TEXT-DBin COM.GIGAMONKEYS.EMAIL-DB, then COM.GIGAMONKEYS.TEXT-DB's DEFPACKAGE must be evaluated before the DEFPACKAGE of COM.GIGAMONKEYS.EMAIL-DB.

The best first step toward making sure packages exist when they need to is to put all your DEFPACKAGE s in files separate from the code that needs to be read in those packages. Some folks like to create a foo-package.lispfile for each individual package, and others create a single packages.lispthat contains all the DEFPACKAGE forms for a group of related packages. Either approach is reasonable, though the one-file-per-package approach also requires that you arrange to load the individual files in the right order according to the interpackage dependencies.

Either way, once all the DEFPACKAGE forms have been separated from the code that will be read in the packages they define, you can arrange to LOAD the files containing the DEFPACKAGE s before you compile or load any of the other files. For simple programs you can do this by hand: simply LOAD the file or files containing the DEFPACKAGE forms, possibly compiling them with COMPILE-FILE first. Then LOAD the files that use those packages, again optionally compiling them first with COMPILE-FILE . Note, however, that the packages don't exist until you LOAD the package definitions, either the source or the files produced by COMPILE-FILE . Thus, if you're compiling everything, you must still LOAD all the package definitions before you can COMPILE-FILE any files to be read in the packages.

Doing these steps by hand will get tedious after a while. For simple programs you can automate the steps by writing a file, load.lisp, that contains the appropriate LOAD and COMPILE-FILE calls in the right order. Then you can just LOAD that file. For more complex programs you'll want to use a system definition facility to manage loading and compiling files in the right order. [232] The code for the "Practical" chapters, available from this book's Web site, uses the ASDF system definition library. ASDF stands for Another System Definition Facility.

The other key rule of thumb is that each file should contain exactly one IN-PACKAGE form, and it should be the first form in the file other than comments. Files containing DEFPACKAGE forms should start with (in-package "COMMON-LISP-USER"), and all other files should contain an IN-PACKAGE of one of your packages.