Package-Local Nicknames

Package-local nicknames make it possible to use short and easy-to-use names without potentially introducing name conflicts as can happen with usual nicknames.

Package-local nicknames are implemented in some form in SBCL, CCL, ECL, Clasp, ABCL, Allegro CL, LispWorks. There is also a pending MR for the CLISP implementation.

Unfortunately, there are multiple inconsistencies between implementations. All of them lose print-read consistency to some extent, and there are multiple edge cases that aren't always implemented correctly or in the same way.

The purpose of this document is to standardize the Package-Local Nicknames extension and to address some existing issues.

[TODO] This CDR also aims to provide an extensive test suite for the extension.

(add-package-local-nickname nickname actual-package &optional designated-package)
  => designated-package-object

(remove-package-local-nickname old-nickname &optional designated-package)
  => nickname-removed-p

(package-local-nicknames package-designator)
  => local-nicknames-alist
local-nicknames-alist ::= ((nickname . package)*)

(package-locally-nicknamed-by-list package-designator)
  => packages-list

See defpackage.

See make-package.

(Contains proposals: see Issue 3, Issue 8.)

When the argument to find-package is a local nickname defined in the current package, it returns the package nicknamed by this nickname.

This also affects all implied calls to find-package, including but not limited to those performed by the lisp reader as well as those performed by defpackage, make-package, export, find-symbol, import, rename-package, shadow, shadowing-import, delete-package, with-package-iterator, unexport, unintern, in-package, unuse-package, use-package, do-symbols, do-external-symbols, do-all-symbols, intern, package-name, package-nicknames, package-shadowing-symbols, package-use-list, package-used-by-list.

add-package-local-nickname, remove-package-local-nickname, package-local-nicknames and package-locally-nicknamed-by are also affected.

The only exception is the tilde slash directive of format, which should not use local nicknames from any package when looking up the specified symbol.

When a package is renamed with rename-package, it retains all local nicknames it has defined, as well as all local nicknames by which it is nicknamed.

When a package is deleted with delete-package, all local nicknames defined in that package are removed, as well as all local nicknames by which it is nicknamed.

This also means that a deleted package must not be available via calls to package-locally-nicknamed-by-list and package-local-nicknames.

See Issue 8.

If an implementation supports package-local nicknames, it should add symbols :package-local-nicknames and :cdr-NN (per CDR 14) to *features*.

Functions add-package-local-nickname and remove-package-local-nickname have inconsistent return values.

The first one always returns the designated package, while the second one returns true (a generalized boolean) that indicates whether a nickname was removed.

Furthermore, there is no consensus among existing implementations as to what this generalized boolean represents.

In comparison,the functions use-package and unuse-package always return T, and the functions export and unexport have the same behavior. There are also functions unintern and delete-package which return a generalized boolean indicating if the operation changed something, but their counterparts intern and make-package, unlike with local nicknames, create and return an object (a symbol or a package).

sbcl, ccl, ecl, acl, abcl, clasp, lispworks: add-package-local-nickname always returns designated package.

sbcl, ccl, ecl, acl, clasp: remove-package-local-nickname returns T if a nickname was removed, and NIL otherwise.

abcl: remove-package-local-nickname returns true if a nickname was removed, (more specifically, it returns the package nicknamed by the removed local nickname), and NIL otherwise.

lispworks: remove-package-local-nickname always returns NIL.

add-package-local-nickname should always return T.

remove-package-local-nickname should always return T.

add-package-local-nickname should return the designated package.

remove-package-local-nickname should return T if a nickname was removed and NIL otherwise.

add-package-local-nickname should return the designated package if a new nickname was added, and NIL otherwise.

remove-package-local-nickname should return the designated package if a nickname was removed, and NIL otherwise.

add-package-local-nickname should return the nicknamed package if a new nickname was added, and NIL otherwise.

remove-package-local-nickname should return the previously nicknamed package if a nickname was removed, and NIL otherwise.

The Lisp reader uses find-package when reading a symbol, which is affected by the local nicknames of the current package. That means that to maintain print-read consistency when printing a symbol, a good package prefix must be used - such that calling find-package on it in the current package returns the home package of the symbol.

There are several situations to consider:

