% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edit_file.R
\name{file_edit}
\alias{file_edit}
\title{Edit a text file programmatically}
\usage{
file_edit(file, txt, match, append = TRUE)
}
\arguments{
\item{file}{chr, path to a file}

\item{txt}{chr or chr fun, either a single character string to insert into
the file or a function that transforms a character string. If supplying a
function, the first argument of the function must accept a single string
and it must return a single string. The function will be applied
independently to each line in the file that matches the match argument.
Supports anonymous functions. See examples.}

\item{match}{num vector or lgl fun, either a numeric vector indicating line
indices in the file or a function that returns a logical indicating lines
to change. If supplying a function, the first argument of the function must
accept a single string and it must return a logical vector. The function
will be applied independently to each line in the file. Supports anonymous
functions. See examples.}

\item{append}{lgl, if TRUE the text will be added as a new line after the
line(s) specified in the match argument. If FALSE, then the text will
replace the lines specified in the match argument}
}
\value{
(invisibly) FALSE if no lines in the specified file match the match
argument and TRUE otherwise
}
\description{
Insert or transform (\code{txt} argument) one or more lines in a file specified
either by line number or a boolean function (\code{match} argument). Any file that
can be read with the \code{readLines()} function should be compatible.
}
\examples{
tmpfile <- tempfile()

writeLines(text =
             c("hello I am joe",
               "this is multiple lines of text",
               "12345",
               "",
               "^ line 4 is an empty line"),
           con = tmpfile)
cat(readLines(tmpfile),sep = "\n")

# The simplest use is to append a line in a file with new text. Note that txt
# must be a single character string.
file_edit(file = tmpfile,
          txt = "this line is appended after the second line",
          match = 2,
          append = TRUE)
cat(readLines(tmpfile),sep = "\n")

# We can instead replace a line using append = FALSE. Here, we replace the empty
# line in the file. After adding the line above, the empty line now occupies
# index 5.
file_edit(file = tmpfile,
          txt = "this line is no longer empty",
          match = 5,
          append = FALSE)
cat(readLines(tmpfile),sep = "\n")

# The txt argument can also be a function, anonymous or named. It just needs to
# accept a single string and return a single string. Here, we replace "is" with
# "was" in line 6.
file_edit(file = tmpfile,
          txt = ~ stringr::str_replace(.x, "is", "was"),
          match = 6,
          append = FALSE)
cat(readLines(tmpfile),sep = "\n")

# The match argument can also be a  function. It just needs to accept a single
# string and return a single boolean. You can use it with the txt argument
# for some interesting interactions. Here, we change every line containing
# the word "is" to uppercase
file_edit(file = tmpfile,
          txt = toupper,
          match = ~ stringr::str_detect(.x, " is "),
          append = FALSE)
cat(readLines(tmpfile),sep = "\n")

# strings containing carriage returns are preserved. Here, we use the readLines
# and length functions to ensure we append the string to the end of the file
multiline <-
"
Here is a string
that takes up multiple lines"

file_edit(file = tmpfile,
          txt = multiline,
          match = length(readLines(tmpfile)),
          append = TRUE)
cat(readLines(tmpfile),sep = "\n")

}
