;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4Packages and Interning* =Text: 3PACKAGES AND INTERNING* The most important service of the package system is to look up a name in a package and return the symbol which has that name in the package's name space. This is done by the function 2intern*, and is called 1interning*. When you type a symbol as input, 2read* converts your characters to the actual symbol by calling 2intern*. The function 2intern* allows you to specify a package as the second argument. It can be specified by giving either the package object itself or a string or symbol that is a name for the package. 2intern* returns three values. The first is the interned symbol. The second is a keyword that says how the symbol was found. The third is the package in which the symbol was actually found. This can be either the specified package or one of its used packages. When you don't specify the second argument to 2intern*, the current package, which is the value of the symbol 2*package**, is used. This happens, in particular, when you call 2read* and 2read* calls 2intern*. To specify the package for such functions to use, bind the symbol 2*package** temporarily to the desired package with 2pkg-bind*. There are actually four forms of the 2intern* function: regular 2intern*, 2intern-soft*, 2intern-local*, and 2intern-local-soft*. 2-soft* means that the symbol should not be added to the package if there isn't already one; in that case, all three values are 2nil*. 2-local* turns off inheritance; it means that the used packages should not be searched. Thus, 2intern-local* can be used to cause shadowing. 2intern-local-soft* is right when you want complete control over what packages to search and when to add symbols. All four forms of 2intern* return the same three values, except that the 2soft* forms return 2nil nil nil* when the symbol isn't found. 3intern* 1string-or-symbol* &optional 1(pkg* 1*package*)* The simplest case of 2intern* is where 1string-or-symbol* is a string. (It makes a big difference which one you use.) 2intern* searches 1pkg* and its used packages sequentially, looking for a symbol whose print-name is equal to 1string-or-symbol*. If one is found, it is returned. Otherwise, a new symbol with 1string-or-symbol* as print name is created, placed in package 1pkg*, and returned. The first value of 2intern* is always the symbol found or created. The second value tells whether an existing symbol was found, and how. It is one of these four values: 2:internal* A symbol was found present directly in 1pkg*, and it was internal in 1pkg*. 2:external* A symbol was found present directly in 1pkg*, and it was external in 1pkg*. 2:inherited* A symbol was found by inheritance from a package used by 1pkg*. You can deduce that the symbol is external in that package. 2nil* A new symbol was created The third value returned by 2intern* says which package the symbol found or created is present directly in. This is different from 1pkg* if and only if if the second value is 2:inherited*. If 1string-or-symbol* is a symbol, the search goes on just the same, using the print-name of 1string-or-symbol* as the string to search for. But if no existing symbol is found, 1string-or-symbol* itself is placed directly into 1pkg*, just as 2import* would do. No new symbol is created; 1string-or-symbol* 1itself* is the ``new'' symbol. This is done even if 1string-or-symbol* is already present in another package. You can create arbitrary arrangements of sharing of symbols between packages this way. Note: 2intern* is sensitive to case; that is, it will consider two character strings different even if the only difference is one of upper-case versus lower-case. The reason that symbols get converted to upper-case when you type them in is that the reader converts the case of characters in symbols; the characters are converted to upper-case before 2intern* is ever called. So if you call 2intern* with a lower-case 2"foo"* and then with an upper-case 2"FOO"*, you won't get the same symbol. 3intern-local* 1string-or-symbol* &optional 1(pkg* 1*package*)* Like 2intern* but ignores inheritance. If a symbol whose name matches 1string-or-symbol* is present directly in 1pkg*, it is returned; otherwise 1string-or-symbol* (if it is a symbol) or a new symbol (if 1string-or-symbol* is a string) is placed directly in 1pkg*. 2intern-local* returns second and third values with the same meaning as those of 2intern*. However, the second value can never be 2:inherited*, and the third value is always 1pkg*. The function 2import* is implemented by passing the symbol to be imported to 2intern-local*. 3intern-soft* 1string* &optional 1(pkg* 1*package*)* 3find-symbol* 1string* &optional 1(pkg* 1*package*)* Like 2intern* but never creates a symbol or modifies 1pkg*. If no existing symbol is found, 2nil* is returned for all three values. It makes no important difference if you pass a symbol instead of a string. 2intern-soft* returns second and third values with the same meaning as those of 2intern*. However, if the second value is 2nil*, it does not mean that a symbol was created, only that none was found. In this case, the third value is 2nil* rather than a package. 2find-symbol* is the Common Lisp name for this function. The two names are synonymous. 3intern-local-soft* 1string* &optional 1(pkg* 1*package*)* Like 2intern-soft* but without inheritance. If a matching symbol is found directly present in 1pkg*, it is returned; otherwise, the value is 2nil*. 2intern-local-soft* returns second and third values with the same meaning as those of 2intern*. However, if the second value is 2nil*, it does not mean that a symbol was created, only that none was found. Also, it can never be 2:inherited*. The third value is rather useless as it is either 1pkg*, or 2nil* if the second value is 2nil*. 3remob* 1symbol* &optional 1(package* 1(symbol-package* 2symbol1))** 3unintern* 1symbol* &optional 1(package* 1*package*)* Both remove 1symbol* from 1package*. 1symbol* itself is unaffected, but 2intern* will no longer find it in 1package*. 1symbol* is not removed from any other package, even packages used by 1package*, if it should be present in them. If 1symbol* was present in 1package* (and therefore, was removed) then the value is 2t*; otherwise, the value is 2nil*. In 2remob*, 1package* defaults to the contents of the symbol's package cell, the package it belongs to. In 2unintern*, 1package* defaults to the current package. 2unintern* is the Common Lisp version and 2remob* is the traditional version. If 1package* is the package that 1symbol* belongs to, then 1symbol* is marked as uninterned: 2nil* is stored in its package cell. If a shadowing symbol is removed, a previously-hidden name conflict between distinct symbols with the same name in two used packages can suddenly be exposed, like a discovered check in chess. If this happens, an error is signaled. =Node: 4Shadowing and Name Conflicts* =Text: 3SHADOWING AND NAME CONFLICTS* In a package that uses 2global*, it may be desirable to avoid inheriting a few standard Lisp symbols. Perhaps the user has defined a function 2copy-list*, knowing that this symbol was not in 2global*, and then a system function 2copy-list* was created as part of supporting Common Lisp. Rather than changing the name in his program, he can 1shadow* 2copy-list* in the program's package. Shadowing a symbol in a package means putting a symbol in that package which hides any symbols with the same name which could otherwise have been inherited there. The symbol is explicitly marked as a 1shadowing symbol* so that the name conflict does not result in an error. Shadowing of symbols and shadowing of bindings are quite distinct. The same word is used for them because they are both examples of the general abstract concept of shadowing, which is meaningful whenever there is inheritance. Shadowing can be done in the definition of a package (see 4(PACKAGES-1)Defining Packages*) or by calling the function 2shadow*. 2(shadow "COPY-LIST")* creates a new symbol named 2copy-list* in the current package, regardless of any symbols with that name already available through inheritance. Once the new symbol is present directly in the package and marked as a shadowing symbol, the potentially inherited symbols are irrelevant. 3shadow* 1names* &optional 1(package* 1*package*)* Makes sure that shadowing symbols with the specified names exist in 1package*. 1names* is either a string or symbol or a list of such. If symbols are used, only their names matter; they are equivalent to strings. Each name specified is handled independently as follows: If there is a symbol of that name present directly in 1package*, it is marked as a shadowing symbol, to avoid any complaints about name conflicts. Otherwise, a new symbol of that name is created and interned in 1package*, and marked as a shadowing symbol. Shadowing must be done before programs are loaded into the package, since if the programs are loaded without shadowing first they will contain pointers to the undesired inherited symbol. Merely shadowing the symbol at this point does not alter those pointers; only reloading the program and rebuilding its data structures from scratch can do that. If it is necessary to refer to a shadowed symbol, it can be done using a package prefix, as in 2global:copy-list*. Shadowing is not only for symbols inherited from 2global*; it can be used to reject inheritance of any symbol. Shadowing is the primary means of resolving 1name conflicts* in which there multiple symbols with the same name are available, due to inheritance, in one package. Name conflicts are not permitted to exist unless a resolution for the conflict has been stated in advance by specifying explicitly which symbol is actually to be seen in package. If no resolution has been specified, any command which would create a name conflict signals an error instead. For example, a name conflict can be created by 2use-package* if it adds a new used package with its own symbol 2foo* to a package which already has or inherits a different symbol with the same name 2foo*. 2export* can cause a name conflict if the symbol becoming external is now supposed to be inherited by another package which already has a conflicting symbol. On either occasion, if shadowing has not already been performed to control the outcome, an error is signaled and the useage or exportation does not occur. The conflict is resolved--in advance, always--by placing the preferred choice of symbol in the package directly, and marking it as a shadowing symbol. This can be done with the function 2shadowing-import*. (Actually, you can proceed from the error and specify a resolution, but this works by shadowing and retrying. From the point of view of the retried operation, the resolution has been done in advance.) 3shadowing-import* 1symbols* &optional 1(package* 1*package*)* Interns the specified symbols in 1package* and marks them as shadowing symbols. 1symbols* must be a list of symbols or a single symbol; strings are not allowed. Each symbol specified is placed directly into 1package*, after first removing any symbol with the same name already interned in 1package*. This is rather drastic, so it is best to use 2shadowing-import* right after creating a package, when it is still empty. 2shadowing-import* is primarily useful for choosing one of several conflicting external symbols present in packages to be used. Once a package has a shadowing symbol named 2foo* in it, any other potentially conflicting external symbols with name 2foo* can come and go in the inherited packages with no effect. It is therefore possible to perform the 2use-package* of another package containing another 2foo*, or to export the 2foo* in one of the used packages, without getting an error. In fact, 2shadow* also marks the symbol it creates as a shadowing symbol. If it did not do so, it would be creating a name conflict and would always get an error. 3package-shadowing-symbols* 1package* Returns the list of shadowing symbols of 1package*. Each of these is a symbol present directly in 1package*. When a symbol is present directly in more than one package, it can be a shadowing symbol in one and not in another. =Node: 4Styles of Using Packages* =Text: 3STYLES OF USING PACKAGES* The unsophisticated user need never be aware of the existence of packages when writing his programs. His files are loaded into package 2user* by default, and keyboard input is also read in 2user* by default. Since all the functions that unsophisticated users are likely to need are provided in the 2global* package, which 2user* inherits from, they are all available without special effort. In this manual, functions that are not in the 2global* package are documented with colons in their names, and they are all external, so typing the name the way it is documented does work in both traditional and Common Lisp syntax. However, if you are writing a generally useful tool, you should put it in some package other than 2user*, so that its internal functions will not conflict with names other users use. If your program contains more than a few files, it probably should have its own package just on the chance that someone else will use it someday along with other programs. If your program is large, you can use multiple packages to help keep its modules independent. Use one package for each module, and export from it those of the module's symbols which are reasonable for other modules to refer to. Each package can use the packages of other modules that it refers to frequently. =Node: 4Package Naming* =Text: 3PACKAGE NAMING* A package has one name, also called the 1primary name* for extra clarity, and can have in addition any number of 1nicknames*. All of these names are defined globally, and all must be unique. An attempt to define a package with a name or nickname that is already in use is an error. Either the name of a package or one of its nicknames counts as a 1name for* the package. All of the functions described below that accept a package as an argument also accept a name for a package (either as a string, or as a symbol whose print-name is the name). Arguments that are lists of packages may also contain names among the elements. When the package object is printed, its primary name is used. The name is also used by default when printing package prefixes of symbols. However, when you create the package you can specify that one of the nicknames should be used instead for this purpose. The name to be used for this is called the 1prefix name*. Case is significant in package name lookup. Usually package names should be all upper case. 2read* converts package prefixes to upper case except for quoted characters, just as it does to symbol names, so the package prefix will match the package name no matter what case you type it in, as long as the actual name is upper case: 2TV:FOO* and 2tv:foo* refer to the same symbol. 2|tv|:foo* is different from them, and normally erroneous since there is no package initially whose name is `tv' in lower case. In the functions 2find-package* and 2pkg-find-package*, and others which accept package names in place of packages, if you specify the name as a string you must give it in the correct case: 3(find-package "TV") => 2the tv package** 3(find-package "tv") => nil* You can alternatively specify the name as a symbol; then the symbol's pname is used. Since 2read* converts the symbol's name to upper case, you can type the symbol in either upper or lower case: 3(find-package 'TV) => 2the tv package** 3(find-package 'tv) => 2the tv package** since both use the symbol whose pname is 3"TV"*. Relevant functions: 3package-name* 1package* Returns the name of 1package* (as a string). 3package-nicknames* 1package* Returns the list of nicknames (strings) of 1package*. This does not include the name itself. 3package-prefix-print-name* 1package* Returns the name to be used for printing package prefixes that refer to 1package*. 3rename-package* 1package* 1new-name* &optional 1new-nicknames* Makes 1new-name* be the name for 1package*, and makes 1new-nicknames* (a list of strings, possibly 2nil*) be its nicknames. An error is signaled if the new name or any of the new nicknames is already in use for some other package. 3find-package* 1name* &optional 1use-local-names-package* Returns the package which 1name* is a name for, or 2nil* if there is none. If 1use-local-names-package* is non-2nil*, the local nicknames of that package are checked first. Otherwise only actual names and nicknames are accepted. 1use-local-names-package* should be supplied only when interpreting package prefixes. If 1name* is a package, it is simply returned. If a list is supplied as 1name*, it is interpreted as a specification of a package name and how to create it. The list should look like 3(1name* 1super-or-use* 1size*)* or 3(1name* 1options*)* If 1name* names a package, it is returned. Otherwise a package is created by passing 1name* and the 1options* to 2make-package*. 3pkg-find-package* 1name* &optional 1create-p* 1use-local-names-package* Invokes 2find-package* on 1name* and returns the package that finds, if any. Otherwise, a package may be created, depending on 1create-p* and possibly on how the user answers. These values of 1create-p* are meaningful: 2nil* An error is signaled if an existing package is not found. 2t* A package is created, and returned. 2:find* 2nil* is returned. 2:ask* The user is asked whether to create a package. If he answers 2Yes*, a package is created and returned. If he answers 2No*, 2nil* is returned. If a package is created, it is done by calling 2make-package* with 1name* as the only argument. This function is not quite for historical compatibility only, since certain values of 1create-p* provide useful features. 3sys:package-not-found* (3error*) 1Condition* is signaled by 2pkg-find-package* with second argument 2:error*, 2nil* or omitted, when the package does not exist. The condition instance supports the operations 2:name* and 2:relative-to*; these return whatever was passed as the first and third arguments to 2pkg-find-package* (the package name, and the package whose local nicknames should be searched). The proceed types that may be available include 2:retry* says to search again for the specified name in case it has become defined; if it is still undefined, the error occurs again. 2:create-package* says to search again for the specified name, and create a package with that name (and default characteristics) if none exists yet. 2:new-name* is accompanied by a name (a string) as an argument. That name is used instead, ignoring any local nicknames. If that name too is not found, another error occurs. 2:no-action* (available on errors from within 2read*) says to continue with the entire 2read* as well as is possible without having a valid package. =Node: 4Local Nicknames for Packages* =Text: 3LOCAL NICKNAMES FOR PACKAGES* Suppose you wish to test new versions of the Chaosnet and file access programs. You could create new packages 2test-chaos* and 2test-file-access*, and use them for loading the new versions of the programs. Then the old, installed versions would not be affected; you could still use them to edit and save the files of the new versions. But one problem must be solved: when the new file access program says "2chaos:connect*" it must get 2test-chaos:connect* rather than the actual 2chaos:connect*. This is accomplished by making 2"CHAOS"* a local nickname for 2"TEST-CHAOS"* in the context of the package 2test-file-access*. This means that the when a 2chaos:* prefix is encountered while reading in package 2test-file-access*, it refers to 2test-chaos* rather than 2chaos*. Local nicknames are allowed to conflict with global names and nicknames; in fact, they are rarely useful unless they conflict. The local nickname takes precedence over the global name. It is necessary to have a way to override local nicknames. If you 2(pkg-goto 'test-file-access)*, you may wish to call a function in 2chaos* (to make use of the old, working Chaosnet program). This can be done using 2#:* as the package prefix instead of just 2:*. 2#:* inhibits the use of local nicknames when it is processed. It always refers to the package which is globally the owner of the name that is specified. 2#:* prefixes are printed whenever the package name printed is also a local nickname in the current package; that is, whenever an ordinary colon prefix would be misunderstood when read back These are the functions which manage local nicknames. 3pkg-add-relative-name* 1in-pkg* 1name* 1for-pkg* Defines 1name* as a local nickname in 1in-pkg* for 1for-pkg*. 1in-pkg* and 1for-pkg* may be packages, symbols or strings. 3pkg-delete-relative-name* 1in-pkg* 1name* Eliminates 1name* as a local nickname in 1in-pkg*. Looking up local nicknames is done with 2find-package*, by providing a non-2nil 1use-local-names-package** argument. =Node: 4Defining Packages* =Text: 3DEFINING PACKAGES* Before any package can be referred to or made current, it must be defined. This is done with the special form 2defpackage*, which tells the package system all sorts of things, including the name of the package, what packages it should use, its estimated size, and some of the symbols which belong in it. The 2defpackage* form is recognized by Zmacs as a definition of the package name. 3defpackage* 1name* &key 1...* 1Macro* Defines a package named 1name*. The alternating keywords and values are passed, unevaluated, to 1make-package* to specify the rest of the information about how to construct the package. If a package named 1name* already exists, it is modified insofar as this is possible to correspond to the new definition. Here are the possible options and their meanings 1nicknames* A list of nicknames for the new package. The nicknames should be specified as strings. 1size* A number; the new package is initially made large enough to hold at least this many symbols before a rehash is needed. 1use* A list of packages or names for packages which the new package should inherit from, or a single name or package. It defaults to just the 2global* package. 1prefix-name* Specifies the name to use for printing package prefixes that refer to this package. It must be equal to either the package name or one of the nicknames. The default is to use the name. 1invisible* If non-2nil*, means that this package should not be put on the list 2*all-packages**. As a result, 2find-package* will not find this package, not by its name and not by any of its nicknames. You can make normal use of the package in all other respects (passing it as the second argument to 2intern*, passing it to 2use-package* to make other packages inherit from it or it from others, and so on). 1export* 1import* defpackage 1shadow* defpackage 1shadowing-import* defpackage If any of these arguments is non-2nil*, it is passed to the function of the same name, to operate on the package. Thus, if 1shadow* is 2("FOO" "BAR")*, then 3(shadow 1this-package* '("FOO" "BAR"))* is done. You could accomplish as much by calling 2export*, 2import*, 2shadow* or 2shadowing-import* yourself, but it is clearer to specify all such things in one central place, the 2defpackage*. 1import-from* If non-2nil*, is a list containing a package (or package name) followed by names of symbols to import from that package. Specifying 1import-from* as 2(chaos* 2"CONNECT" "LISTEN")* is nearly the same as specifying 1import* as 2(chaos:connect* 2chaos:listen)*, the difference being that with 1import-from* the symbols 2connect* and 2listen* are not looked up in the 2chaos* package until it is time to import them. 1super* If non-2nil*, should be a package or name to be the superpackage of the new package. This means that the new package should inherit from that package, and also from all the packages that package inherits from. In addition, the superpackage is marked as autoexporting. Superpackages are obsolete and are implemented for compatibility only. 1relative-names* An alist specifying the local nicknames to have in this package for other packages. Each element looks like 2(1localname* 1package*)*, where 1package* is a package or a name for one, and 1localname* is the desired local nickname. 1relative-names-for-me* An alist specifying local nicknames by which this package can be referred to from other packages. Each element looks like 2(1package* 1localname*)*, where 1package* is a package name and 1localname* is the name to refer to this package by from 1package*. For example, the system package 2eh* could have been defined this way: 3(defpackage "EH" :size 1200* 3 :use ("GLOBAL" "SYS") :nicknames ("DBG" "DEBUGGER")* 3 :shadow ("ARG"))* It has room initially for at least 1200. symbols, nicknames 2dbg* and 2debugger*, uses 2system* as well as 2global*, and contains a symbol named 2arg* which is not the same as the 2arg* in 2global*. You may note that the function 2eh:arg* is documented in this manual (see 4(DEBUGGING-4)Debugger Commands*), as is the function 2arg* (see 4(FUNCTIONS-2)Maclisp Lexprs*). The packages of our inheritance example (4(PACKAGES-1)Inheritance between Name Spaces*) might have been defined by 3(defpackage 'chaos :size 1000 :use '(sys global)* 3 :export ("CONNECT" "OPEN-STREAM" "LISTEN" ...* 3 "OPEN-STATE" "RFC-RECEIVED-STATE" ...))* 3(defpackage 'file-access :size 1500* 3 :use '(chaos global)* 3 :export ("OPEN-FILE" "CLOSE-FILE" "DELETE-FILE" ...)* 3 :import (chaos:connect chaos:open-state))* 3(defpackage 'mypackage :size 400* 3 :use '(file-access global))* It is usually best to put the package definition in a separate file, which should be loaded into the 2user* package. (It cannot be loaded into the package it is defining, and no other package has any reason to be preferred.) Often the files to be loaded into the package belong to one or a few systems; then it is often convenient to put the system definitions in the same file (see 4(SYSTEMS-0)Maintaining Large Systems*). A package can also be defined by the package attribute in a file's 3-*-* line. Normally this specifies which (existing) package to load, compile or edit the file in. But if the attribute value is a list, as in 3-*-Package: (foo :size 300 :use (global system)); ...* then loading, compiling or editing the file automatically creates package 2foo*, if necessary with the specified options (just like 2defpackage* options). No 2defpackage* is needed. It is wise to use this feature only when the package is used for just a single file. For programs containing multiple files, it is good to make a system for them, and then convenient to put a 2defpackage* near the 2defsystem*. 3make-package* 1name* &key 1nicknames* 1size* 1use* 1prefix-name* 1invisible* 1export* 1shadow* 1import* 1shadowing-import* 1import-from* 1super* 1relative-names* 1relative-names-for-me* Creates and returns new package with name 1name*. The meanings of the keyword arguments are described under 2defpackage* (4(PACKAGES-1)Defining Packages*). 3pkg-create-package* 1name* &optional 1(super* 1*package*)* 1(size* 1#o200)* Creates a new package named 1name* of size 1size* with superpackage 1super*. This function is obsolete. 3kill-package* 1name-or-package* Kills the package specified or named. It is removed from the list which is searched when package names are looked up. 3package-declare* 1Macro* 2package-declare* is an older way of defining a package, obsolete but still used. 3(package-declare 1name* 1superpackage* 1size* nil* 3 1option-1* 1option-2* ...)* creates a package named 1name* with initial size 1size*. 1super* specifies the 1superpackage* to use for this package. Superpackages were an old way of specifying inheritance; it was transitive, all symbols were inherited, and only one inheritance path could exist. If 1super* is 2global*, nothing special needs to be done; otherwise, the old superpackage facility is simulated using the 1super* argument to 2make-package*. 1body* is now allowed to contain only these types of elements: 2(shadow 1names*)* Passes the names to the function 2SHADOW*. 2(intern 1names*)* Converts each name to a string and interns it in the package. 2(refname 1refname* 1packagename*)* Makes 1refname* a local nickname in this package for the package named 1packagename*. 2(myrefname 1packagename* 1refname*)* Makes 1refname* a local nickname in the package named 1packagename* for this package. If 1packagename* is 2"GLOBAL"*, makes 1refname* a global nickname for this package. 2(external 1names*)* Does nothing. This controlled an old feature that no longer exists.