\HeaderA{ns-topenv}{Top Level Environment}{ns.Rdash.topenv}
\aliasA{topenv}{ns-topenv}{topenv}
\keyword{programming}{ns-topenv}
\begin{Description}\relax
Finding the top level environment.
\end{Description}
\begin{Usage}
\begin{verbatim}
topenv(envir = parent.frame(),
       matchThisEnv = getOption("topLevelEnvironment"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{envir}] environment.
\item[\code{matchThisEnv}] return this environment, if it matches before
any other criterion is satisfied.  The default, the option
\dQuote{topLevelEnvironment}, is set by \code{\LinkA{sys.source}{sys.source}},
which treats a specific environment as the top level environment.
Supplying the argument as \code{NULL} means it will never match.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{topenv} returns the first top level environment found when
searching \code{envir} and its parent environments.  An environment is
considered top level if it is the internal environment of a name space,
a package environment in the search path, or \code{.GlobalEnv}.
\end{Details}
\begin{Examples}
\begin{ExampleCode}
topenv(.GlobalEnv)
topenv(new.env())
\end{ExampleCode}
\end{Examples}

