The R Project SVN R

% File src/library/tools/man/Rdiff.Rd

% Part of the R package, https://www.R-project.org

% Copyright 2010-2024 R Core Team

% Distributed under GPL 2 or later

\name{Rdiff}

\alias{Rdiff}

\title{Difference R Output Files}

\description{

  Given two \R output files, compute differences ignoring headers,

  footers and some other differences.

}

\usage{

Rdiff(from, to, useDiff = FALSE, forEx = FALSE,

      nullPointers = TRUE, Log = FALSE)

}

\arguments{

  \item{from, to}{filepaths to be compared}

  \item{useDiff}{should \command{diff} be used to compare results?

    Overridden to false if the command is not available.}

  \item{forEx}{logical: extra pruning for \file{-Ex.Rout} files to

    exclude headers and footers of examples, code and results for

    \option{"--timings"}, etc.}

  \item{nullPointers}{logical: should the displayed addresses of

    pointers be set to \code{0x00000000} before comparison?}

  \item{Log}{logical: should the returned value include a log of

    differences found?}

}

\details{

  The \R startup banner and any timing information from \command{R CMD

    BATCH} are removed from both files, together with lines about

  loading packages.  UTF-8 fancy quotes (see \code{\link{sQuote}}) and

  on Windows, Windows' so-called \sQuote{smart quotes}, are mapped to

  a simple quote.  Addresses of environments, compiled bytecode and

  other exotic types expressed as hex addresses

  (e.g., \samp{<environment: 0x12345678>}) are mapped to

  \code{0x00000000}.  The files are then compared line-by-line.  If

  there are the same number of lines and \code{useDiff} is false, a

  simple \command{diff -b} -like display of differences is printed

  (which ignores trailing spaces and differences in numbers of

  consecutive spaces), otherwise \command{diff -bw} is called on the

  edited files.  (This tries to ignore all differences in whitespace:

  note that flag \option{-w} is not required by POSIX but is supported

  by GNU, Solaris and FreeBSD versions -- macOS uses an old GNU version.)

  %% Unreliable with 2022-07 gsub changes.

  %% This can compare uncompressed PDF files, ignoring differences in

  %% creation and modification dates.  However, non-ASCII text may not be

  %% handled in UTF-8 locales, and it does not check if the PDF files really

  %% are uncompressed.  Using \code{useDiff = TRUE} is likely to be more

  %% successful if a \command{diff} command is available.

  There is limited support for comparing PDF files produced by

  \code{pdf(compress = FALSE)}, mainly for use in \command{make check}

  -- this requires a \command{diff} command and \code{useDiff = TRUE}.

  Mainly for use in examples and tests, text from marker

  \samp{> ## IGNORE_RDIFF_BEGIN} up to (but not including)

  \samp{> ## IGNORE_RDIFF_END} is ignored.

  In examples, since \R 4.4.0, the built-in Rd macro \verb{\dontdiff\{\}}

  can be used instead.

}

\value{

  If \code{Log} is true, a list with components \code{status} (see

  below) and \code{out}, a character vector of descriptions of

  differences, possibly of zero length.

  Otherwise, a status indicator (invisibly), \code{0L} if and only if no

  differences were found.

}

\seealso{

  The shell script run as \command{R CMD Rdiff}, which uses

  \code{useDiff = TRUE}.

}

\keyword{utilities}