\HeaderA{ls}{List Objects}{ls}
\aliasA{objects}{ls}{objects}
\keyword{environment}{ls}
\begin{Description}\relax
\code{ls} and \code{objects} return a vector of character strings
giving the names of the objects in the specified environment.
When invoked with no argument at the top level prompt,
\code{ls} shows what data sets and functions a user has defined.
When invoked with no argument inside a function,
\code{ls} returns the names of the functions local variables.
This is useful in conjunction with \code{browser}.
\end{Description}
\begin{Usage}
\begin{verbatim}
ls(name, pos = -1, envir = as.environment(pos),
   all.names = FALSE, pattern)
objects(name, pos= -1, envir = as.environment(pos),
        all.names = FALSE, pattern)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{name}] which environment to use in listing the available objects.
Defaults to the \emph{current}
environment.  Although called \code{name} for back compatibility, in
fact this argument can specify the environment in any form; see the
details section.
\item[\code{pos}] an alternative argument to \code{name} for specifying the
environment as a position in the search list.  Mostly there for
back compatibility.
\item[\code{envir}] an alternative argument to \code{name} for specifying the
environment evaluation environment. Mostly there for back compatibility.
\item[\code{all.names}] a logical value.  If \code{TRUE}, all
object names are returned.  If \code{FALSE}, names which begin with a
\samp{.} are omitted.
\item[\code{pattern}] an optional \LinkA{regular expression}{regular expression}.  Only names
matching \code{pattern} are returned.  \code{\LinkA{glob2rx}{glob2rx}} can be
used to convert wildcard patterns to regular expressions.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{name} argument can specify the  environment from which
object names are taken in one of several forms:
as an integer (the position in the \code{\LinkA{search}{search}} list); as
the character string name of an element in the search list; or as an
explicit \code{\LinkA{environment}{environment}} (including using
\code{\LinkA{sys.frame}{sys.frame}} to access the currently active function calls).
By default, the environment of the call to \code{ls} or \code{objects}
is used. The \code{pos} and \code{envir} arguments are an alternative
way to specify an environment, but are primarily there for back
compatibility.

Note that the \emph{order} of the resulting strings is locale
dependent, see \code{\LinkA{Sys.getlocale}{Sys.getlocale}}.
\end{Details}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{glob2rx}{glob2rx}} for converting wildcard patterns to regular
expressions.

\code{\LinkA{ls.str}{ls.str}} for a long listing based on \code{\LinkA{str}{str}}.
\code{\LinkA{apropos}{apropos}} (or \code{\LinkA{find}{find}})
for finding objects in the whole search path;
\code{\LinkA{grep}{grep}} for more details on \sQuote{regular expressions};
\code{\LinkA{class}{class}},
\code{\LinkA{methods}{methods}}, etc., for
object-oriented programming.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
.Ob <- 1
ls(pattern = "O")
ls(pattern= " O", all.names = TRUE)    # also shows ".[foo]"

# shows an empty list because inside myfunc no variables are defined
myfunc <- function() {ls()}
myfunc()

# define a local variable inside myfunc
myfunc <- function() {y <- 1; ls()}
myfunc()                # shows "y"
\end{ExampleCode}
\end{Examples}