1. The symbol is apparently uninterned.

   In this case it is printed without the package prefix, using the uninterned symbol syntax #:.

2. The symbol is accessible in the current package.

   In this case it is printed without any package prefix.

3. The name or one of the global nicknames of the home package of the symbol is not shadowed by any local nickname defined in the current package.

   In this case that name or global nickname might be used as the package prefix.

4. There exists a local nickname defined in the current package for the home package of the symbol.

   In this case that local nickname might be used as the package prefix.

5. Both the name and all global nicknames of the home package of the symbol are shadowed by local nicknames of the current package, and there is no local nickname defined in the current package for the home package.

   It is not clear how the symbol is printed, see PROPOSALS.

sbcl, ccl, abcl, lispworks: When possible, a local nickname is used as a package prefix.

ecl, acl, clasp: Local nicknames are never used as a package prefix.

In the 5th case the symbol is printed using the #. syntax:

#.(cl:let ((cl:*package* (cl:find-package "KEYWORD")))
    (cl:find-symbol "BAR" "FOO"))
;; or
#.(cl:let ((cl:*package* (cl:find-package "KEYWORD")))
    (cl:intern "BAR" "FOO"))

If *read-eval* is false and *print-readably* is true, an error of type print-not-readable is signaled.

In the 5th case the symbol is printed using the extended #: syntax:

#:(package name)
#::(package name)

Shinmera's idea.

In the 5th case the symbol is printed using the new #` syntax for reading an expression ignoring local nicknames in the current package:

#`foo:bar
#`foo::bar

It can be implemented roughly as follows:

(defun |#`-reader| (stream subchar arg)
  (declare (ignore subchar arg))
  (let* ((current-package *package*)
         (local-nicknames (package-local-nicknames current-package)))
    (loop for (nick . package) in local-nicknames
          do (remove-package-local-nickname nick current-package))
    (unwind-protect
      (read stream t nil t)
      (loop for (nick . package) in local-nicknames
            do (add-package-local-nickname nick package current-package)))))

(set-dispatch-macro-character #\# #\` #'|#`-reader|)

It is implementation-dependent whether local nicknames are actually removed from the current package or not.

In the 5th case the symbol is printed unreadably using the #< syntax:

#<SYMBOL IN THE SHADOWED PACKAGE FOO:BAR>
#<SYMBOL IN THE SHADOWED PACKAGE FOO::BAR>

(Specifics are implementation-dependent.)

If *print-readably* is true, an error of type print-not-readable is signaled.

In the 5th case the symbol is printed using the extended symbol token syntax:

foo:::bar   ; same as (cl:find-symbol "BAR" "FOO") in the #:KEYWORD package
foo::::bar  ; same as (cl:intern "BAR" "FOO") in #:KEYWORD package

See CLHS 22.1.3.3.1 Package Prefixes for Symbols.

It is not clear whether local nicknames of the current package should affect the package lookup in operators that accept a package designator as an argument. This mainly concerns make-package and defpackage. See also Notes.

• defpackage and make-package sbcl, lispworks: Only the :local-nicknames clause is not affected by local nicknames.

  ccl, acl, abcl: All clauses and keyword arguments are affected.

  ecl: Only the :local-nicknames clause and all keyword arguments (:use and :local-nicknames) are affected.

  clasp: Only the keyword argument :use is affected.

• Known exceptions in other operators: sbcl: add-package-local-nickname is not affected.

  lispworks: in-package is not affected.

All operators taking a package designator as an argument must be affected by local nicknames of the current package.

In particular, all defpackage clauses (:use, :local-nicknames, :import-from, :shadowing-import-from) as well as all keyword arguments to make-package (:use and :local-nicknames) must be affected.

A non-exhaustive list of operators possibly affected by this issue: defpackage, make-package, export, find-symbol, import, rename-package, shadow, shadowing-import, delete-package, with-package-iterator, unexport, unintern, in-package, unuse-package, use-package, do-symbols, do-external-symbols, do-all-symbols, intern, package-name, package-nicknames, package-shadowing-symbols, package-use-list, package-used-by-list, add-package-local-nickname, remove-package-local-nickname, package-local-nicknames, package-locally-nicknamed-by.

format is not affected by this issue, see instead Issue 8.

It is not clear whether local nicknames of the package being defined should affect make-package or defpackage.

sbcl, ccl, acl, abcl, lispworks: Nothing is affected.

ecl: :use, :import-from and :shadowing-import-from clauses are affected.

clasp: :local-nicknames clause is affected by local nicknames introduced by previous :local-nicknames clauses.

Local nicknames of the package being defined must not affect any of the defpackage clauses (:use, :local-nicknames, :import-from, :shadowing-import-from).

The keyword argument :local-nicknames to make-package must not affect the :use keyword argument either.

It is not clear whether it should be allowed to define a local nickname that shadows the name or one of the global nicknames of the package that it is defined in.

sbcl, ccl, abcl: A correctable error is signaled by defpackage.

lispworks: An error is signaled by defpackage. A correctable error is signaled by add-package-local-nickname.

ecl, acl, clasp: No errors are signaled.

It should be allowed to use the name or one of the global nicknames of the package as a local nickname, but a style warning might be issued.

Attemts to create such a nickname should result in a correctable error being signaled. The continue restart can be used to create the nickname anyway.

An additional keyword argument to make-package similar to the :use keyword argument would be a nice feature. There are only two implementations introducing this extension, unfortunately they use different API for this argument.

Possible questions:

• Does it accept an alist or a nested list?
• Is the default value implementation-dependent, or is it an empty list?

sbcl, ccl, abcl, clasp, lispworks: no additional keyword argument.

ecl: has an additional keyword argument :local-nicknames, but it is undocumented and it segfaults on incorrect usage. The expected value is a list of conses: ((nickname . package)*).

acl: has an additional keyword argument :local-nicknames. The expected value is a list of lists: ((nickname package)*).

Add :local-nicknames keyword argument to make-package:

local-nicknames ::= ((nickname package)*)

nickname — a string designator.

package — a package designator.

local-nicknames defaults to an empty list.

See make-package.

It is not clear whether package-locally-nicknamed-by-list should be allowed to return a list with duplicate entries (when there are multiple local nicknames in one package).

sbcl, acl, clasp, lispworks: package-locally-nicknamed-by-list never contains duplicate entries.

ccl, abcl, ecl: package-locally-nicknamed-by-list might contain duplicate entries.

package-locally-nicknamed-by-list should return a list without duplicate entries.

It is not clear how local nicknames should affect the tilde slash \~// directive of format.

• If \~// directive wasn't affected by local nicknames, it would mean that using [long and not-so-easy-to-use] package names is necessary.

• It would be counterintuitive if the function used by the \~// directive could change based on the current package at execution time (that is, if the symbol lookup was affected by local nicknames of the current package).

  This could also break existing code if a local nickname in the current package shadows the name of a package containing a function used in a format control string in the called function. The only way to prevent this issue would be to rebind the *package* variable around any call to format where the \~// directive is used.

• Finally, if the call to format is not compiled, it would be hard to impossible to find the function using local nicknames of the package that was the current package at compile time.

The tilde slash \~// directive of format must not use local nicknames of any package when looking up the specified symbol.

See CLHS 22.3.5.4 Tilde Slash: Call Function.

It is not clear whether it should be allowed to use the empty string "" as a local nickname, and in the case it is allowed, whether it should affect the keyword symbol syntax :xxxx.

sbcl, ccl: :xxxx is read as a keyword; ||:xxxx is read as a symbol in the package named or nicknamed "".

ecl, clasp, lispworks: Both ||:xxxx and :xxxx are read as a keyword.

acl:

Both :xxxx and ||:xxxx are read as a symbol in the package named or nicknamed "" which is a global nickname for the #:KEYWORD package, but can be shadowed by a local nickname.

abcl: :xxxx is read as a keyword; ||:xxxx syntax cannot be read (attemts result in an error).

The "" local nickname should be explicitely allowed. :xxxx should be always read as a keyword regardless of package names or nicknames. ||:xxxx should be read as a symbol in the package named or nicknamed by "".

The "" local nickname should be explicitely allowed. Both :xxxx and ||:xxxx should be read as a symbol in the package named or nicknamed by "".

See also the WSCL issue 63.