reflection: refine and accurately define the options for names (#54659)

This commit refines the keyword arguments that `names` can accept,
allowing for more specific exclusions, such as excluding deprecated
names or implicitly `using`-ed names.
For the new behavior of `names`, please refer to the following
docstring:

>     names(x::Module; non_public::Bool=false, imported::Bool=false,
> usings_explicit::Bool=false, usings_implicit::Bool=false,
>                      generated::Bool=false, deprecated::Bool=false,
> [usings::Bool=false], [all::Bool=false]) -> Vector{Symbol}
>
> Return a vector of the sorted names of module `x`.
>
> By default, only public names defined within `x` are returned.
>
> By specifying the following keyword arguments, additional names can be
included:
> - `non_public=true`: includes names defined within `x` that are not
public.
> - `imported=true`: includes names explicitly imported from other
modules via `import` statements.
> - `usings_explicit=true`: includes names explicitly imported from
other modules via `using` statements.
> - `usings_implicit=true`: includes names implicitly imported from
other modules via `using` statements
  (i.e., names exported by modules that `x` has `using`-ed).
> - `generated=true`: includes names generated by the compiler frontend
(specifically those starting with `#`).
> - `deprecated=true`: includes deprecated names.

Note that the previously existing options (`all` and `usings`) are
retained as alias arguments, ensuring that the previous behavior of
`names` is preserved.
> Additionally, the following keyword arguments can be used as aliases
to conveniently specify these options:
> - `usings::Bool=true`: a shortcut to set both `usings_explicit` and
`usings_implicit` to `true`.
> - `all::Bool=true`: a shortcut to set `non_public`, `generated`, and
`deprecated` to `true`.

By utilizing these newly and accurately defined options, the
implementation of downstream applications like REPL completions can be
simplified.

Author: aviatesk

base/docs/Docs.jl

@@ -821,9 +821,8 @@ compiler-generated hidden symbols starting with `#`).
 See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.ispublic`](@ref).
 """
 function undocumented_names(mod::Module; private::Bool=false)
-    filter!(names(mod; all=true)) do sym
-        !hasdoc(mod, sym) && !startswith(string(sym), '#') &&
-            (private || Base.ispublic(mod, sym))
+    filter!(names(mod; non_public=true, deprecated=true)) do sym
+        !hasdoc(mod, sym) && (private || Base.ispublic(mod, sym))
     end
 end
 

base/reflection.jl

@@ -77,23 +77,35 @@ function fullname(m::Module)
 end
 
 """
-    names(x::Module; all::Bool=false, imported::Bool=false, usings::Bool=false) -> Vector{Symbol}
+    names(x::Module; non_public::Bool=false, imported::Bool=false,
+                     usings_explicit::Bool=false, usings_implicit::Bool=false,
+                     generated::Bool=false, deprecated::Bool=false,
+                     [usings::Bool=false], [all::Bool=false]) -> Vector{Symbol}
 
-Get a vector 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.
-If `usings` is true, then names explicitly imported via `using` are also included.
-Names are returned in sorted order.
+Return a vector of the sorted names of module `x`.
 
-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.
+By default, only public names defined within `x` are returned.
+
+By specifying the following keyword arguments, additional names can be included:
+- `non_public=true`: includes names defined within `x` that are not public.
+- `imported=true`: includes names explicitly imported from other modules via `import` statements.
+- `usings_explicit=true`: includes names explicitly imported from other modules via `using` statements.
+- `usings_implicit=true`: includes names implicitly imported from other modules via `using` statements
+  (i.e., names exported by modules that `x` has `using`-ed).
+- `generated=true`: includes names generated by the compiler frontend (specifically those starting with `#`).
+- `deprecated=true`: includes deprecated names.
+
+Additionally, the following keyword arguments can be used as aliases to conveniently specify these options:
+- `usings::Bool=true`: a shortcut to set both `usings_explicit` and `usings_implicit` to `true`.
+- `all::Bool=true`: a shortcut to set `non_public`, `generated`, and `deprecated` to `true`.
 
 !!! note
-    `sym ∈ names(SomeModule)` does *not* imply `isdefined(SomeModule, sym)`.
-    `names` may return symbols marked with `public` or `export`, even if
-    they are not defined in the module.
+    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.
+
+!!! note
+    `sym ∈ names(x)` does *not* imply `isdefined(x, sym)`.
+    `names` may return symbols that are only declared and not necessarily defined yet.
 
 !!! warning
     `names` may return duplicate names. The duplication happens, e.g. if an `import`ed name
@@ -102,8 +114,16 @@ since it is not idiomatic to explicitly mark names from `Main` as public.
 See also: [`Base.isexported`](@ref), [`Base.ispublic`](@ref), [`Base.@locals`](@ref), [`@__MODULE__`](@ref).
 """
 names(m::Module; kwargs...) = sort!(unsorted_names(m; kwargs...))
-unsorted_names(m::Module; all::Bool=false, imported::Bool=false, usings::Bool=false) =
-    ccall(:jl_module_names, Array{Symbol,1}, (Any, Cint, Cint, Cint), m, all, imported, usings)
+function unsorted_names(m::Module; non_public::Bool=false, imported::Bool=false,
+                                   usings_explicit::Bool=false, usings_implicit::Bool=false,
+                                   generated::Bool=false, deprecated::Bool=false,
+                                   usings::Bool=false, all::Bool=false)
+    usings && (usings_explicit = usings_implicit = true)
+    all && (non_public = generated = deprecated = true)
+    return ccall(:jl_module_names, Array{Symbol,1},
+        (Any, Cint, Cint, Cint, Cint, Cint, Cint),
+        m, non_public, imported, usings_explicit, usings_implicit, generated, deprecated)
+end
 
 """
     isexported(m::Module, s::Symbol) -> Bool

base/summarysize.jl

@@ -178,8 +178,8 @@ end
 function (ss::SummarySize)(obj::Module)
     haskey(ss.seen, obj) ? (return 0) : (ss.seen[obj] = true)
     size::Int = Core.sizeof(obj)
-    for binding in names(obj, all = true)
-        if isdefined(obj, binding) && !isdeprecated(obj, binding)
+    for binding in names(obj, non_public=true, generated=true)
+        if isdefined(obj, binding)
             value = getfield(obj, binding)
             if !isa(value, Module) || parentmodule(value) === obj
                 size += ss(value)::Int

src/module.c

@@ -1007,50 +1007,55 @@ void _append_symbol_to_bindings_array(jl_array_t* a, jl_sym_t *name) {
     jl_array_ptr_set(a, jl_array_dim0(a)-1, (jl_value_t*)name);
 }
 
-void append_module_names(jl_array_t* a, jl_module_t *m, int all, int imported, int usings)
+void append_module_names(jl_array_t* a, jl_module_t *m, int non_public, int imported, int usings_explicit, int generated, int deprecated)
 {
     jl_svec_t *table = jl_atomic_load_relaxed(&m->bindings);
     for (size_t i = 0; i < jl_svec_len(table); i++) {
         jl_binding_t *b = (jl_binding_t*)jl_svecref(table, i);
         if ((void*)b == jl_nothing)
             break;
         jl_sym_t *asname = b->globalref->name;
-        int hidden = jl_symbol_name(asname)[0]=='#';
+        int isgenerated = jl_symbol_name(asname)[0]=='#';
         int main_public = (m == jl_main_module && !(asname == jl_eval_sym || asname == jl_include_sym));
-        if (((b->publicp) ||
-             (imported && b->imported) ||
-             (usings && _binding_is_from_explicit_using(b)) ||
-             (jl_atomic_load_relaxed(&b->owner) == b && !b->imported && (all || main_public))) &&
-            (all || (!b->deprecated && !hidden)))
+        if (((jl_atomic_load_relaxed(&b->owner) == b) ? // check if this binding is owned by this module
+                // if it is owned by this module, check if the binding is public:
+                // one exception is bindings imported from other modules,
+                // which might also be owned by this module
+                (b->imported ? imported : (non_public || b->publicp || main_public)) :
+                // if this binding is external, then also include:
+                // - bindings imported from other modules, if `imported` is true
+                // - bindings usinged from other modules explicitly, if `usings_explicit` is true
+                ((imported && b->imported) || (usings_explicit && _binding_is_from_explicit_using(b)))) &&
+            ((generated || !isgenerated) && (deprecated || !b->deprecated))) {
             _append_symbol_to_bindings_array(a, asname);
+        }
     }
 }
 
-void append_exported_names(jl_array_t* a, jl_module_t *m, int all)
+void append_exported_names(jl_array_t* a, jl_module_t *m, int deprecated)
 {
     jl_svec_t *table = jl_atomic_load_relaxed(&m->bindings);
     for (size_t i = 0; i < jl_svec_len(table); i++) {
         jl_binding_t *b = (jl_binding_t*)jl_svecref(table, i);
         if ((void*)b == jl_nothing)
             break;
-        if (b->exportp && (all || !b->deprecated))
+        if (b->exportp && (deprecated || !b->deprecated))
             _append_symbol_to_bindings_array(a, b->globalref->name);
     }
 }
 
-JL_DLLEXPORT jl_value_t *jl_module_names(jl_module_t *m, int all, int imported, int usings)
+JL_DLLEXPORT jl_value_t *jl_module_names(jl_module_t *m, int non_public, int imported,
+                                         int usings_explicit, int usings_implicit,
+                                         int generated, int deprecated)
 {
     jl_array_t *a = jl_alloc_array_1d(jl_array_symbol_type, 0);
     JL_GC_PUSH1(&a);
-    append_module_names(a, m, all, imported, usings);
-    if (usings) {
+    append_module_names(a, m, non_public, imported, usings_explicit, generated, deprecated);
+    if (usings_implicit)
         // If `usings` is specified, traverse the list of `using`-ed modules and incorporate
         // the names exported by those modules into the list.
-        for(int i=(int)m->usings.len-1; i >= 0; --i) {
-            jl_module_t *usinged = module_usings_getidx(m, i);
-            append_exported_names(a, usinged, all);
-        }
-    }
+        for (int i = 0; i < m->usings.len; i++)
+            append_exported_names(a, module_usings_getidx(m, i), deprecated);
     JL_GC_POP();
     return (jl_value_t*)a;
 }

stdlib/InteractiveUtils/src/InteractiveUtils.jl

@@ -261,8 +261,8 @@ function _subtypes_in!(mods::Array, x::Type)
     while !isempty(mods)
         m = pop!(mods)
         xt = xt::DataType
-        for s in names(m, all = true)
-            if isdefined(m, s) && !isdeprecated(m, s)
+        for s in names(m, non_public=true)
+            if isdefined(m, s)
                 t = getfield(m, s)
                 dt = isa(t, UnionAll) ? unwrap_unionall(t) : t
                 if isa(dt, DataType)

stdlib/REPL/src/REPLCompletions.jl

@@ -138,7 +138,7 @@ end
 function append_filtered_mod_names!(ffunc::Function, suggestions::Vector{Completion},
                                     mod::Module, name::String, complete_internal_only::Bool)
     imported = usings = !complete_internal_only
-    ssyms = names(mod; all=true, imported, usings)
+    ssyms = names(mod; non_public=true, imported, usings)
     filter!(ffunc, ssyms)
     macros = filter(x -> startswith(String(x), "@" * name), ssyms)
     syms = String[sprint((io,s)->Base.show_sym(io, s; allow_macroname=true), s) for s in ssyms if completes_global(String(s), name)]
