Support requiring namespaces as aliases only (#840)

Fixes #664

Author: chrisrink10

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Added support for `thrown-with-msg?` assertions to `basilisp.test/is` (#831)
  * Added support for reading scientific notation literals, octal and hex integer literals, and arbitrary base (2-36) integer literals (#769)
  * Added support for passing trailing maps to functions which accept Basilisp keyword arguments (#663)
+ * Added support for loading namespaces as an alias only (#664)
 
 ### Changed
  * Optimize calls to Python's `operator` module into their corresponding native operators (#754)

docs/concepts.rst

@@ -10,6 +10,8 @@ Concepts
 Seqs
 ----
 
+TBD
+
 .. _macros:
 
 Macros

src/basilisp/core.lpy

@@ -4723,6 +4723,9 @@
   Optional keys:
 
   - ``:as ns-alias`` a symbol which will alias the Namespace when required (if given)
+  - ``:as-alias ns-alias`` a symbol which will alias the Namespace when required; if
+    the namespace does not exist, it will be created as an empty namespace; if it does
+    exist, it will not be loaded
   - ``:refer [sym1, sym2]`` a sequence of symbols naming Vars to refer
   - ``:refer :all`` if every Var should be referred
   - ``:only [sym1, sym2]`` a sequence of symbols naming Vars to refer
@@ -4761,6 +4764,9 @@
     ;; rewrote the namespace on require.
     (when-let [original-ns (:original-namespace libspec)]
       (.add-alias requiring-ns (the-ns required-ns-sym) original-ns))
+    ;; If an `:as-alias` is requested, apply that as well.
+    (when-let [as-alias (:as-alias libspec)]
+      (.add-alias requiring-ns (the-ns required-ns-sym) as-alias))
     ;; Reset the namespace to the requiring namespace, since it was likely changed
     ;; during the require process
     (set! *ns* requiring-ns)))
@@ -4812,6 +4818,9 @@
   Vector libspec arguments must be one of:
 
   - ``:as name`` which will alias the imported namespace to the symbol name
+  - ``:as-alias name`` which will alias the namespace to the symbol name but not
+    require the namespace, which can be useful for namespaces used primarily for
+    keywords; the namespace need not exist at all; can be combined with ``:as``
   - ``:refer [& syms]`` which will refer syms in the local namespace directly
   - ``:refer :all`` which will refer all symbols from the namespace directly
 
@@ -4820,22 +4829,27 @@
   [& args]
   (let [current-ns *ns*]
     (doseq [libspec (map require-libspec args)]
-      (require-lib current-ns libspec)
-
-      ;; Add refers
-      (let [new-ns    (the-ns (:namespace libspec))
-            refer-opt (:refer libspec)]
-        (cond
-          (= :all refer-opt)
-          (.refer-all current-ns new-ns)
+      (if (and (:as-alias libspec) (not (:as libspec)))
+        (let [alias-target (or (find-ns (:namespace libspec))
+                               (create-ns (:namespace libspec)))]
+          (.add-alias current-ns alias-target (:as-alias libspec)))
+        (do
+          (require-lib current-ns libspec)
+
+          ;; Add refers
+          (let [new-ns    (the-ns (:namespace libspec))
+                refer-opt (:refer libspec)]
+            (cond
+              (= :all refer-opt)
+              (.refer-all current-ns new-ns)
 
-          (seq refer-opt)
-          (let [new-ns-interns (ns-interns new-ns)]
-            (doseq [var-sym refer-opt]
-              (let [var (get new-ns-interns var-sym)]
-                (.add-refer current-ns var-sym var))))
+              (seq refer-opt)
+              (let [new-ns-interns (ns-interns new-ns)]
+                (doseq [var-sym refer-opt]
+                  (let [var (get new-ns-interns var-sym)]
+                    (.add-refer current-ns var-sym var))))
 
-          :else nil)))
+              :else nil)))))
     nil))
 
 (defn refer
@@ -4926,7 +4940,25 @@
          [basilisp.string :as str])
        (:use
          [basilisp.set :only [intersection]])
-       (:import inspect))"
+       (:import inspect))
+
+  Flags and contents of each of the various sections are detailed further at each of
+  their respective function definitions.
+
+   - ``:refer-basilisp`` (``:refer-clojure`` is also accepted) controls how names from
+     :lpy:ns:`basilisp.core` are exposed in the namespace. Refer to :lpy:fn:`refer` for
+     usage.
+   - ``:require`` imports other Basilisp namespaces. Refer to :lpy:fn:`require` for
+     usage.
+   - ``:use`` is a variant of ``:require``, although ``:require`` is preferred in most
+     cases. See :lpy:fn:`use` for usage.
+   - ``:import`` imports Python modules and packages. Refer to :lpy:fn:`import` for
+     usage.
+
+  Use of the ``ns`` macro to control requires and imports is recommended in all cases.
+  The various functions that ``ns`` delegates to and whose documentation are referred
+  to above are generally useful for interactive usage at the REPL but not appropriate
+  for usage in a larger application."
   [name & opts]
   (when-not (and (symbol? name) (nil? (namespace name)))
     (throw (ex-info "Namespace name must be a non-namespaced symbol"
@@ -4966,8 +4998,8 @@
        ~@imports)))
 
 (defn requiring-resolve
-  "Resolve the namespaced symbol ``sym`` as by ``resolve``\\. If resolution fails,
-  attempts to require ``sym`` 's namespace (as by ``require``\\) before resolving
+  "Resolve the namespaced symbol ``sym`` as by :lpy:fn:`resolve`\\. If resolution fails,
+  attempts to require ``sym`` 's namespace (as by :lpy:fn:`require`\\) before resolving
   again."
   [sym]
   (if (qualified-symbol? sym)

tests/basilisp/namespace_test.py

@@ -8,7 +8,7 @@
 from basilisp.lang import runtime as runtime
 from basilisp.lang import symbol as sym
 from basilisp.lang.runtime import Namespace, NamespaceMap, Var
-from tests.basilisp.helpers import get_or_create_ns
+from tests.basilisp.helpers import CompileFn, get_or_create_ns
 
 
 @pytest.fixture
@@ -272,6 +272,34 @@ def test_alias(ns_cache: atom.Atom[NamespaceMap]):
     assert None is ns1.get_alias(sym.symbol("n2"))
 
 
+class TestRequireAsAlias:
+    @pytest.fixture
+    def test_ns(self) -> str:
+        return "basilisp.require-as-alias-test"
+
+    @pytest.fixture
+    def compiler_file_path(self) -> str:
+        return "require_as_alias_test"
+
+    def test_requires_and_allows_aliasing(self, lcompile: CompileFn):
+        lcompile("(require '[basilisp.json :as-alias json])")
+        assert lcompile("::json/some-kw") == kw.keyword("some-kw", ns="basilisp.json")
+
+    def test_can_be_combined_with_normal_require(self, lcompile: CompileFn):
+        lcompile("(require '[basilisp.json :as json :as-alias json-alias])")
+        assert lcompile("::json/some-kw") == kw.keyword("some-kw", ns="basilisp.json")
+        assert lcompile("::json-alias/some-kw") == kw.keyword(
+            "some-kw", ns="basilisp.json"
+        )
+
+    def test_need_not_be_real_ns(self, lcompile: CompileFn):
+        lcompile("(require '[basilisp.require-alias-test-ns :as-alias test-ns])")
+        assert lcompile("::test-ns/some-kw") == kw.keyword(
+            "some-kw", ns="basilisp.require-alias-test-ns"
+        )
+        assert lcompile("(ns-publics 'basilisp.require-alias-test-ns)") == lmap.m()
+
+
 class TestCompletion:
     @pytest.fixture
     def ns(self) -> Namespace: