Scope introspection builtins

[xiaq]

It would be nice if we have a pair of builtins for examining (lexical) scopes.

Scopes have two parts: a names part, storing variable names, and a uses part, storing other namespaces used in that scope:

elvish/eval/scope.go

Lines 3 to 7 in 2d837f1

	// Scope represents a lexical scope. It holds variables and imports.
	type Scope struct {
	Names Namespace
	Uses map[string]Namespace
	}

Hence it makes sense to have two builtin functions for examining these two parts. One list-names and one list-uses.

list-names takes an optional namespace name and lists all names in that namespace. For instance, list-names builtin lists all names in the builtin namespace, and list-names local lists all names in the local namespace. When no namespace or "" is given, it should list all names in the local, up and builtin namespaces, akin to how variable name resolution works

elvish/eval/eval.go

Lines 368 to 404 in 2d837f1

	// ResolveVar resolves a variable. When the variable cannot be found, nil is
	// returned.
	func (ec *EvalCtx) ResolveVar(ns, name string) Variable {
	switch ns {
	case "local":
	return ec.local.Names[name]
	case "up":
	return ec.up.Names[name]
	case "builtin":
	return ec.Builtin.Names[name]
	case "":
	if v := ec.local.Names[name]; v != nil {
	return v
	}
	if v, ok := ec.up.Names[name]; ok {
	return v
	}
	return ec.Builtin.Names[name]
	case "e":
	if strings.HasPrefix(name, FnPrefix) {
	return NewRoVariable(ExternalCmd{name[len(FnPrefix):]})
	}
	case "E":
	return envVariable{name}
	case "shared":
	if ec.Daemon == nil {
	throw(ErrStoreUnconnected)
	}
	return sharedVariable{ec.Daemon, name}
	default:
	ns := ec.ResolveMod(ns)
	if ns != nil {
	return ns[name]
	}
	}
	return nil
	}

In short, "list-names ns" should list all such names n that $ns:n is a valid variable.

list-uses does not take arguments, and always lists names of namespaces used in the local, up, or builtin scope. This is to mirror the behavior of namespace resolution, which always happens as described:

elvish/eval/eval.go

Lines 406 to 417 in 2d837f1

	func (ec *EvalCtx) ResolveMod(name string) Namespace {
	if ns, ok := ec.local.Uses[name]; ok {
	return ns
	}
	if ns, ok := ec.up.Uses[name]; ok {
	return ns
	}
	if ns, ok := ec.Builtin.Uses[name]; ok {
	return ns
	}
	return nil
	}

[krader1961]

Let's say you have namespaces a: and a:b: (from doing use a and use a:b). How would I use these commands to list just the namespaces nested within a:? Or is that a nonsensical question? It looks like command completions provide reasonable suggestions when I type a: including showing the nested a:b: namespace. Isn't that something we should be able to replicate using elvish script?

[xiaq]

@krader1961 There is no "nested namespace". The module a:b: happens to have a: as its prefix in name. (The situation is comparable to Perl's modules, if you are familiar with that). The fact that completion for a: includes a:b: is based on prefix matching, just like if you have variables $a-b and $a, typing $a will include $a-b as a candidate.

[krader1961]

Yeah, I see that now that I've read the docs more carefully after my previous question. The problem is that most people are going to look at namespaces a: and a:b: and conclude the latter is somehow nested inside the former. A careful reading of the rules for evaluating use statements makes the relationship clearer. But I suspect it will be a FAQ since nearly every new user will make the mistake I made. Which doesn't argue for changing the namespace model but does mean additional documentation, especially examples, is going to be needed.

[xiaq]

A different API has been implemented: namespaces can now be indexed like maps, and has-key and keys work on namespaces.

[zzamboni]

In my tests, keys works fine on namespaces, but has-key does not:

> kind-of $edit:
▶ ns
> keys $edit:
▶ move-dot-eol~
▶ rprompt-persistent
▶ match-prefix~
▶ complex-candidate~
▶ selected-file
...
> has-key $edit: after-readline
Exception: couldn't get key or index of type 'ns'