Resolution of ambiguous word names
Factor handbook » The language » Syntax » Parse-time word lookup

Prev:Private words
Next:Word lookup errors


There is a distinction between parsing words which perform “open” imports versus “closed” imports. An open import introduces all words from a vocabulary as identifiers, except possibly a finite set of exclusions. The USE:, USING: and EXCLUDE: words perform open imports. A closed import only adds a fixed set of identifiers. The FROM:, RENAME:, QUALIFIED: and QUALIFIED-WITH: words perform closed imports. Note that the latter two are considered as closed imports, due to the fact that all identifiers they introduce are unambiguously qualified with a prefix. The IN: parsing word also performs a closed import of the newly-created vocabulary.

When the parser encounters a reference to a word, it first searches the closed imports, in order. Closed imports are searched from the most recent to least recent. If the word could not be found this way, it searches open imports. Unlike closed imports, with open imports, the order does not matter -- instead, if more than one vocabulary defines a word with this name, an error is thrown.
ambiguous-use-error


To resolve the error, add a closed import, using FROM:, QUALIFIED: or QUALIFIED-WITH:. The closed import will then take precedence over the open imports, and the ambiguity will be resolved.

The rationale for this behavior is as follows. Open imports are named such because they are open to future extension; if a future version of a vocabulary that you use adds new words, those new words will now be in scope in your source file, too. To avoid problems, any references to the new word have to be resolved since the parser cannot safely determine which vocabulary was meant. This problem can be avoided entirely by using only closed imports, but this leads to additional verbosity.

In practice, a small set of guidelines helps avoid name clashes:
Keep vocabularies small
Hide internal words using <PRIVATE
Make good use of FROM:, QUALIFIED: or QUALIFIED-WITH: