\HeaderA{edit}{Invoke a Text Editor}{edit}
\methaliasA{edit.default}{edit}{edit.default}
\aliasA{emacs}{edit}{emacs}
\aliasA{pico}{edit}{pico}
\aliasA{vi}{edit}{vi}
\aliasA{xedit}{edit}{xedit}
\aliasA{xemacs}{edit}{xemacs}
\keyword{utilities}{edit}
\begin{Description}\relax
Invoke a text editor on an \R{} object.
\end{Description}
\begin{Usage}
\begin{verbatim}
## Default S3 method:
edit(name = NULL, file = "", title = NULL,
     editor = getOption("editor"), ...)

vi(name = NULL, file = "")
emacs(name = NULL, file = "")
pico(name = NULL, file = "")
xemacs(name = NULL, file = "")
xedit(name = NULL, file = "")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{name}] a named object that you want to edit. If name is missing
then the file specified by \code{file} is opened for editing.
\item[\code{file}] a string naming the file to write the edited version to.
\item[\code{title}] a display name for the object being edited.
\item[\code{editor}] a string naming the text editor you want to use.  On
Unix the default is set from the environment variables \env{EDITOR}
or \env{VISUAL} if either is set, otherwise \code{vi} is used.  On
Windows it defaults to \code{notepad}.
\item[\code{...}] further arguments to be passed to or from methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{edit} invokes the text editor specified by \code{editor} with
the object \code{name} to be edited.  It is a generic function,
currently with a default method and one for data frames and matrices.

\code{data.entry} can be used to edit data, and is used by \code{edit}
to edit matrices and data frames on systems for which
\code{data.entry} is available.

It is important to realize that \code{edit} does not change the object
called \code{name}. Instead, a copy of name is made and it is that copy
which is changed. Should you want the changes to apply to the object
\code{name} you must assign the result of \code{edit} to
\code{name}. (Try \code{\LinkA{fix}{fix}} if you want to make permanent
changes to an object.)

In the form \code{edit(name)},
\code{edit} deparses \code{name} into a temporary file and invokes the
editor \code{editor} on this file. Quitting from the editor causes
\code{file} to be parsed and that value returned.
Should an error occur in parsing, possibly due to incorrect syntax, no
value is returned. Calling \code{edit()}, with no arguments, will
result in the temporary file being reopened for further editing.

Currently only the internal editor in Windows makes use of the 
\code{title} option; it displays the given name in the window 
header.
\end{Details}
\begin{Note}\relax
The functions \code{vi}, \code{emacs}, \code{pico}, \code{xemacs},
\code{xedit} rely on the corresponding editor being available and
being on the path. This is system-dependent.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{edit.data.frame}{edit.data.frame}},
\code{\LinkA{data.entry}{data.entry}},
\code{\LinkA{fix}{fix}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
# use xedit on the function mean and assign the changes
mean <- edit(mean, editor = "xedit")

# use vi on mean and write the result to file mean.out
vi(mean, file = "mean.out")
## End(Not run)
\end{ExampleCode}
\end{Examples}

