Add public keyword

base/exports.jl

@@ -1063,3 +1063,71 @@ export
     @view,
     @views,
     @static
+
+# TODO: use normal syntax once JuliaSyntax.jl becomes available at this point in bootstrapping
+eval(Expr(:public,
+    Symbol("@assume_effects"),
+    Symbol("@constprop"),
+    Symbol("@locals"),
+    Symbol("@propagate_inbounds"),
+    :AbstractLock,
+    :AsyncCondition,
+    :CFunction,
+    :Checked,
+    :CodeUnits,
+    :DL_LOAD_PATH,
+    :EnvDict,
+    :Event,
+    :Fix1,
+    :Fix2,
+    :Generator,
+    :ImmutableDict,
+    :IteratorEltype,
+    :IteratorSize,
+    :OneTo,
+    :Pairs,
+    :Semaphore,
+    :UUID,
+    :acquire,
+    :active_project,
+    :add_sum,
+    :cconvert,
+    :checked_length,
+    :compilecache,
+    :datatype_alignment,
+    :datatype_haspadding,
+    :datatype_pointerfree,
+    :elsize,
+    :exit_on_sigint,
+    :front,
+    :identify_package,
+    :include,
+    :isambiguous,
+    :isbinaryoperator,
+    :isdone,
+    :isexpr,
+    :isidentifier,
+    :isoperator,
+    :issingletontype,
+    :isunaryoperator,
+    :jit_total_bytes,
+    :load_path,
+    :locate_package,
+    :moduleroot,
+    :notnothing,
+    :operator_associativity,
+    :operator_precedence,
+    :promote_typejoin,
+    :release,
+    :require,
+    :rest,
+    :runtests,
+    :set_active_project,
+    :split_rest,
+    :summarysize,
+    :tail,
+    :text_colors,
+    :to_index,
+    :unsafe_convert,
+    :vect,
+    :windowserror))

base/reflection.jl

@@ -73,25 +73,28 @@ function fullname(m::Module)
 end
 
 """
-    names(x::Module; all::Bool = false, imported::Bool = false)
+    names(x::Module; qualified::Bool=true, all::Bool = false, imported::Bool = false)
 
-Get an array of the names exported by a `Module`, excluding deprecated names.
-If `all` is true, then the list also includes non-exported names defined in the module,
+Get an array of the public names of `Module`, excluding deprecated names.
+
+If `qualified` is false, then return only exported names, not public but unexported names.
+If `all` is true, then the list also includes private names defined in the module,
 deprecated names, and compiler-generated names.
 If `imported` is true, then names explicitly imported from other modules
 are also included.
 
-As a special case, all names defined in `Main` are considered \"exported\",
-since it is not idiomatic to explicitly export names from `Main`.
+As a special case, all names defined in `Main` are considered \"public\",
+since it is not idiomatic to mark names from `Main` as public.
 
 See also: [`@locals`](@ref Base.@locals), [`@__MODULE__`](@ref).
 """
-names(m::Module; all::Bool = false, imported::Bool = false) =
-    sort!(unsorted_names(m; all, imported))
-unsorted_names(m::Module; all::Bool = false, imported::Bool = false) =
-    ccall(:jl_module_names, Array{Symbol,1}, (Any, Cint, Cint), m, all, imported)
+names(m::Module; qualified::Bool = true, all::Bool = false, imported::Bool = false) =
+    sort!(unsorted_names(m; qualified, all, imported))
+unsorted_names(m::Module; qualified::Bool = true, all::Bool = false, imported::Bool = false) =
+    ccall(:jl_module_names, Array{Symbol,1}, (Any, Cint, Cint, Cint), m, qualified, all, imported)
 
 isexported(m::Module, s::Symbol) = ccall(:jl_module_exports_p, Cint, (Any, Any), m, s) != 0
+isinternal(m::Module, s::Symbol) = ccall(:jl_module_public_p, Cint, (Any, Any), m, s) == 0
 isdeprecated(m::Module, s::Symbol) = ccall(:jl_is_binding_deprecated, Cint, (Any, Any), m, s) != 0
 isbindingresolved(m::Module, var::Symbol) = ccall(:jl_binding_resolved_p, Cint, (Any, Any), m, var) != 0
 

base/show.jl

@@ -2232,7 +2232,7 @@ function show_unquoted(io::IO, ex::Expr, indent::Int, prec::Int, quote_level::In
         print(io, head, ' ')
         show_list(io, args, ", ", indent, 0, quote_level)
 
-    elseif head === :export
+    elseif head in (:export, :public)
         print(io, head, ' ')
         show_list(io, mapany(allow_macroname, args), ", ", indent)
 

deps/JuliaSyntax.version

@@ -1,4 +1,4 @@
-JULIASYNTAX_BRANCH = main
-JULIASYNTAX_SHA1 = 8731bab86f14762cca8cf24224d8c7a6a89c21c5
-JULIASYNTAX_GIT_URL := https://github.com/JuliaLang/JuliaSyntax.jl.git
-JULIASYNTAX_TAR_URL = https://api.github.com/repos/JuliaLang/JuliaSyntax.jl/tarball/$1
+JULIASYNTAX_BRANCH = scoped-export
+JULIASYNTAX_SHA1 = 22754c8d6bf2c12f780e7d2cd9625a4d19688c3c
+JULIASYNTAX_GIT_URL := https://github.com/LilithHafner/JuliaSyntax.jl.git
+JULIASYNTAX_TAR_URL = https://api.github.com/repos/LilithHafner/JuliaSyntax.jl/tarball/$1

deps/checksums/JuliaSyntax-22754c8d6bf2c12f780e7d2cd9625a4d19688c3c.tar.gz/md5

@@ -0,0 +1 @@
+f70088fa8cf1b2f88c0df71bb16e7a81

deps/checksums/JuliaSyntax-22754c8d6bf2c12f780e7d2cd9625a4d19688c3c.tar.gz/sha512

@@ -0,0 +1 @@
+76017ca5ff287de975a8a0708b06781a7f6bb45c5c7d8294f0aba388ade75fbdeeb295c4f4b0d5df829a1b35a47e881cd97e4ea4ea651d1977085656d14b64e3

doc/src/manual/faq.md

@@ -22,11 +22,36 @@ On the other hand, language *interoperability* is extremely useful: we want to e
 
 ### How does Julia define its public API?
 
-Julia `Base` and standard library functionality described in the
-[the documentation](https://docs.julialang.org/) that is not marked as unstable
-(e.g. experimental and internal) is covered by [SemVer](https://semver.org/).
-Functions, types, and constants are not part of the public API if they are not
-included in the documentation, _even if they have docstrings_.
+Julia's public [API](https://en.wikipedia.org/wiki/API) is the behavior described in
+documentation of public symbols from `Base` and the standard libraries. Functions,
+types, and constants are not part of the public API if they are not public, even if
+they have docstrings or are described in the documentation. Further, only the documented
+behavior of public symbols is part of the public API. Undocumented behavior of public
+symbols is internal.
+
+Public symbols are those marked with either `public foo` or `export foo`.
+Exported symbols are automatically considered public
+
+In other words:
+
+- Documented behavior of public symbols is part of the public API.
+
+- Undocumented behavior of public symbols is not part of the public API.
+
+- Documented behavior of private symbols is not part of the public API.
+
+- Undocumented behavior of private symbols is not part of the public API.
+
+You can get a complete list of the public symbols from a module with `names(MyModule)`.
+
+Package authors are encouraged to define their public API similarly.
+
+Anything in Julia's Public API is covered by [SemVer](https://semver.org/) and therefore
+will not be removed or receive meaningful breaking changes before Julia 2.0.
+
+### When is Julia 2.0 coming out?
+
+2047
 
 ### There is a useful undocumented function/type/constant. Can I use it?
 

src/ast.c

@@ -28,6 +28,7 @@ JL_DLLEXPORT jl_sym_t *jl_top_sym;
 JL_DLLEXPORT jl_sym_t *jl_module_sym;
 JL_DLLEXPORT jl_sym_t *jl_slot_sym;
 JL_DLLEXPORT jl_sym_t *jl_export_sym;
+JL_DLLEXPORT jl_sym_t *jl_public_sym;
 JL_DLLEXPORT jl_sym_t *jl_import_sym;
 JL_DLLEXPORT jl_sym_t *jl_toplevel_sym;
 JL_DLLEXPORT jl_sym_t *jl_quote_sym;
@@ -304,6 +305,7 @@ void jl_init_common_symbols(void)
     jl_lambda_sym = jl_symbol("lambda");
     jl_module_sym = jl_symbol("module");
     jl_export_sym = jl_symbol("export");
+    jl_public_sym = jl_symbol("public");
     jl_import_sym = jl_symbol("import");
     jl_using_sym = jl_symbol("using");
     jl_assign_sym = jl_symbol("=");

src/builtins.c

@@ -1927,7 +1927,7 @@ static void add_intrinsic(jl_module_t *inm, const char *name, enum intrinsic f)
     jl_value_t *i = jl_permbox32(jl_intrinsic_type, 0, (int32_t)f);
     jl_sym_t *sym = jl_symbol(name);
     jl_set_const(inm, sym, i);
-    jl_module_export(inm, sym);
+    jl_module_public(inm, sym, 1);
 }
 
 void jl_init_intrinsic_properties(void) JL_GC_DISABLED

src/jl_exported_funcs.inc

@@ -325,13 +325,14 @@
     XX(jl_methtable_lookup) \
     XX(jl_mi_cache_insert) \
     XX(jl_module_build_id) \
-    XX(jl_module_export) \
     XX(jl_module_exports_p) \
     XX(jl_module_globalref) \
     XX(jl_module_import) \
     XX(jl_module_name) \
     XX(jl_module_names) \
     XX(jl_module_parent) \
+    XX(jl_module_public) \
+    XX(jl_module_public_p) \
     XX(jl_module_use) \
     XX(jl_module_using) \
     XX(jl_module_usings) \

src/julia-syntax.scm

@@ -2364,7 +2364,7 @@
       `(= ,lhs ,rhs)))
 
 (define (expand-forms e)
-  (if (or (atom? e) (memq (car e) '(quote inert top core globalref outerref module toplevel ssavalue null true false meta using import export thismodule toplevel-only)))
+  (if (or (atom? e) (memq (car e) '(quote inert top core globalref outerref module toplevel ssavalue null true false meta using import export public thismodule toplevel-only)))
       e
       (let ((ex (get expand-table (car e) #f)))
         (if ex
@@ -3708,7 +3708,7 @@ f(x) = yt(x)
          thunk with-static-parameters toplevel-only
          global globalref outerref const-if-global thismodule
          const atomic null true false ssavalue isdefined toplevel module lambda
-         error gc_preserve_begin gc_preserve_end import using export inline noinline)))
+         error gc_preserve_begin gc_preserve_end import using export public inline noinline)))
 
 (define (local-in? s lam (tab #f))
   (or (and tab (has? tab s))
@@ -4836,7 +4836,7 @@ f(x) = yt(x)
                val))
 
             ;; other top level expressions
-            ((import using export)
+            ((import using export public)
              (check-top-level e)
              (emit e)
              (let ((have-ret? (and (pair? code) (pair? (car code)) (eq? (caar code) 'return))))

src/julia.h

@@ -594,11 +594,12 @@ typedef struct _jl_binding_t {
     _Atomic(struct _jl_binding_t*) owner;  // for individual imported bindings (NULL until 'resolved')
     _Atomic(jl_value_t*) ty;  // binding type
     uint8_t constp:1;
-    uint8_t exportp:1;
+    uint8_t exportp:1; // `public foo` sets `publicp`, `export foo` sets both `publicp` and `exportp`
+    uint8_t publicp:1; // exportp without publicp is not allowed.
     uint8_t imported:1;
     uint8_t usingfailed:1;
     uint8_t deprecated:2; // 0=not deprecated, 1=renamed, 2=moved to another package
-    uint8_t padding:2;
+    uint8_t padding:1;
 } jl_binding_t;
 
 typedef struct {
@@ -1736,7 +1737,7 @@ JL_DLLEXPORT void jl_module_use(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 void jl_module_public(jl_module_t *from, jl_sym_t *s, int exp);
 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_DLLEXPORT void jl_add_standard_imports(jl_module_t *m);

src/julia_internal.h

@@ -1498,6 +1498,7 @@ extern JL_DLLEXPORT jl_sym_t *jl_top_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_module_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_slot_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_export_sym;
+extern JL_DLLEXPORT jl_sym_t *jl_public_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_import_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_toplevel_sym;
 extern JL_DLLEXPORT jl_sym_t *jl_quote_sym;

src/module.c

@@ -49,7 +49,7 @@ JL_DLLEXPORT jl_module_t *jl_new_module_(jl_sym_t *name, jl_module_t *parent, ui
     if (default_names) {
         jl_set_const(m, name, (jl_value_t*)m);
     }
-    jl_module_export(m, name);
+    jl_module_public(m, name, 1);
     JL_GC_POP();
     return m;
 }
@@ -670,10 +670,11 @@ JL_DLLEXPORT void jl_module_using(jl_module_t *to, jl_module_t *from)
     }
 }
 
-JL_DLLEXPORT void jl_module_export(jl_module_t *from, jl_sym_t *s)
+JL_DLLEXPORT void jl_module_public(jl_module_t *from, jl_sym_t *s, int exp)
 {
     jl_binding_t *b = jl_get_module_binding(from, s, 1);
-    b->exportp = 1;
+    b->publicp = 1;
+    b->exportp = exp;
 }
 
 JL_DLLEXPORT int jl_boundp(jl_module_t *m, jl_sym_t *var)
@@ -694,6 +695,12 @@ JL_DLLEXPORT int jl_module_exports_p(jl_module_t *m, jl_sym_t *var)
     return b && b->exportp;
 }
 
+JL_DLLEXPORT int jl_module_public_p(jl_module_t *m, jl_sym_t *var)
+{
+    jl_binding_t *b = jl_get_module_binding(m, var, 0);
+    return b && b->publicp;
+}
+
 JL_DLLEXPORT int jl_binding_resolved_p(jl_module_t *m, jl_sym_t *var)
 {
     jl_binding_t *b = jl_get_module_binding(m, var, 0);
@@ -934,7 +941,7 @@ JL_DLLEXPORT jl_value_t *jl_module_usings(jl_module_t *m)
     return (jl_value_t*)a;
 }
 
-JL_DLLEXPORT jl_value_t *jl_module_names(jl_module_t *m, int all, int imported)
+JL_DLLEXPORT jl_value_t *jl_module_names(jl_module_t *m, int qualified, int all, int imported)
 {
     jl_array_t *a = jl_alloc_array_1d(jl_array_symbol_type, 0);
     JL_GC_PUSH1(&a);
@@ -945,7 +952,7 @@ JL_DLLEXPORT jl_value_t *jl_module_names(jl_module_t *m, int all, int imported)
             break;
         jl_sym_t *asname = b->globalref->name;
         int hidden = jl_symbol_name(asname)[0]=='#';
-        if ((b->exportp ||
+        if (((qualified ? b->publicp : b->exportp) ||
              (imported && b->imported) ||
              (jl_atomic_load_relaxed(&b->owner) == b && !b->imported && (all || m == jl_main_module))) &&
             (all || (!b->deprecated && !hidden))) {

src/toplevel.c

@@ -560,6 +560,7 @@ int jl_is_toplevel_only_expr(jl_value_t *e) JL_NOTSAFEPOINT
          ((jl_expr_t*)e)->head == jl_import_sym ||
          ((jl_expr_t*)e)->head == jl_using_sym ||
          ((jl_expr_t*)e)->head == jl_export_sym ||
+         ((jl_expr_t*)e)->head == jl_public_sym ||
          ((jl_expr_t*)e)->head == jl_thunk_sym ||
          ((jl_expr_t*)e)->head == jl_global_sym ||
          ((jl_expr_t*)e)->head == jl_const_sym ||
@@ -575,8 +576,9 @@ int jl_needs_lowering(jl_value_t *e) JL_NOTSAFEPOINT
     jl_expr_t *ex = (jl_expr_t*)e;
     jl_sym_t *head = ex->head;
     if (head == jl_module_sym || head == jl_import_sym || head == jl_using_sym ||
-        head == jl_export_sym || head == jl_thunk_sym || head == jl_toplevel_sym ||
-        head == jl_error_sym || head == jl_incomplete_sym || head == jl_method_sym) {
+        head == jl_export_sym || head == jl_public_sym || head == jl_thunk_sym ||
+        head == jl_toplevel_sym || head == jl_error_sym || head == jl_incomplete_sym ||
+        head == jl_method_sym) {
         return 0;
     }
     if (head == jl_global_sym || head == jl_const_sym) {
@@ -837,12 +839,14 @@ jl_value_t *jl_toplevel_eval_flex(jl_module_t *JL_NONNULL m, jl_value_t *e, int
         JL_GC_POP();
         return jl_nothing;
     }
-    else if (head == jl_export_sym) {
+    else if (head == jl_export_sym || head == jl_public_sym) {
+        int exp = (head == jl_export_sym);
         for (size_t i = 0; i < jl_array_len(ex->args); i++) {
             jl_sym_t *name = (jl_sym_t*)jl_array_ptr_ref(ex->args, i);
             if (!jl_is_symbol(name))
-                jl_eval_errorf(m, "syntax: malformed \"export\" statement");
-            jl_module_export(m, name);
+                jl_eval_errorf(m, exp ? "syntax: malformed \"export\" statement" :
+                                        "syntax: malformed \"public\" statement");
+            jl_module_public(m, name, exp);
         }
         JL_GC_POP();
         return jl_nothing;

stdlib/REPL/src/REPLCompletions.jl

@@ -170,7 +170,7 @@ function complete_symbol(@nospecialize(ex), name::String, @nospecialize(ffunc),
         # as excluding Main.Main.Main, etc., because that's most likely not what
         # the user wants
         p = let mod=mod, modname=nameof(mod)
-            (s::Symbol) -> !Base.isdeprecated(mod, s) && s != modname && ffunc(mod, s)::Bool
+            (s::Symbol) -> !Base.isdeprecated(mod, s) && !Base.isinternal(mod, s) && s != modname && ffunc(mod, s)::Bool
         end
         # Looking for a binding in a module
         if mod == context_module

stdlib/REPL/src/docview.jl

@@ -148,6 +148,9 @@ end
 
 _trimdocs(md, brief::Bool) = md, false
 
+const INTERNAL_WARNING = Markdown.Paragraph("Warning: this symbol may be internal. \
+    Behavior documented here might change in future versions.")
+
 """
     Docs.doc(binding, sig)
 
@@ -191,6 +194,9 @@ function doc(binding::Binding, sig::Type = Union{})
         end
         # Get parsed docs and concatenate them.
         md = catdoc(mapany(parsedoc, results)...)
+
+        Base.isinternal(binding.mod, binding.var) && pushfirst!(md.content, INTERNAL_WARNING)
+
         # Save metadata in the generated markdown.
         if isa(md, Markdown.MD)
             md.meta[:results] = results