Add public keyword (#50105)

Co-authored-by: Claire Foster <[email protected]>

base/docs/basedocs.jl

@@ -52,13 +52,23 @@ kw"import"
 """
  export
 
-`export` is used within modules to tell Julia which functions should be
+`export` is used within modules to tell Julia which names should be
 made available to the user. For example: `export foo` makes the name
 `foo` available when [`using`](@ref) the module.
 See the [manual section about modules](@ref modules) for details.
 """
 kw"export"
 
+"""
+ public
+
+`public` is used within modules to tell Julia which names are part of the
+public API of the module . For example: `public foo` indicates that the name
+`foo` is public, without making it available available when [`using`](@ref)
+the module. See the [manual section about modules](@ref modules) for details.
+"""
+kw"public"
+
 """
  as
 

base/exports.jl

@@ -1063,3 +1063,84 @@ export
  @view,
  @views,
  @static
+
+# TODO: use normal syntax once JuliaSyntax.jl becomes available at this point in bootstrapping
+eval(Expr(:public,
+# Modules
+ :Checked,
+ :Filesystem,
+ :Order,
+ :Sort,
+
+# Types
+ :AbstractLock,
+ :AsyncCondition,
+ :CodeUnits,
+ :Event,
+ :Fix1,
+ :Fix2,
+ :Generator,
+ :ImmutableDict,
+ :OneTo,
+ :UUID,
+
+# Semaphores
+ :Semaphore,
+ :acquire,
+ :release,
+
+# collections
+ :IteratorEltype,
+ :IteratorSize,
+ :to_index,
+ :vect,
+ :isdone,
+ :front,
+ :rest,
+ :split_rest,
+ :tail,
+ :checked_length,
+
+# Loading
+ :DL_LOAD_PATH,
+ :load_path,
+ :active_project,
+
+# Reflection and introspection
+ :isambiguous,
+ :isexpr,
+ :isidentifier,
+ :issingletontype,
+ :identify_package,
+ :locate_package,
+ :moduleroot,
+ :jit_total_bytes,
+ :summarysize,
+ :isexported,
+ :ispublic,
+
+# Opperators
+ :operator_associativity,
+ :operator_precedence,
+ :isbinaryoperator,
+ :isoperator,
+ :isunaryoperator,
+
+# C interface
+ :cconvert,
+ :unsafe_convert,
+
+# Error handling
+ :exit_on_sigint,
+ :windowserror,
+
+# Macros
+ Symbol("@assume_effects"),
+ Symbol("@constprop"),
+ Symbol("@locals"),
+ Symbol("@propagate_inbounds"),
+
+# misc
+ :notnothing,
+ :runtests,
+ :text_colors))

base/reflection.jl

@@ -75,24 +75,100 @@ end
 """
  names(x::Module; 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 a `Module`, excluding deprecated names.
+If `all` is true, then the list also includes non-public 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 explicitly mark names from `Main` as public.
 
-See also: [`@locals`](@ref Base.@locals), [`@__MODULE__`](@ref).
+See also: [`isexported`](@ref), [`ispublic`](@ref), [`@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)
 
+"""
+ isexported(m::Module, s::Symbol) -> Bool
+
+Returns whether a symbol is exported from a module.
+
+See also: [`ispublic`](@ref), [`names`](@ref)
+
+```jldoctest
+julia> module Mod
+ export foo
+ public bar
+ end
+Mod
+
+julia> Base.isexported(Mod, :foo)
+true
+
+julia> Base.isexported(Mod, :bar)
+false
+
+julia> Base.isexported(Mod, :baz)
+false
+```
+"""
 isexported(m::Module, s::Symbol) = ccall(:jl_module_exports_p, Cint, (Any, Any), m, s) != 0
+
+"""
+ ispublic(m::Module, s::Symbol) -> Bool
+
+Returns whether a symbol is marked as public in a module.
+
+Exported symbols are considered public.
+
+See also: [`isexported`](@ref), [`names`](@ref)
+
+```jldoctest
+julia> module Mod
+ export foo
+ public bar
+ end
+Mod
+
+julia> Base.ispublic(Mod, :foo)
+true
+
+julia> Base.ispublic(Mod, :bar)
+true
+
+julia> Base.ispublic(Mod, :baz)
+false
+```
+"""
+ispublic(m::Module, s::Symbol) = ccall(:jl_module_public_p, Cint, (Any, Any), m, s) != 0
+
+# TODO: this is vaguely broken because it only works for explicit calls to
+# `Base.deprecate`, not the @deprecated macro:
 isdeprecated(m::Module, s::Symbol) = ccall(:jl_is_binding_deprecated, Cint, (Any, Any), m, s) != 0
+
+"""
+ isbindingresolved(m::Module, s::Symbol) -> Bool
+
+Returns whether the binding of a symbol in a module is resolved.
+
+See also: [`isexported`](@ref), [`ispublic`](@ref), [`isdeprecated`](@ref)
+
+```jldoctest
+julia> module Mod
+ foo() = 17
+ end
+Mod
+
+julia> Base.isbindingresolved(Mod, :foo)
+true
+
+julia> Base.isbindingresolved(Mod, :bar)
+false
+```
+"""
 isbindingresolved(m::Module, var::Symbol) = ccall(:jl_binding_resolved_p, Cint, (Any, Any), m, var) != 0
 
 function binding_module(m::Module, s::Symbol)

base/show.jl

@@ -2226,7 +2226,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 = 045d156c44dbb87769c7416d049a7c08908539d4
+JULIASYNTAX_SHA1 = a9110fa8ecbe79943bb9525b4ccd99a3976cfcb7
 JULIASYNTAX_GIT_URL := https://github.com/JuliaLang/JuliaSyntax.jl.git
 JULIASYNTAX_TAR_URL = https://api.github.com/repos/JuliaLang/JuliaSyntax.jl/tarball/$1

deps/checksums/JuliaSyntax-a9110fa8ecbe79943bb9525b4ccd99a3976cfcb7.tar.gz/md5

@@ -0,0 +1 @@
+a42bbb42babbbd727556f6bc01455826

deps/checksums/JuliaSyntax-a9110fa8ecbe79943bb9525b4ccd99a3976cfcb7.tar.gz/sha512

@@ -0,0 +1 @@
+d542766e72b57418b9b4e17743f89d8535c1f36497346b57538bd0cb451e64af9493015692179f80ec4ee8cf18349c1e0888f5710db895e19f9bb0322f0f7464

doc/src/base/base.md

@@ -60,13 +60,15 @@ However, you can create variables with names:
 Finally:
 `where` is parsed as an infix operator for writing parametric method and type definitions;
 `in` and `isa` are parsed as infix operators;
+`public` is parsed as a keyword when beginning a toplevel statement;
 `outer` is parsed as a keyword when used to modify the scope of a variable in an iteration specification of a `for` loop;
 and `as` is used as a keyword to rename an identifier brought into scope by `import` or `using`.
 Creation of variables named `where`, `in`, `isa`, `outer` and `as` is allowed, though.
 
 ```@docs
 module
 export
+public
 import
 using
 as
@@ -451,6 +453,8 @@ Base.@__DIR__
 Base.@__LINE__
 Base.fullname
 Base.names
+Base.isexported
+Base.ispublic
 Base.nameof(::Function)
 Base.functionloc(::Any, ::Any)
 Base.functionloc(::Method)

doc/src/base/reflection.md

@@ -4,9 +4,9 @@ Julia provides a variety of runtime reflection capabilities.
 
 ## Module bindings
 
-The exported names for a `Module` are available using [`names(m::Module)`](@ref), which will return
-an array of [`Symbol`](@ref) elements representing the exported bindings. `names(m::Module, all = true)`
-returns symbols for all bindings in `m`, regardless of export status.
+The public names for a `Module` are available using [`names(m::Module)`](@ref), which will return
+an array of [`Symbol`](@ref) elements representing the public bindings. `names(m::Module, all = true)`
+returns symbols for all bindings in `m`, regardless of public status.
 
 ## DataType fields
 

doc/src/manual/faq.md

@@ -22,11 +22,28 @@ 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`.
+
+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.
 
 ### There is a useful undocumented function/type/constant. Can I use it?
 

doc/src/manual/modules.md

@@ -7,7 +7,8 @@ Modules in Julia help organize code into coherent units. They are delimited synt
  allows the same name to be used for different functions or global variables without conflict, as long as they are in separate modules.
 
 2. Modules have facilities for detailed namespace management: each defines a set of names it
- `export`s, and can import names from other modules with `using` and `import` (we explain these below).
+ `export`s and marks as `public`, and can import names from other modules with `using` and
+ `import` (we explain these below).
 
 3. Modules can be precompiled for faster loading, and may contain code for runtime initialization.
 
@@ -16,7 +17,7 @@ Typically, in larger Julia packages you will see module code organized into file
 ```julia
 module SomeModule
 
-# export, using, import statements are usually here; we discuss these below
+# export, public, using, import statements are usually here; we discuss these below
 
 include("file1.jl")
 include("file2.jl")
@@ -103,6 +104,10 @@ Also, some modules don't export names at all. This is usually done if they use c
 words, such as `derivative`, in their API, which could easily clash with the export lists of other
 modules. We will see how to manage name clashes below.
 
+To mark a name as public without exporting it into the namespace of folks who call `using NiceStuff`,
+one can use `public` instead of `export`. This marks the public name(s) as part of the public API,
+but does not have any namespace implications.
+
 ### Standalone `using` and `import`
 
 Possibly the most common way of loading a module is `using ModuleName`. This [loads](@ref

doc/src/manual/noteworthy-differences.md

@@ -413,15 +413,16 @@ For users coming to Julia from R, these are some noteworthy differences:
  file are `include`d only once (No `#ifdef` confusion).
 
 ### Julia ⇔ C/C++: Module interface
- * C++ exposes interfaces using "public" `.h`/`.hpp` files whereas Julia `module`s `export`
- symbols that are intended for their users.
+ * C++ exposes interfaces using "public" `.h`/`.hpp` files whereas Julia `module`s mark
+ specific symbols that are intended for their users as `public`or `export`ed.
  * Often, Julia `module`s simply add functionality by generating new "methods" to existing
  functions (ex: `Base.push!`).
  * Developers of Julia packages therefore cannot rely on header files for interface
  documentation.
  * Interfaces for Julia packages are typically described using docstrings, README.md,
  static web pages, ...
- * Some developers choose not to `export` all symbols required to use their package/module.
+ * Some developers choose not to `export` all symbols required to use their package/module,
+ but should still mark unexported user facing symbols as `public`.
  * Users might be expected to access these components by qualifying functions/structs/...
  with the package/module name (ex: `MyModule.run_this_task(...)`).
 

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

@@ -1939,7 +1939,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