\HeaderA{ls.str}{List Objects and their Structure}{ls.str}
\aliasA{lsf.str}{ls.str}{lsf.str}
\aliasA{print.ls\_str}{ls.str}{print.ls.Rul.str}
\keyword{print}{ls.str}
\keyword{utilities}{ls.str}
\begin{Description}\relax
\code{ls.str} and \code{lsf.str} are variations of \code{\LinkA{ls}{ls}}
applying \code{\LinkA{str}{str}()} to each matched name: see section Value.
\end{Description}
\begin{Usage}
\begin{verbatim}
ls.str(pos = -1, name, envir, all.names = FALSE,
       pattern, mode = "any")

lsf.str(pos = -1, envir, ...)

## S3 method for class 'ls_str':
print(x, max.level = 1, give.attr = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{pos}] integer indicating \code{\LinkA{search}{search}} path position.
\item[\code{name}] optional name indicating \code{\LinkA{search}{search}} path
position, see \code{\LinkA{ls}{ls}}.
\item[\code{envir}] environment to use, see \code{\LinkA{ls}{ls}}.
\item[\code{all.names}] logical indicating if names which begin with a
\code{.} are omitted; see \code{\LinkA{ls}{ls}}.
\item[\code{pattern}] a \LinkA{regular expression}{regular expression} passed to \code{\LinkA{ls}{ls}}.
Only names matching \code{pattern} are considered.
\item[\code{max.level}] maximal level of nesting which is applied for
displaying nested structures, e.g., a list containing sub lists.
Default 0: Display all nesting levels.
\item[\code{give.attr}] logical; if \code{TRUE} (default), show attributes
as sub structures.
\item[\code{mode}] character specifying the \code{\LinkA{mode}{mode}} of objects to
consider.  Passed to \code{\LinkA{exists}{exists}} and \code{\LinkA{get}{get}}.
\item[\code{x}] an object of class \code{"ls\_str"}.
\item[\code{...}] further arguments to pass.  and \code{lsf.str} passes
them to \code{ls.str} which passes them on to \code{\LinkA{ls}{ls}}.
The (non-exported) print method \code{print.ls\_str} passes them to
\code{\LinkA{str}{str}}.
\end{ldescription}
\end{Arguments}
\begin{Value}
\code{ls.str} and \code{lsf.str} return an object of class
\code{"ls\_str"}, basically the character vector of matching names
(functions only for \code{lsf.str}), similarly to
\code{\LinkA{ls}{ls}}, with a \code{print()} method that calls \code{\LinkA{str}{str}()}
on each object.
\end{Value}
\begin{Author}\relax
Martin Maechler
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{str}{str}}, \code{\LinkA{summary}{summary}}, \code{\LinkA{args}{args}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)

lsf.str()#- how do the functions look like which I am using?
ls.str(mode = "list") #- what are the structured objects I have defined?

## create a few objects
example(glm, echo = FALSE)
ll <- as.list(LETTERS)
print(ls.str(), max.level = 0)# don't show details

## which base functions have "file" in their name ?
lsf.str(pos = length(search()), pattern = "file")

## demonstrating that  ls.str() works inside functions
## ["browser/debug mode"]:
tt <- function(x, y=1) { aa <- 7; r <- x + y; ls.str() }
(nms <- sapply(strsplit(capture.output(tt(2))," *: *"), `[`, 1))
stopifnot(nms == c("aa", "r","x","y"))
\end{ExampleCode}
\end{Examples}

