;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Introduction =Text: 3INTRODUCTION* A Lisp program is a collection of function definitions. The functions are known by their names, and so each must have its own name to identify it. Clearly a programmer must not use the same name for two different functions. The Lisp Machine consists of a huge Lisp environment, in which many programs must coexist. All of the operating system, the compiler, the editor, and a wide variety of programs are provided in the initial environment. Furthermore, every program that you use during a session must be loaded into the same environment. Each of these programs is composed of a group of functions; apparently each function must have its own distinct name to avoid conflicts. For example, if the compiler had a function named 2pull*, and you loaded a program which had its own function named 2pull*, the compiler's 2pull* would be redefined, probably breaking the compiler. It would not really be possible to prevent these conflicts, since the programs are written by many different people who could never get together to hash out who gets the privilege of using a specific name such as 2pull*. Now, if we are to enable two programs to coexist in the Lisp world, each with its own function 2pull*, then each program must have its own symbol named 2pull*, because there can't be two function definitions on the same symbol. This means that separate 1name spaces*--mappings between names and symbols--must be provided for the two programs. The package system is designed to do just that. Under the package system, the author of a program or a group of closely related programs identifies them together as a 1package*. The package system associates a distinct name space with each package. Here is an example: suppose there are two programs named 2chaos* and 2arpa*, for handling the Chaosnet and Arpanet respectively. The author of each program wants to have a function called 2get-packet*, which reads in a packet from the network (or something). Also, each wants to have a function called 2allocate-pbuf*, which allocates the packet buffer. Each ``get'' routine first allocates a packet buffer, and then reads bits into the buffer; therefore, each version of 2get-packet* should call the respective version of 2allocate-pbuf*. Without the package system, the two programs could not coexist in the same Lisp environment. But the package feature can be used to provide a separate name space for each program. What is required is to define a package named 2chaos* to contain the Chaosnet program, and another package 2arpa* to hold the Arpanet program. When the Chaosnet program is read into the machine, its symbols would be entered in the 2chaos* package's name space. So when the Chaosnet program's 2get-packet* referred to 2allocate-pbuf*, the 2allocate-pbuf* in the 2chaos* name space would be found, which would be the 2allocate-pbuf* of the Chaosnet program--the right one. Similarly, the Arpanet program's 2get-packet* would be read in using the 2arpa* package and would refer to the Arpanet program's 2allocate-pbuf*. In order to have multiple name spaces, the function 2intern*, which searches for a name, must allow the name space to be specified. 2intern* accepts an optional second argument which is the package to search. It's obvious that every file has to be loaded into the right package to serve its purpose. It may not be so obvious that every file must be compiled in the right package, but it's just as true. Luckily, this usually happens automatically. The system can get the package of a source file from its 3-*-* line. For instance, you can put at the front of your file a line such as 3; -*- Mode:Lisp; Package:System-Internals* The compiler puts the package name into the QFASL file for use when it is loaded. If a file doesn't have such a package specification in it, the system loads it into the current package and tells you what it did. =Node: 4The Current Package* =Text: 3THE CURRENT PACKAGE* At any time, one package is the 1current package*. By default, symbol lookup happens in the current package. 3package* 1Variable* 3*package** 1Variable* The value of the this variable is the current package. 2intern* searches this package if it is not given a second argument. Many other functions for operating on packages also use this as the default. Setting or binding the variable changes the current package. May the Goddess help you if you set it to something that isn't a package! The two names are synonymous. Each process or stack group can have its own setting for the current package by binding 2*package** with 2let*. The actual current package at any time is the value bound by the process which is running. The bindings of another process are irrelevant until the process runs. 3pkg-bind* 1pkg* 1body...* 1Macro* 1pkg* may be a package or a package name. The forms of the 1body* are evaluated sequentially with the variable 2*package** bound to the package named by 1pkg*. Example: 3(pkg-bind "ZWEI"* 3 (read-from-string function-name))* When a file is loaded, 2*package** is bound to the correct package for the file (the one named in the file's 3-*-* line). The Chaosnet program file has 2Package: Chaos;* in the attribute line, and therefore its symbols are looked up in the 2chaos* package. A QFASL file has an encoded representation of the 3-*-* line of the source file; it looks different, but it serves the same purpose. The current package is also relevant when you type Lisp expressions on the keyboard; it controls the reading of the symbols that you type. Initially it is the package 2user*. You can select a different package using 2pkg-goto*, or even by 2setq*ing 2*package**. If you are working with the Chaosnet program, it might be useful to type 2(pkg-goto 'chaos)* so that your symbols are found in the 2chaos* package by default. The Lisp listen loop binds 2*package** so that 2pkg-goto* in one Lisp listener does not affect others, or any other processes whatever. 3pkg-goto* 1package* &optional 1globally* Sets 2*package** to 1package*, if 1package* is suitable. (Autoexporting packages used by other packages are not suitable because it you could cause great troubles by interning new symbols in them). 1package* may be specified as a package object or the name of one. If 2globally* is non-2nil*, then this function also calls 2pkg-goto-globally* (see below) The Zmacs editor records the correct package for each buffer; it is determined from the file's 3-*-* line. This package is used whenever expressions are read from the buffer. So if you edit the definition of the Chaosnet 2get-packet* and recompile it, the new definition is read in the 2chaos* package. The current buffer's package is also used for all expressions or symbols typed by the user. Thus, if you type 2Meta-. allocate-pbuf* while looking at the Chaosnet program, you get the definition of the 2allocate-pbuf* function in the 2chaos* package. The variable 2*package** also has a global binding, which is in effect in any process or stack group which does not rebind the variable. New processes that do bind 2*package** generally use the global binding to initialize their own bindings, doing 2(let ((*package* *package*)) ...)*. Therefore, it can be useful to set the global binding. But you cannot do this with 2setq* or 2pkg-goto* from a Lisp listener, or in a file, because that will set the local binding of 2*package** instead. Therefore you must use 2setq-globally* (4(EVAL-1)The Global Binding*) or 2pkg-goto-globally*. 3pkg-goto-globally* 1package* Sets the global binding of 2*package** to 1package*. An error is signaled if 1package* is not suitable. Bindings of 1package* other than the the global one are not changed, including the current binding if it is not the global one. The name of the current package is always displayed in the middle of the who line, with a colon following it. This describes the process which the who line in general is describing; normally, the process of the selected window. No matter how the current package is changed, the who line will eventually show it (at one-second intervals). Thus, while a file is being loaded, the who line displays that file's package; in the editor, the who line displays the package of the selected buffer. =Node: 4Package Prefixes* =Text: 3PACKAGE PREFIXES* The separation of name spaces is not an uncrossable gulf. Consider a program for accessing files, using the Chaosnet. It may be useful to put it in a distinct package 2file-access*, not 2chaos*, so that the programs are protected from accidental name conflicts. But the file program cannot exist without referring to the functions of the Chaosnet program. The colon character (`2:*') has a special meaning to the Lisp reader. When the reader sees a colon preceded by the name of a package, it reads the next Lisp object with 2*package** bound to that package. Thus, to refer to the symbol 2connect* in package 2chaos*, we write 2chaos:connect*. Some symbols documented in this manual require package prefixes to refer to them; they are always written with an appropriate prefix. Similarly, if the 2chaos* program wanted to refer to the 2arpa* program's 2allocate-pbuf* function (for some reason), it could use 2arpa:allocate-pbuf*. Package prefixes are printed on output also. If you would need a package prefix to refer to a symbol on input, then the symbol is printed with a suitable package prefix if it supposed to be printed readably (2prin1*, as opposed to 2princ*). Just as the current package affects how a symbol is read, it also affects how the symbol is printed. A symbol available in the current package is never printed with a package prefix. The printing of package prefixes makes it possible to print list structure containing symbols from many packages and read the text to produce an equal list with the same symbols in it--provided the current package when the text is read is the same one that was current when the text was printed. The package name in a package prefix is read just like a symbol name. This means that escape characters can be used to include special characters in the package name. Thus, 2foo/:bar:test* refers to the symbol 2test* in the package whose name is ``FOO:BAR'', and so does 2|FOO:BAR|:test*. Also, letters are converted to upper case unless they are escaped. For this reason, the actual name of a package is normally all upper case, but you can use either case when you write a package prefix. In Common Lisp programs, simple colon prefixes are supposed to be used only for referring to external symbols (see 4(PACKAGES-1)Inheritance between Name Spaces*). To refer to other symbols, one is supposed to use two colons, as in 2chaos::lose-it-later*. The Lisp machine tradition is to allow reference to any symbol with a single colon. Since this is upward compatible with what is allowed in Common Lisp, single-colon references are always allowed. However, double-colon prefixes are printed for internal symbols when Common Lisp syntax is in use, so that data printed on a Lisp Machine can be read by other Common Lisp implementations. =Node: 4Home Packages of Symbols* =Text: 3HOME PACKAGES OF SYMBOLS* Each symbol remembers one package which it belongs to: normally, the first one it was ever interned in. This package is available as 2(symbol-package 1symbol*)*. With 2make-symbol* (see 4(SYMBOLS-1)Creating Symbols*) it is possible to create a symbol that has never been interned in any package. It is called an 1uninterned symbol*, and it remains one as long as nobody interns it. The package cell of an uninterned symbol contains 2nil*. Uninterned symbols print with 2#:* as a prefix, as in 2#:foo*. This syntax can be used as input to create an uninterned symbol with a specific name; but a new symbol is created each time you type it, since the mechanism which normally makes symbols unique is interning in a package. Thus, 2(eq #:foo #:foo)* returns 2nil*. 3symbol-package* 1symbol* Returns the contents of 1symbol*'s package cell, which is the package which owns 1symbol*, or 2nil* if 1symbol* is uninterned. 3package-cell-location* 1symbol* Returns a locative pointer to 1symbol*'s package cell. It is preferable to write 3(locf (symbol-package 1symbol*))* rather than calling this function explicitly. Printing of package prefixes is based on the contents of the symbol's package cell. If the cell contains the 2chaos* package, then 2chaos:* is printed as the prefix when a prefix is necessary. As a result of obscure actions involving interning and uninterning in multiple packages, the symbol may not actually be present in 2chaos* any more. Then the printed prefix is inaccurate. This cannot be helped. If the symbol is not where it claims to be, there is no easy way to find wherever it might be. =Node: 4Keywords* =Text: 3KEYWORDS* Distinct name spaces are useful for symbols which have function definitions or values, to enable them to be used independently by different programs. Another way to use a symbol is to check for it with 2eq*. Then there is no possibility of name conflict. For example, the function 2open*, part of the file system, checks for the symbol 2:error* in its input using 2eq*. A user function might do the same thing. Then the symbol 2:error* is meaningful in two contexts, but these meanings do not affect each other. The fact that a user program contains the code 2(eq sym :error)* does not interfere with the function of system code which contains a similar expression. There is no need to separate name spaces for symbols used in this way. In fact, it would be a disadvantage. If both the Chaosnet program and the Arpanet program wish to recognize a keyword named ``address'', for similar purposes (naturally), it is very useful for programs that can call either one if it is the 1same* keyword for either program. But which should it be? 2chaos:address*? 2arpa:address*? To avoid this uncertainty, one package called 2keyword* has been set aside for the keywords of all programs. The Chaosnet and Arpanet programs would both look for 2keyword:address*, normally written as just 2:address*. Symbols in 2keyword* are the normal choice for names of keyword arguments; if you use 2&key* to process them, code is automatically generated to look for for symbols in 2keyword*. They are also the normal choice for flavor operation names, and for any set of named options meaningful in a specific context. 2keyword* and the symbols belonging to it are treated differently from other packages in a couple of ways designed to make them more convenient for this usage. 2** Symbols belonging to 2keyword* are constants; they always evaluate to themselves. (This is brought about by storing the symbol in its own value cell when the symbol is placed in the package). So you can write just 2:error* rather than 2':error*. The nature of the application of keywords is such that they would always be quoted if they were not constant. 2** A colon by itself is a sufficient package prefix for 2keyword*. This is because keywords are the most frequent application of package prefixes. 3keywordp* 1object* 2t* if 1object* is a symbol which belongs to the keyword package. There are certain cases when a keyword should 1not* be used for a symbol to be checked for with 2eq*. Usually this is when the symbol 1) does not need to be known outside of a single program, and 2) is to be placed in shared data bases such as property lists of symbols which may sometimes be in 2global* or 2keyword*. For example, if the Chaosnet program were to record the existence of a host named CAR by placing an 2:address* property on the symbol 2:car*, or the symbol 2car* (notice that 2chaos:car* 1is* 2car*), it would risk conflicts with other programs that might wish to use the 2:address* property of symbols in general. It is better to call the property 2chaos:address*. =Node: 4Inheritance between Name Spaces* =Text: 3INHERITANCE BETWEEN NAME SPACES* In the simplest (but not the default) case, a package is independent of all other packages. This is not the default because it is not usually useful. Consider the standard Lisp function and variables names, such as 2car*: how can the Chaosnet program, using the 2chaos* package, access them? One way would be to install all of them in the 2chaos* package, and every other package. But it is better to have one table of the standard Lisp symbols and refer to it where necessary. This is called 1inheritance*. The single package 2global* is the only one which actually contains the standard Lisp symbols; other packages such as 2chaos* contain directions to ``search 2global* too''. Each package has a hash table of the symbols. The symbols in this table are said to be 1present* (more explicitly, 1present directly*) in the package, or 1interned* in it. In addition, each package has a list of other packages to inherit from. By default, this list contains the package 2global* and no others; but packages can be added and removed at any time with the functions 2use-package* and 2unuse-package*. We say that a package 1uses* the packages it inherits from. Both the symbols present directly in the package and the symbols it inherits are said to be 1available* in the package. Here's how this works in the above example. When the Chaosnet program is read into the Lisp world, the current package would be the 2chaos* package. Thus all of the symbols in the Chaosnet program would be interned in the 2chaos* package. If there is a reference to a standard Lisp symbol such as 2append*, nothing is found in the 2chaos* package's own table; no symbol of that name is present directly in 2chaos*. Therefore the packages used by 2chaos* are searched, including 2global*. Since 2global* contains a symbol named 2append*, that symbol is found. If, however, there is a reference to a symbol that is not standard, such as 2get-packet*, the first time it is used it is not found in either 2chaos* or 2global*. So 2intern* makes a new symbol named 2get-packet*, and installs it in the 2chaos* package. When 2get-packet* is referred to later in the Chaosnet program, 2intern* finds 2get-packet* immediately in the 2chaos* package. 2global* does not need to be searched. When the Arpanet program is read in, the current package is 2arpa* instead of 2chaos*. When the Arpanet program refers to 2append*, it gets the 2global* one; that is, it shares the same one that the Chaosnet program got. However, if it refers to 2get-packet*, it does 1not* get the same one the Chaosnet program got, because the 2chaos* package is presumably not used by 2arpa*. The 2get-packet* in 2chaos* not being available, no symbol is found, so a new one is created and placed in the 2arpa* package. Further references in the Arpanet program find that 2get-packet*. This is the desired result: the packages share the standard Lisp symbols only. Inheritance between other packages can also be useful, but it must be restricted: inheriting only some of the symbols of the used package. If the file access program refers frequently to the advertised symbols of the Chaosnet program--the connection states, such as 2open-state*, functions such as 2connect*, 2listen* and 2open-stream*, and others--it might be convenient to be able to refer to these symbols from the 2file-access* package without need for package prefixes. One way to do this is to place the appropriate symbols of the 2chaos* package into the 2file-access* package as well. Then they can be accessed by the file access program just like its own symbols. Such sharing of symbols between packages never happens from the ordinary operation of packages, but it can be requested explicitly using 2import*. 3import* 1symbols* &optional 1(package* 1*package*)* Is the standard Common Lisp way to insert a specific symbol or symbols into a package. 1symbols* is a symbol or a list of symbols. Each of the specified symbols becomes present directly in 1package*. If a symbol with the same name is already present (directly or by inheritance) in 1package*, an error is signaled. On proceeding, you can say whether to leave the old symbol there or replace it with the one specified in 2import*. But importing may not be the best solution. All callers of the Chaosnet program probably want to refer to the same set of symbols: the symbols described in the documentation of the Chaosnet program. It is simplest if the Chaosnet program, rather than each caller, says which symbols they are. Restricted inheritance allows the 2chaos* package to specify which of its symbols should be inheritable. Then 2file-access* can use package 2chaos* and the desired symbols are available in it. The inheritable symbols of a package such as 2chaos* in this example are called 1external*; the other symbols are 1internal*. Symbols are internal by default. The function 2export* is how symbols are made external. Only the external symbols of a package are inherited by other packages which use it. This is true of 2global* as well; Only external symbols in 2global* are inherited. Since 2global* exists only for inheritance, every symbol in it is external; in fact, any symbol placed in 2global* is automatically made external. 2global* is said to be 1autoexporting*. A few other packages with special uses, such as 2keyword* and 2fonts*, are autoexporting. Ordinary packages such as 2chaos*, which programs are loaded in, should not be. If a request is made to find a name in a package, first the symbols present directly in that package are searched. If the name is not found that way, then all the packages in the used-list are searched; but only external symbols are accepted. Internal symbols found in the used packages are ignored. If a new symbol needs to be created and put into the name space, it is placed directly in the specified package. New symbols are never put into the inherited packages. The used packages of a package are not in any particular order. It does not make any difference which one is searched first, because they are 1not allowed* to have any conflicts among them. If you attempt to set up an inheritance situation where a conflict would exist, you get an error immediately. You can then specify explicitly how to resolve the conflict. See 4(PACKAGES-1)Shadowing and Name Conflicts*. The packages used by the packages used are 1not* searched. If package 2file-access* uses package 2chaos* and file 2mypackage* uses package 2file-access*, this does not cause 2mypackage* to inherit anything from 2chaos*. This is desirable; the Chaosnet functions for whose sake 2file-access* uses 2chaos* are not needed in the programs in 2mypackage* simply to enable them to communicate with 2file-access*. If it is desirable for 2mypackage* to inherit from 2chaos*, that can be requested explicitly. These functions are used to set up and control package inheritance. 3use-package* 1packages* &optional 1(in-package* 1*package*)* Makes 1in-package* inherit symbols from 1packages*, which should be either a single package or name for a package, or a list of packages and/or names for packages. This can cause a name conflict, if any of 1packages* has a symbol whose name matches a symbol in 1in-package*. In this case, an error is signaled, and you must resolve the conflict or abort. 3unuse-package* 1packages* &optional 1(in-package* 1*package*)* Makes 1in-package* cease to inherit symbols from 1packages*. 3package-use-list* 1package* Returns the list of packages used by 1package*. 3package-used-by-list* 1package* Returns the list of packages which use 1package*. You can add or remove inheritance paths at any time, no matter what else you have done with the package. These functions are used to make symbols external or internal in a package. By default, they operate on the current package. 3export* 1symbols* &optional 1(package* 1*package*)* Makes 1symbols* external in 1package*. 1symbols* should be a symbol or string or a list of symbols and/or strings. The specified symbols or strings are interned in 1package*, and the symbols found are marked external in 1package*. If one of the specified symbols is found by inheritance from a used package, it is made directly present in 1package* and then marked external there. (We know it was already external in the package it was inherited from.) Note that if a symbol is present directly in several packages, it can be marked external or internal in each package independently. Thus, it is the symbol's presence in a particular package which is external or not, rather than the symbol itself. 2export* makes symbols external in whichever package you specify; if the same symbols are present directly in any other package, their status as external or internal in the other package is not affected. 3unexport* 1symbols* &optional 1(package* 1*package*)* Makes 1symbols* not be external in 1package*. An error occurs if any of the symbols fails to be directly present in 1package*. 3package-external-symbols* 1package* Returns a list of all the external symbols of 1package*. Sometimes it will be discovered that a symbol which ought to be in 2global* is not there, and the file defining it has already been loaded, thus mistakenly creating a symbol with that name in some other package. Creating a symbol in 2global* would not fix the problem, since pointers to the misbegotten symbol already exist. Even worse, similarly named symbols may have been created mistakenly in other packages by code attempting to refer to the global symbol, and those symbols also are already pointed to. 2globalize* is designed for use in correcting such a situation. 3globalize* 1symbol-or-string* &optional 1(package* 1"GLOBAL")* If 1name-or-symbol* is a name (a string), interns the name in 1into-package* and then forwards together all symbols with the same name in all the packages that use 1into-package* as well as in 1into-package* itself. These symbols are forwarded together so that they become effectively one symbol as far as the value, function definition and properties are concerned. The value of the composite is taken from whichever of the symbols had a value; a proceedable error is signaled if multiple, distinct values were found. The function definition is treated similarly, and so is each property that any of the symbols has. If 1name-or-symbol* is a symbol, 2globalize* interns that symbol in 1into-package* and then forwards the other symbols to that one. The symbol which ultimately is present in 1into-package* is also exported.