The R Project SVN R

% File src/library/utils/man/Rscript.Rd

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

% Copyright 1995-2022 R Core Team

% Distributed under GPL 2 or later

\name{Rscript}

\alias{Rscript}

\title{Scripting Front-End for R}

\description{

  This is an alternative front end for use in \samp{#!} scripts and

  other scripting applications.

}

\usage{

\special{Rscript [options] file [args]}

\special{Rscript [options] -e expr [-e expr2 ...] [args]}

}

\arguments{

  \item{options}{a list of options, all beginning with \samp{--}.  These

    can be any of the options of the standard \R front-end, and also those

    described in the details.}

  \item{expr, expr2}{\R expression(s), properly quoted.}

  \item{file}{the name of a file containing \R commands.  \samp{-}

    indicates \file{stdin}.}

  \item{args}{arguments to be passed to the script in \code{file} or

    expressions supplied via \option{-e}.}

}

\details{

  \command{Rscript --help} gives details of usage, and

  \command{Rscript --version} gives the version of \command{Rscript}.

  Other invocations invoke the \R front-end with selected options.  This

  front-end is convenient for writing \samp{#!} scripts since it is an

  executable and takes \code{file} directly as an argument.  Options

  \option{--no-echo --no-restore} are always supplied: these imply

  \option{--no-save}. Arguments that contain spaces cannot be specified

  directly on the \samp{#!} line, because spaces and tabs are interpreted as

  delimiters and there is no way to protect them from this interpretation on

  the \samp{#!} line. (The standard Windows command line has no concept

  of \samp{#!} scripts, but \I{Cygwin} shells do.)

  \emph{Either} one or more \option{-e} options or \code{file} should

  be supplied.  When using \option{-e} options be aware of the quoting

  rules in the shell used: see the examples.

  The prescribed order of arguments is important: e.g.  \option{--verbose}

  specified after \option{-e} will be part of \code{args} and passed to the

  expression; the same will happen to \option{-e} specified after

  \code{file}.

  Additional options accepted as part of \code{options} (before \code{file}

  or \option{-e}) are

  \describe{

    \item{\option{--verbose}}{gives details of what \command{Rscript} is

      doing.}

    \item{\option{--default-packages=list}}{where \code{list} is a

      comma-separated list of package names or \code{NULL}.  Sets the

      environment variable \env{R_DEFAULT_PACKAGES} which determines the

      packages loaded on startup.

    }

  }

  Spaces are allowed in \code{expr} and \code{file} (but will need

  to be protected from the shell in use, if any, for example by

  enclosing the argument in quotes).

  If \option{--default-packages} is not used, then \command{Rscript}

  checks the environment variable \env{R_SCRIPT_DEFAULT_PACKAGES}. If

  this is set, then it takes precedence over \env{R_DEFAULT_PACKAGES}.

#ifdef unix

  Normally the version of \R is determined at installation, but this can

  be overridden by setting the environment variable \env{RHOME}.

#endif

#ifdef windows

  The \R files are found from the location of the \file{Rscript.exe}

  executable.   If this is copied elsewhere, the environment variable

  \env{RHOME} should be set to the top directory of the \R installation.

  Unlike Unix-alikes, this links directly to \file{R.dll} rather than

  running a separate process.

#endif

  \code{\link{stdin}()} refers to the input file, and

  \code{\link{file}("stdin")} to the \code{stdin} file stream of the

  process.

}

#ifdef unix

\note{

  \command{Rscript} is only supported on systems with the \code{execv}

  system call.

}

#endif

\examples{\dontrun{

#ifdef unix

Rscript -e 'date()' -e 'format(Sys.time(), "\%a \%b \%d \%X \%Y")'

#endif

#ifdef windows

# Note that Rscript is not by default in the PATH on Windows, so

# either put it there or use an explicit path to Rscript.

# at the standard Windows command line

Rscript -e "date()" -e "format(Sys.time(), \\"\%a \%b \%d \%X \%Y\\")"

# in other shells, e.g. bash or tcsh, prefer

Rscript -e 'date()' -e 'format(Sys.time(), "\%a \%b \%d \%X \%Y")'

#endif

# Get the same initial packages in the same order as default R:

Rscript --default-packages=methods,datasets,utils,grDevices,graphics,stats -e 'sessionInfo()'

## example #! script for a Unix-alike

## (arguments given on the #! line end up as [options] to Rscript, while

## arguments passed to the #! script end up as [args], so available to

## commandArgs())

#! /path/to/Rscript --vanilla --default-packages=utils

args <- commandArgs(TRUE)

res <- try(install.packages(args))

if(inherits(res, "try-error")) q(status=1) else q()

}}

\keyword{utilities}