1% File src/library/utils/man/edit.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{edit}
7\alias{edit}
8\alias{edit.default}
9\alias{vi}
10\alias{emacs}
11\alias{pico}
12\alias{xemacs}
13\alias{xedit}
14\title{Invoke a Text Editor}
15\description{
16  Invoke a text editor on an \R object.
17}
18\usage{
19\method{edit}{default}(name = NULL, file = "", title = NULL,
20     editor = getOption("editor"), \dots)
21
22vi(name = NULL, file = "")
23emacs(name = NULL, file = "")
24pico(name = NULL, file = "")
25xemacs(name = NULL, file = "")
26xedit(name = NULL, file = "")
27}
28\arguments{
29  \item{name}{a named object that you want to edit. If name is missing
30    then the file specified by \code{file} is opened for editing.}
31  \item{file}{a string naming the file to write the edited version to.}
32  \item{title}{a display name for the object being edited.}
33  \item{editor}{usually a character string naming (or giving the path
34    to) the text editor you want to use.  On Unix the default is set from
35    the environment variables \env{EDITOR} or \env{VISUAL} if either is
36    set, otherwise \code{vi} is used.  On Windows it defaults to
37    \code{"internal"}, the script editor.  On the macOS GUI the argument
38    is ignored and the document editor is always used.
39
40    \code{editor} can also be an \R function, in which case it is called
41    with the arguments \code{name}, \code{file}, and \code{title}.  Note
42    that such a function will need to independently implement all
43    desired functionality.
44  }
45  \item{\dots}{further arguments to be passed to or from methods.}
46}
47\details{
48  \code{edit} invokes the text editor specified by \code{editor} with
49  the object \code{name} to be edited.  It is a generic function,
50  currently with a default method and one for data frames and matrices.
51
52  \code{data.entry} can be used to edit data, and is used by \code{edit}
53  to edit matrices and data frames on systems for which
54  \code{data.entry} is available.
55
56  It is important to realize that \code{edit} does not change the object
57  called \code{name}. Instead, a copy of name is made and it is that
58  copy which is changed.  Should you want the changes to apply to the
59  object \code{name} you must assign the result of \code{edit} to
60  \code{name}.  (Try \code{\link{fix}} if you want to make permanent
61  changes to an object.)
62
63  In the form \code{edit(name)},
64  \code{edit} deparses \code{name} into a temporary file and invokes the
65  editor \code{editor} on this file. Quitting from the editor causes
66  \code{file} to be parsed and that value returned.
67  Should an error occur in parsing, possibly due to incorrect syntax, no
68  value is returned. Calling \code{edit()}, with no arguments, will
69  result in the temporary file being reopened for further editing.
70
71  Note that deparsing is not perfect, and the object recreated after
72  editing can differ in subtle ways from that deparsed: see
73  \code{\link{dput}} and \code{\link{.deparseOpts}}. (The deparse options
74  used are the same as the defaults for \code{dump}.)  Editing a
75  function will preserve its environment.  See
76  \code{\link{edit.data.frame}} for further changes that can occur when
77  editing a data frame or matrix.
78
79  Currently only the internal editor in Windows makes use of the
80  \code{title} option; it displays the given name in the window
81  header.
82}
83\seealso{
84  \code{\link{edit.data.frame}},
85  \code{\link{data.entry}},
86  \code{\link{fix}}.
87}
88\note{
89  The functions \code{vi}, \code{emacs}, \code{pico}, \code{xemacs},
90  \code{xedit} rely on the corresponding editor being available and
91  being on the path. This is system-dependent.
92}
93\examples{
94\dontrun{
95# use xedit on the function mean and assign the changes
96mean <- edit(mean, editor = "xedit")
97
98# use vi on mean and write the result to file mean.out
99vi(mean, file = "mean.out")
100}
101}
102\keyword{utilities}
103