From c5deb8544b7cc2cae1b20dd56eea64400d67454c Mon Sep 17 00:00:00 2001 From: Philip Ginsbach Date: Wed, 1 Feb 2023 16:00:11 +0000 Subject: [PATCH 1/3] rework documentation of namespaces to take account of shadowing --- .../ql-language-reference/name-resolution.rst | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/codeql/ql-language-reference/name-resolution.rst b/docs/codeql/ql-language-reference/name-resolution.rst index 55463c630d4..59e95690001 100644 --- a/docs/codeql/ql-language-reference/name-resolution.rst +++ b/docs/codeql/ql-language-reference/name-resolution.rst @@ -216,15 +216,21 @@ Local namespaces In addition to the global module, type, and predicate namespaces, each module defines a number of local module, type, and predicate namespaces. -For a module ``M``, it's useful to distinguish between its **declared**, **exported**, and **imported** namespaces. -(These are described generically, but remember that there is always one for each of modules, types, and predicates.) +For a module ``M``, it is useful to distinguish between its **privately declared**, **publically declared**, **exported**, and **visible** namespaces. +(These are described generically, but remember that there is always one for each of modules, module signatures, types, type signatures, predicates, and predicate signatures.) + +- The **privately declared** namespaces of ``M`` contain all entities that are declared—that is, defined—in ``M`` and that are annotated as ``private``. +- The **publically declared** namespaces of ``M`` contain all entities that are declared—that is, defined—in ``M`` and that are not annotated as ``private``. +- The **exported** namespaces of ``M`` contain + 1. all entries from the **publically declared** namespaces of ``M``, and + 2. for each module ``N`` that is imported into ``M`` with an import statement that is not annotated as ``private``: all entries from the **exported** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``. +- The **visible** namespaces of ``M`` contain + 1. all entries from the **exported** namespaces of ``M``, and + 2. all entries from the **global** namespaces, and + 3. all entries from the **privately declared** namespace of ``M``, and + 4. if ``M`` is nested within a module ``N``: all entries from the **visible** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``, and + 5. all parameters of ``M``. - - The **declared** namespaces contain any names that are declared—that is, defined—in ``M``. - - The **imported** namespaces contain any names exported by the modules that are imported into ``M`` using an - :ref:`import statement `. - - The **exported** namespaces contain any names declared in ``M``, or exported from a module imported into ``M``, - except names annotated with ``private``. This includes everything in the imported namespaces that was not introduced - by a private import. This is easiest to understand in an example: @@ -248,12 +254,13 @@ This is easiest to understand in an example: } } -The module ``OneTwoThreeLib`` **imports** anything that is exported by the module ``MyFavoriteNumbers``. +The module ``OneTwoThreeLib`` **publically declares** the class ``OneTwoThree`` and **privately declares** the module ``P``. -It **declares** the class ``OneTwoThree`` and the module ``P``. +It **exports** the class ``OneTwoThree`` and anything that is exported by ``MyFavoriteNumbers`` +(assuming ``MyFavoriteNumbers`` does not export a type ``OneTwoThree``, which would not be **exported** by ``OneTwoThreeLib``). -It **exports** the class ``OneTwoThree`` and anything that is exported by ``MyFavoriteNumbers``. -It does not export ``P``, since it is annotated with ``private``. +Within it, the class ``OneTwoThree`` and the module ``P`` are **visible**, as well as anything exported by `MyFavoriteNumbers`` +(assuming ``MyFavoriteNumbers`` does not export a type ``OneTwoThree``, which would not be **visible** within ``OneTwoThreeLib``). Example ======= From 2b719d503dc5dfa46393607eff970491d2ad8568 Mon Sep 17 00:00:00 2001 From: Philip Ginsbach Date: Thu, 2 Feb 2023 13:03:30 +0000 Subject: [PATCH 2/3] visible namespaces also include private imports --- docs/codeql/ql-language-reference/name-resolution.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/codeql/ql-language-reference/name-resolution.rst b/docs/codeql/ql-language-reference/name-resolution.rst index 59e95690001..fd55c0b83bd 100644 --- a/docs/codeql/ql-language-reference/name-resolution.rst +++ b/docs/codeql/ql-language-reference/name-resolution.rst @@ -228,8 +228,9 @@ For a module ``M``, it is useful to distinguish between its **privately declared 1. all entries from the **exported** namespaces of ``M``, and 2. all entries from the **global** namespaces, and 3. all entries from the **privately declared** namespace of ``M``, and - 4. if ``M`` is nested within a module ``N``: all entries from the **visible** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``, and - 5. all parameters of ``M``. + 4. for each module ``N`` that is imported into ``M`` with an import statement that is annotated as ``private``: all entries from the **exported** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``. + 5. if ``M`` is nested within a module ``N``: all entries from the **visible** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``, and + 6. all parameters of ``M``. This is easiest to understand in an example: From 4282e1a18e3faf1aeac0c607ec7c6c40e628b642 Mon Sep 17 00:00:00 2001 From: Philip Ginsbach Date: Thu, 2 Feb 2023 13:04:43 +0000 Subject: [PATCH 3/3] explicitly mention aliases --- docs/codeql/ql-language-reference/name-resolution.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/codeql/ql-language-reference/name-resolution.rst b/docs/codeql/ql-language-reference/name-resolution.rst index fd55c0b83bd..6353c13477e 100644 --- a/docs/codeql/ql-language-reference/name-resolution.rst +++ b/docs/codeql/ql-language-reference/name-resolution.rst @@ -219,8 +219,8 @@ module, type, and predicate namespaces. For a module ``M``, it is useful to distinguish between its **privately declared**, **publically declared**, **exported**, and **visible** namespaces. (These are described generically, but remember that there is always one for each of modules, module signatures, types, type signatures, predicates, and predicate signatures.) -- The **privately declared** namespaces of ``M`` contain all entities that are declared—that is, defined—in ``M`` and that are annotated as ``private``. -- The **publically declared** namespaces of ``M`` contain all entities that are declared—that is, defined—in ``M`` and that are not annotated as ``private``. +- The **privately declared** namespaces of ``M`` contain all entities and aliases that are declared—that is, defined—in ``M`` and that are annotated as ``private``. +- The **publically declared** namespaces of ``M`` contain all entities and aliases that are declared—that is, defined—in ``M`` and that are not annotated as ``private``. - The **exported** namespaces of ``M`` contain 1. all entries from the **publically declared** namespaces of ``M``, and 2. for each module ``N`` that is imported into ``M`` with an import statement that is not annotated as ``private``: all entries from the **exported** namespaces of ``N`` that do not have the same name as any of the entries in the **publically declared** namespaces of ``M``.