11.1.1.2.5 Prevention of Name Conflicts in Packages

Within one package, any particular name can refer to at most one symbol. A name conflict is said to occur when there would be more than one candidate symbol. Any time a name conflict is about to occur, a correctable error is signaled.

The following rules apply to name conflicts:

-- Name conflicts are detected when they become possible, that is, when the package structure is altered. Name conflicts are not checked during every name lookup.

-- If the same symbol is accessible to a package through more than one path, there is no name conflict. A symbol cannot conflict with itself. Name conflicts occur only between distinct symbols with the same name (under string=).

-- Every package has a list of shadowing symbols. A shadowing symbol takes precedence over any other symbol of the same name that would otherwise be accessible in the package. A name conflict involving a shadowing symbol is always resolved in favor of the shadowing symbol, without signaling an error (except for one exception involving import). See shadow and shadowing-import.

-- The functions use-package, import, and export check for name conflicts.

-- shadow and shadowing-import never signal a name-conflict error.

-- unuse-package and unexport do not need to do any name-conflict checking. unintern does name-conflict checking only when a symbol being uninterned is a shadowing symbol.

-- Giving a shadowing symbol to unintern can uncover a name conflict that had previously been resolved by the shadowing.

-- Package functions signal name-conflict errors of type package-error before making any change to the package structure. When multiple changes are to be made, it is permissible for the implementation to process each change separately. For example, when export is given a list of symbols, aborting from a name conflict caused by the second symbol in the list might still export the first symbol in the list. However, a name-conflict error caused by export of a single symbol will be signaled before that symbol's accessibility in any package is changed.

-- Continuing from a name-conflict error must offer the user a chance to resolve the name conflict in favor of either of the candidates. The package structure should be altered to reflect the resolution of the name conflict, via shadowing-import, unintern, or unexport.

-- A name conflict in use-package between a symbol present in the using package and an external symbol of the used package is resolved in favor of the first symbol by making it a shadowing symbol, or in favor of the second symbol by uninterning the first symbol from the using package.

-- A name conflict in export or unintern due to a package's inheriting two distinct symbols with the same name (under string=) from two other packages can be resolved in favor of either symbol by importing it into the using package and making it a shadowing symbol, just as with use-package.