@@ -183,9 +183,7 @@ function complete_symbol!(suggestions::Vector{Completion},
         let modname = nameof(mod),
             is_main = mod===Main
             append_filtered_mod_names!(suggestions, mod, name, complete_internal_only) do s::Symbol
-                if Base.isdeprecated(mod, s)
-                    return false
-                elseif s === modname
+                if s === modname
                     return false # exclude `Main.Main.Main`, etc.
                 elseif complete_modules_only && !completes_module(mod, s)
                     return false
@@ -757,9 +755,9 @@ end
 MAX_ANY_METHOD_COMPLETIONS::Int = 10
 function recursive_explore_names!(seen::IdSet, callee_module::Module, initial_module::Module, exploredmodules::IdSet{Module}=IdSet{Module}())
     push!(exploredmodules, callee_module)
-    for name in names(callee_module; all=true, imported=true)
-        if !Base.isdeprecated(callee_module, name) && !startswith(string(name), '#') && isdefined(initial_module, name)
-            func = getfield(callee_module, name)
+    for name in names(callee_module; non_public=true, imported=true)
+        if isdefined(initial_module, name) # TODO use `usings=true` instead here?
+            func = getglobal(initial_module, name)
             if !isa(func, Module)
                 funct = Core.Typeof(func)
                 push!(seen, funct)

stdlib/REPL/src/docview.jl

@@ -873,11 +873,9 @@ print_correction(word, mod::Module) = print_correction(stdout, word, mod)
 moduleusings(mod) = ccall(:jl_module_usings, Any, (Any,), mod)
 
 function accessible(mod::Module)
-    bindings = Set(AccessibleBinding(s) for s in names(mod; all=true, imported=true)
-                   if !isdeprecated(mod, s))
+    bindings = Set(AccessibleBinding(s) for s in names(mod; non_public=true, imported=true))
     for used in moduleusings(mod)
-        union!(bindings, (AccessibleBinding(used, s) for s in names(used)
-                          if !isdeprecated(used, s)))
+        union!(bindings, (AccessibleBinding(used, s) for s in names(used)))
     end
     union!(bindings, (AccessibleBinding(k) for k in keys(Base.Docs.keywords)))
     filter!(b -> !occursin('#', b.name), bindings)

stdlib/Test/src/Test.jl

@@ -2076,8 +2076,7 @@ function detect_ambiguities(mods::Module...;
     filter!(mod -> mod === parentmodule(mod), work) # some items in loaded_modules_array are not top modules (really just Base)
     while !isempty(work)
         mod = pop!(work)
-        for n in names(mod, all = true)
-            Base.isdeprecated(mod, n) && continue
+        for n in names(mod, non_public=true, generated=true)
             if !isdefined(mod, n)
                 if is_in_mods(mod, recursive, mods)
                     if allowed_undefineds === nothing || GlobalRef(mod, n) ∉ allowed_undefineds
@@ -2147,8 +2146,7 @@ function detect_unbound_args(mods...;
     filter!(mod -> mod === parentmodule(mod), work) # some items in loaded_modules_array are not top modules (really just Base)
     while !isempty(work)
         mod = pop!(work)
-        for n in names(mod, all = true)
-            Base.isdeprecated(mod, n) && continue
+        for n in names(mod, non_public=true, generated=true)
             if !isdefined(mod, n)
                 if is_in_mods(mod, recursive, mods)
                     if allowed_undefineds === nothing || GlobalRef(mod, n) ∉ allowed_undefineds

test/reflection.jl

@@ -177,7 +177,7 @@ let
     @test Base.binding_module(TestMod7648, :d7648) == TestMod7648
     @test Base.binding_module(TestMod7648, :a9475) == TestMod7648.TestModSub9475
     @test Base.binding_module(TestMod7648.TestModSub9475, :b9475) == TestMod7648.TestModSub9475
-    defaultset = Set(Symbol[:Foo7648, :TestMod7648, :a9475, :c7648, :f9475, :foo7648, :foo7648_nomethods])
+    defaultset = Set(Symbol[:Foo7648, :TestMod7648, :c7648, :foo7648, :foo7648_nomethods])
     allset = defaultset ∪ Set(Symbol[
         Symbol("#eval"), Symbol("#foo7648"), Symbol("#foo7648_nomethods"), Symbol("#include"),
         :TestModSub9475, :d7648, :eval, :f7648, :include])
@@ -189,7 +189,7 @@ let
         :GenericSet, :GenericString, :LogRecord, :Test, :TestLogger, :TestSetException,
         :detect_ambiguities, :detect_unbound_args])
     usings_from_Base = delete!(Set(names(Module(); usings=true)), :anonymous) # the name of the anonymous module itself
-    usings = Set(Symbol[:x36529, :TestModSub9475, :f54609]) ∪ usings_from_Test ∪ usings_from_Base
+    usings = Set(Symbol[:x36529, :TestModSub9475, :a9475, :f9475, :f54609]) ∪ usings_from_Test ∪ usings_from_Base
     @test Set(names(TestMod7648)) == defaultset
     @test Set(names(TestMod7648, all=true)) == allset
     @test Set(names(TestMod7648, all=true, imported=true)) == allset ∪ imported
@@ -209,8 +209,16 @@ global unexported::Int = 0
 end
 using Base: @assume_effects
 using .Inner
-end
-let usings = names(Test54609Simple; usings=true)
+end # baremodule Test54609Simple
+let usings_explicit = names(Test54609Simple; usings_explicit=true)
+    @test Symbol("@assume_effects") ∈ usings_explicit
+    @test :exported ∉ usings_explicit
+    @test :unexported ∉ usings_explicit
+    usings_implicit = names(Test54609Simple; usings_implicit=true)
+    @test Symbol("@assume_effects") ∉ usings_implicit
+    @test :exported ∈ usings_implicit
+    @test :unexported ∉ usings_implicit
+    usings = names(Test54609Simple; usings=true)
     @test Symbol("@assume_effects") ∈ usings
     @test :Base ∉ usings
     @test :exported ∈ usings
@@ -230,7 +238,7 @@ let usings = names(Test54609Complex; usings=true)
     @test :exported_new ∈ usings
     @test :exported_old ∉ usings
     @test :_Test54609Complex ∈ usings # should include the `using`ed module itself
-    usings_all = names(Test54609Complex; usings=true, all=true)
+    usings_all = names(Test54609Complex; usings=true, deprecated=true)
     @test :exported_new ∈ usings_all
     @test :exported_old ∈ usings_all # deprecated names should be included with `all=true`
 end