add import ... as ... syntax

NEWS.md

@@ -21,6 +21,8 @@ New language features
   `(x...) -> (op).(x...)`, which can be useful for passing the broadcasted version of an
   operator to higher-order functions, like for example `map(.*, A, B)` for an elementwise
   product of two arrays of arrays. ([#37583])
+* The syntax `import A as B` (plus `import A: x as y`, `import A.x as y`, and `using A: x as y`)
+  can now be used to rename imported modules and identifiers ([#1255]).
 
 Language changes
 ----------------

base/show.jl

@@ -1447,7 +1447,10 @@ function show_generator(io, ex::Expr, indent, quote_level)
     end
 end
 
-function valid_import_path(@nospecialize ex)
+function valid_import_path(@nospecialize(ex), allow_as = true)
+    if allow_as && is_expr(ex, :as) && length((ex::Expr).args) == 2
+        ex = (ex::Expr).args[1]
+    end
     return is_expr(ex, :(.)) && length((ex::Expr).args) > 0 && all(a->isa(a,Symbol), (ex::Expr).args)
 end
 
@@ -1998,6 +2001,10 @@ function show_unquoted(io::IO, ex::Expr, indent::Int, prec::Int, quote_level::In
             first = false
             show_import_path(io, a, quote_level)
         end
+    elseif head === :as && nargs == 2 && valid_import_path(args[1], false)
+        show_import_path(io, args[1], quote_level)
+        print(io, " as ")
+        show_unquoted(io, args[2], indent, 0, quote_level)
     elseif head === :meta && nargs >= 2 && args[1] === :push_loc
         print(io, "# meta: location ", join(args[2:end], " "))
     elseif head === :meta && nargs == 1 && args[1] === :pop_loc

doc/src/manual/modules.md

@@ -13,9 +13,9 @@ is shown for illustrative purposes:
 module MyModule
 using Lib
 
-using BigLib: thing1, thing2
+using BigLib: thing1, thing2, thing3 as t3
 
-import Base.show
+import Base.show, Base.print as pr
 
 export MyType, foo
 
@@ -26,7 +26,7 @@ end
 bar(x) = 2x
 foo(a::MyType) = bar(a.x) + 1
 
-show(io::IO, a::MyType) = print(io, "MyType $(a.x)")
+show(io::IO, a::MyType) = pr(io, "MyType $(a.x)")
 end
 ```
 
@@ -86,6 +86,37 @@ functions into the current workspace:
 | `import MyModule.x, MyModule.p` | `x` and `p`                                                                     | `x` and `p`                                 |
 | `import MyModule: x, p`         | `x` and `p`                                                                     | `x` and `p`                                 |
 
+### Import renaming
+
+An identifier brought into scope by `import` or `using` can be renamed with the keyword `as`.
+This is useful for working around name conflicts as well as for shortening names.
+For example, `Base` exports the function name `read`, but the CSV.jl package also provides `CSV.read`.
+If we are going to invoke CSV reading many times, it would be convenient to drop the `CSV.` qualifier.
+But then it is ambiguous whether we are referring to `Base.read` or `CSV.read`:
+
+```julia
+julia> read;
+
+julia> import CSV.read
+WARNING: ignoring conflicting import of CSV.read into Main
+```
+
+Renaming provides a solution:
+
+```julia
+julia> import CSV.read as rd
+```
+
+Imported packages themselves can also be renamed:
+
+```julia
+import BenchmarkTools as BT
+```
+
+`as` works with `using` only when a single identifier is brought into scope.
+For example `using CSV: read as rd` works, but `using CSV as C` does not, since it operates
+on all of the exported names in `CSV`.
+
 ### Modules and files
 
 Files and file names are mostly unrelated to modules; modules are associated only with module

src/ast.c

@@ -44,7 +44,7 @@ jl_sym_t *exc_sym;     jl_sym_t *error_sym;
 jl_sym_t *new_sym;     jl_sym_t *using_sym;
 jl_sym_t *splatnew_sym;
 jl_sym_t *const_sym;   jl_sym_t *thunk_sym;
-jl_sym_t *foreigncall_sym;
+jl_sym_t *foreigncall_sym; jl_sym_t *as_sym;
 jl_sym_t *global_sym; jl_sym_t *list_sym;
 jl_sym_t *dot_sym;    jl_sym_t *newvar_sym;
 jl_sym_t *boundscheck_sym; jl_sym_t *inbounds_sym;
@@ -363,6 +363,7 @@ void jl_init_common_symbols(void)
     thunk_sym = jl_symbol("thunk");
     toplevel_sym = jl_symbol("toplevel");
     dot_sym = jl_symbol(".");
+    as_sym = jl_symbol("as");
     colon_sym = jl_symbol(":");
     boundscheck_sym = jl_symbol("boundscheck");
     inbounds_sym = jl_symbol("inbounds");

src/ast.scm

@@ -46,6 +46,21 @@
       (string ":" (deparse e))
       (deparse e)))
 
+(define (deparse-import-path e)
+  (cond ((and (pair? e) (eq? (car e) '|.|))
+         (let loop ((lst   (cdr e))
+                    (ndots 0))
+           (if (or (null? lst)
+                   (not (eq? (car lst) '|.|)))
+               (string (string.rep "." ndots)
+                       (string.join (map deparse lst) "."))
+               (loop (cdr lst) (+ ndots 1)))))
+        ((and (pair? e) (eq? (car e) ':))
+         (string (deparse-import-path (cadr e)) ": "
+                 (string.join (map deparse-import-path (cddr e)) ", ")))
+        (else
+         (string e))))
+
 (define (deparse e (ilvl 0))
   (cond ((or (symbol? e) (number? e)) (string e))
         ((string? e) (print-to-string e))
@@ -71,6 +86,8 @@
          (if (length= e 2)
              (string (car e) (deparse (cadr e)))
              (string (deparse (cadr e)) " " (car e) " " (deparse (caddr e)))))
+        ((eq? (car e) 'as)
+         (string (deparse-import-path (cadr e)) " as " (deparse (caddr e))))
         (else
          (case (car e)
            ((null)  "nothing")
@@ -209,21 +226,7 @@
                     "end"))
            ;; misc syntax forms
            ((import using)
-            (define (deparse-path e)
-              (cond ((and (pair? e) (eq? (car e) '|.|))
-                     (let loop ((lst   (cdr e))
-                                (ndots 0))
-                       (if (or (null? lst)
-                               (not (eq? (car lst) '|.|)))
-                           (string (string.rep "." ndots)
-                                   (string.join (map deparse lst) "."))
-                           (loop (cdr lst) (+ ndots 1)))))
-                    ((and (pair? e) (eq? (car e) ':))
-                     (string (deparse-path (cadr e)) ": "
-                             (string.join (map deparse-path (cddr e)) ", ")))
-                    (else
-                     (string e))))
-            (string (car e) " " (string.join (map deparse-path (cdr e)) ", ")))
+            (string (car e) " " (string.join (map deparse-import-path (cdr e)) ", ")))
            ((global local export) (string (car e) " " (string.join (map deparse (cdr e)) ", ")))
            ((const)        (string "const " (deparse (cadr e))))
            ((top)          (deparse (cadr e)))

src/julia-parser.scm

@@ -1580,26 +1580,31 @@
       e))
 
 (define (parse-imports s word)
-  (let* ((first (parse-import s word))
+  (let* ((first (parse-import s word #f))
          (next  (peek-token s))
-         (from  (and (eq? next ':) (not (ts:space? s))))
+         (from  (and (eq? next ':) (not (ts:space? s))
+                     (or (not (and (pair? first) (eq? (car first) 'as)))
+                         (error (string "invalid syntax \"" word " " (deparse first) ":\"")))))
          (done  (cond ((or from (eqv? next #\,))
                        (begin (take-token s) #f))
-                      ((or (eq? next '|.|)
+                      ;; TODO: this seems to be wrong; figure out if it's needed
+                      #;((or (eq? next '|.|)
                            (eqv? (string.sub (string next) 0 1) ".")) #f)
                       (else #t)))
          (rest  (if done
                     '()
                     (let ((ex (parse-comma-separated s (lambda (s)
-                                                         (parse-import s word)))))
+                                                         (parse-import s word from)))))
                       (if (eq? (peek-token s) ':)
                           (error (string "\":\" in \"" word "\" syntax can only be used "
                                          "when importing a single module. "
                                          "Split imports into multiple lines."))
                           ex)))))
     (if from
         `(,word (|:| ,first ,@rest))
-        (list* word first rest))))
+        (begin (if (and (eq? word 'using) (pair? first) (eq? (car first) 'as))
+                   (error (string "invalid syntax \"using " (deparse-import-path (cadr first)) " as ...\"")))
+               (list* word first rest)))))
 
 (define (parse-import-dots s)
   (let loop ((l '())
@@ -1619,7 +1624,7 @@
           (else
            (cons (macrocall-to-atsym (parse-unary-prefix s)) l)))))
 
-(define (parse-import s word)
+(define (parse-import-path s word)
   (let loop ((path (parse-import-dots s)))
     (if (not (symbol-or-interpolate? (car path)))
         (error (string "invalid \"" word "\" statement: expected identifier")))
@@ -1639,6 +1644,16 @@
        (else
         (cons '|.| (reverse path)))))))
 
+(define (parse-import s word from)
+  (let ((path (parse-import-path s word)))
+    (if (eq? (peek-token s) 'as)
+        (begin
+          (if (and (not from) (eq? word 'using))
+              (error (string "invalid syntax \"using " (deparse-import-path path) " as ...\"")))
+          (take-token s)
+          `(as ,path ,(parse-unary-prefix s)))
+        path)))
+
 ;; parse comma-separated assignments, like "i=1:n,j=1:m,..."
 (define (parse-comma-separated s what)
   (let loop ((exprs '()))

src/julia.h

@@ -1474,8 +1474,9 @@ JL_DLLEXPORT void jl_checked_assignment(jl_binding_t *b JL_ROOTING_ARGUMENT, jl_
 JL_DLLEXPORT void jl_declare_constant(jl_binding_t *b);
 JL_DLLEXPORT void jl_module_using(jl_module_t *to, jl_module_t *from);
 JL_DLLEXPORT void jl_module_use(jl_module_t *to, jl_module_t *from, jl_sym_t *s);
-JL_DLLEXPORT void jl_module_import(jl_module_t *to, jl_module_t *from,
-                                   jl_sym_t *s);
+JL_DLLEXPORT void jl_module_use_as(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname);
+JL_DLLEXPORT void jl_module_import(jl_module_t *to, jl_module_t *from, jl_sym_t *s);
+JL_DLLEXPORT void jl_module_import_as(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname);
 JL_DLLEXPORT void jl_module_export(jl_module_t *from, jl_sym_t *s);
 JL_DLLEXPORT int jl_is_imported(jl_module_t *m, jl_sym_t *s);
 JL_DLLEXPORT int jl_module_exports_p(jl_module_t *m, jl_sym_t *var) JL_NOTSAFEPOINT;

src/julia_internal.h

@@ -1242,7 +1242,7 @@ extern jl_sym_t *new_sym;     extern jl_sym_t *using_sym;
 extern jl_sym_t *splatnew_sym;
 extern jl_sym_t *pop_exception_sym;
 extern jl_sym_t *const_sym;   extern jl_sym_t *thunk_sym;
-extern jl_sym_t *foreigncall_sym;
+extern jl_sym_t *foreigncall_sym; extern jl_sym_t *as_sym;
 extern jl_sym_t *global_sym; extern jl_sym_t *list_sym;
 extern jl_sym_t *dot_sym;    extern jl_sym_t *newvar_sym;
 extern jl_sym_t *boundscheck_sym; extern jl_sym_t *inbounds_sym;

src/module.c

@@ -224,14 +224,14 @@ JL_DLLEXPORT jl_binding_t *jl_get_binding_for_method_def(jl_module_t *m, jl_sym_
             }
             else {
                 JL_UNLOCK_NOGC(&m->lock);
-                jl_binding_t *b2 = jl_get_binding(b->owner, var);
+                jl_binding_t *b2 = jl_get_binding(b->owner, b->name);
                 if (b2 == NULL || b2->value == NULL)
                     jl_errorf("invalid method definition: imported function %s.%s does not exist",
-                              jl_symbol_name(b->owner->name), jl_symbol_name(var));
+                              jl_symbol_name(b->owner->name), jl_symbol_name(b->name));
                 // TODO: we might want to require explicitly importing types to add constructors
                 if (!b->imported && !jl_is_type(b2->value)) {
                     jl_errorf("error in method definition: function %s.%s must be explicitly imported to be extended",
-                              jl_symbol_name(b->owner->name), jl_symbol_name(var));
+                              jl_symbol_name(b->owner->name), jl_symbol_name(b->name));
                 }
                 return b2;
             }
@@ -248,7 +248,7 @@ JL_DLLEXPORT jl_binding_t *jl_get_binding_for_method_def(jl_module_t *m, jl_sym_
     return b;
 }
 
-static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s,
+static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname,
                            int explici);
 
 typedef struct _modstack_t {
@@ -331,14 +331,14 @@ static jl_binding_t *jl_get_binding_(jl_module_t *m, jl_sym_t *var, modstack_t *
             // do a full import to prevent the result of this lookup
             // from changing, for example if this var is assigned to
             // later.
-            module_import_(m, b->owner, var, 0);
+            module_import_(m, b->owner, var, var, 0);
             return b;
         }
         return NULL;
     }
     JL_UNLOCK(&m->lock);
     if (b->owner != m)
-        return jl_get_binding_(b->owner, var, &top);
+        return jl_get_binding_(b->owner, b->name, &top);
     return b;
 }
 
@@ -404,7 +404,7 @@ JL_DLLEXPORT int jl_is_imported(jl_module_t *m, jl_sym_t *s)
 }
 
 // NOTE: we use explici since explicit is a C++ keyword
-static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s, int explici)
+static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname, int explici)
 {
     jl_binding_t *b = jl_get_binding(from, s);
     if (b == NULL) {
@@ -431,19 +431,27 @@ static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s, int
         }
 
         JL_LOCK(&to->lock);
-        jl_binding_t **bp = (jl_binding_t**)ptrhash_bp(&to->bindings, s);
+        jl_binding_t **bp = (jl_binding_t**)ptrhash_bp(&to->bindings, asname);
         jl_binding_t *bto = *bp;
         if (bto != HT_NOTFOUND) {
             if (bto == b) {
                 // importing a binding on top of itself. harmless.
             }
+            else if (bto->name != s) {
+                JL_UNLOCK(&to->lock);
+                jl_printf(JL_STDERR,
+                          "WARNING: ignoring conflicting import of %s.%s into %s\n",
+                          jl_symbol_name(from->name), jl_symbol_name(s),
+                          jl_symbol_name(to->name));
+                return;
+            }
             else if (bto->owner == b->owner) {
                 // already imported
                 bto->imported = (explici!=0);
             }
             else if (bto->owner != to && bto->owner != NULL) {
                 // already imported from somewhere else
-                jl_binding_t *bval = jl_get_binding(to, s);
+                jl_binding_t *bval = jl_get_binding(to, asname);
                 if (bval->constp && bval->value && b->constp && b->value == bval->value) {
                     // equivalent binding
                     bto->imported = (explici!=0);
@@ -493,12 +501,22 @@ static void module_import_(jl_module_t *to, jl_module_t *from, jl_sym_t *s, int
 
 JL_DLLEXPORT void jl_module_import(jl_module_t *to, jl_module_t *from, jl_sym_t *s)
 {
-    module_import_(to, from, s, 1);
+    module_import_(to, from, s, s, 1);
+}
+
+JL_DLLEXPORT void jl_module_import_as(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname)
+{
+    module_import_(to, from, s, asname, 1);
 }
 
 JL_DLLEXPORT void jl_module_use(jl_module_t *to, jl_module_t *from, jl_sym_t *s)
 {
-    module_import_(to, from, s, 0);
+    module_import_(to, from, s, s, 0);
+}
+
+JL_DLLEXPORT void jl_module_use_as(jl_module_t *to, jl_module_t *from, jl_sym_t *s, jl_sym_t *asname)
+{
+    module_import_(to, from, s, asname, 0);
 }
 
 JL_DLLEXPORT void jl_module_using(jl_module_t *to, jl_module_t *from)