Common Lisp the Language, 2nd Edition

Next: Package System Functions Up: Packages Previous: Name Conflicts

# 11.6. Built-in Packages

The following packages, at least, are built into every Common Lisp system.

`lisp`
  The package named `lisp` contains the primitives of the Common Lisp system. Its external symbols include all of the user-visible functions and global variables that are present in the Common Lisp system, such as `car`, `cdr`, and `*package*`. Almost all other packages will want to use `lisp` so that these symbols will be accessible without qualification.

`user`
  The `user` package is, by default, the current package at the time a Common Lisp system starts up. This package uses the `lisp` package.

X3J13 voted in March 1989 (LISP-PACKAGE-NAME) to specify that the forthcoming ANSI Common Lisp will use the package name `common-lisp` instead of `lisp` and the package name `common-lisp-user` instead of `user`. The purpose is to allow a single Lisp system to support both ``old'' Common Lisp and ``new'' ANSI Common Lisp simultaneously despite the fact that in some cases the two languages use the same names for incompatible purposes. (That's what packages are for!)

`common-lisp`
  The package named `common-lisp` contains the primitives of the ANSI Common Lisp system (as opposed to a Common Lisp system based on the 1984 specification). Its external symbols include all of the user-visible functions and global variables that are present in the ANSI Common Lisp system, such as `car`, `cdr`, and `*package*`. Note, however, that the home package of such symbols is not necessarily the `common-lisp` package (this makes it easier for symbols such as `t` and `lambda` to be shared between the `common-lisp` package and another package, possibly one named `lisp`). Almost all other packages ought to use `common-lisp` so that these symbols will be accessible without qualification. This package has the nickname `cl`.

`common-lisp-user`
  The `common-lisp-user` package is, by default, the current package at the time an ANSI Common Lisp system starts up. This package uses the `common-lisp` package and has the nickname `cl-user`. It may contain other implementation-dependent symbols and may use other implementation-specific packages.

`keyword`
  This package contains all of the keywords used by built-in or user-defined Lisp functions. Printed symbol representations that start with a colon are interpreted as referring to symbols in this package, which are always external symbols. All symbols in this package are treated as constants that evaluate to themselves, so that the user can type `:foo` instead of `':foo`.

`system`
  This package name is reserved to the implementation. Normally this is used to contain names of implementation-dependent system-interface functions. This package uses `lisp` and has the nickname `sys`.

X3J13 voted in January 1989 (PACKAGE-CLUTTER) to modify the requirements on the built-in packages so as to limit what may appear in the `common-lisp` package and to lift the requirement that every implementation have a package named `system`. The details are as follows.

Not only must the `common-lisp` package in any given implementation contain all the external symbols prescribed by the standard; the `common-lisp` package moreover may not contain any external symbol that is not prescribed by the standard. However, the `common-lisp` package may contain additional internal symbols, depending on the implementation.

An external symbol of the `common-lisp` package may not have a function, macro, or special form definition, or a top-level value, or a `special` proclamation, or a type definition, unless specifically permitted by the standard. Programmers may validly rely on this fact; for example, `fboundp` is guaranteed to be false for all external symbols of the `common-lisp` package except those explicitly specified in the standard to name functions, macros, and special forms. Similarly, `boundp` will be false of all such external symbols except those documented to be variables or constants.

Portable programs may use external symbols in the `common-lisp` package that are not documented to be constants or variables as names of local lexical variables with the presumption that the implementation has not proclaimed such variables to be special; this legitimizes the common practice of using such names as `list` and `string` as names for local variables.

A valid implementation may initially have properties on any symbol, or dynamically put new properties on symbols (even user-created symbols), as long as no property indicator used for this purpose is an external symbol of any package defined by the standard or a symbol that is accessible from the `common-lisp-user` package or any package defined by the user.

This vote eliminates the requirement that every implementation have a predefined package named `system`. An implementation may provide any number of predefined packages; these should be described in the documentation for that implementation.

The `common-lisp-user` package may contain symbols not described by the standard and may use other implementation-specific packages.

X3J13 voted in March 1989 (LISP-SYMBOL-REDEFINITION) to restrict user programs from performing certain actions that might interfere with built-in facilities or interact badly with them. Except where explicitly allowed, the consequences are undefined if any of the following actions are performed on a symbol in the `common-lisp` package.

- binding or altering its value (lexically or dynamically)
- defining or binding it as a function
- defining or binding it as a macro
- defining it as a type specifier (`defstruct`, `defclass`, `deftype`)
- defining it as a structure (`defstruct`)
- defining it as a declaration
- dsing it as a symbol macro
- altering its print name
- altering its package
- tracing it
- declaring or proclaiming it special or lexical
- declaring or proclaiming its `type` or `ftype`
- removing it from the package `common-lisp`

X3J13 also voted in June 1989 (DEFINE-COMPILER-MACRO) to add to this list the item

- defining it as a compiler macro

If such a symbol is not globally defined as a variable or a constant, a user program is allowed to lexically bind it and declare the `type` of that binding.

If such a symbol is not defined as a function, macro, or special form, a user program is allowed to (lexically) bind it as a function and to declare the `ftype` of that binding and to trace that binding.

If such a symbol is not defined as a function, macro, or special form, a user program is allowed to (lexically) bind it as a macro.

As an example, the behavior of the code fragment

    (flet ((open (filename &key direction)
             (format t "~%OPEN was called.")
             (open filename :direction direction)))
      (with-open-file (x "frob" :direction ':output)
        (format t "~%Was OPEN called?")))

is undefined. Even in a ``reasonable'' implementation, for example, the macro expansion of `with-open-file` might refer to the `open` function and might not. However, the preceding rules eliminate the burden of deciding whether an implementation is reasonable. The code fragment violates the rules; officially its behavior is therefore completely undefined, and that's that.

Note that ``altering the property list'' is not in the list of proscribed actions, so a user program is permitted to add properties to or remove properties from symbols in the `common-lisp` package.

Next: Package System Functions Up: Packages Previous: Name Conflicts