Denotes an R {@code environment}. Abstractly, environments consist of a frame (collection of named objects), and a pointer to an enclosing environment. R environments can be named or unnamed. {@code base} is an example of a named environment.Environments associated with function invocations are unnamed. The {@code environmentName}builtin returns "" for an unnamed environment. However, unnamed environments print using a unique numeric id in the place where the name would appear for a named environment. This is finessed using the {@link #getPrintNameHelper} method. Further, environments on the {@code search} pathreturn a yet different name in the result of {@code search}, e.g. ".GlobalEnv", "package:base", which is handled via {@link #getSearchName()}. Finally, environments can be given names using the {@code attr} function, and (then) they print differently again. Of the default set ofenvironments, only "Autoloads" has a {@code name} attribute.
Environments can also be locked preventing any bindings from being added or removed. N.B. the empty environment can't be assigned to but is not locked (see GnuR). Further, individual bindings within an environment can be locked, although they can be removed unless the environment is also locked.
Environments are used for many different things in R, including something close to a {@link java.util.Map} created in R code using the {@code new.env} function. This is the only casewhere the {@code size} parameter is specified. All the other instances of environments areimplicitly created by the virtual machine, for example, on function call.
The different kinds of environments are implemented as subclasses. The variation in behavior regarding access to the "frame" is handled by delegation to an instance of {@link REnvFrameAccess}. Conceptually, variables are searched for by starting in a given environment and searching backwards through the "parent" chain. In practice, variables are accessed in the Truffle environment using {@link Frame} instances which may, in some cases suchas compiled code, not even exist as actual objects. Therefore, we have to keep the name lookup in the two worlds in sync. This is an issue during initialization, and when a new environment is attached, cf. {@link #attach}.
Packages have three associated environments, "package:xxx", "imports:xxx" and "namespace:xxx", for package "xxx". The {@code base} package is a special case in that it does not have an"imports" environment. The parent of "package:base" is the empty environment, but the parent of "namespace:base" is the global environment. Whereas R types generally use value semantics environments do not; they have reference semantics. In particular in FastR, there is at exactly one environment created for any package frame and at most one for a function frame, allowing equality to be tested using {@code ==}. TODO retire the {@code Package}, {@code Namespace} and {@code Imports} classes as they are onlyused by the builtin packages, and will be completely redundant when they are loaded from serialized package meta-data as will happen in due course.