Scripts and the Command Line

Rscript --help
#> Usage: Rscript [options] file [args]
#>    or: Rscript [options] -e expr [-e expr2 ...] [args]
#> A binary front-end to R, for use in scripting applications.
#>
#> Options:
#>   --help              Print usage and exit
#>   --version           Print version and exit
#>   --verbose           Print information on progress
#>   --default-packages=LIST  Attach these packages on startup;
#>                         a comma-separated LIST of package names, or 'NULL'
#> and options to R (in addition to --no-echo --no-restore), for example:
#>   --save              Do save workspace at the end of the session
#>   --no-environ        Don't read the site and user environment files
#>   --no-site-file      Don't read the site-wide Rprofile
#>   --no-init-file      Don't read the user R profile
#>   --restore           Do restore previously saved objects at startup
#>   --vanilla           Combine --no-save, --no-restore, --no-site-file,
#>                         --no-init-file and --no-environ
#>
#> Expressions (one or more '-e <expr>') may be used *instead* of 'file'.
#> Any additional 'args' can be accessed from R via 'commandArgs(TRUE)'.
#> See also  ?Rscript  from within R.

Rscript --version
#> Rscript (R) version 4.6.1 (2026-06-24)

Rscript --verbose args.R a 2>&1 | sed "s|'[^ ]*R --no-echo|'R --no-echo|"
#> running
#>   'R --no-echo --no-restore --file=args.R --args a'
#>
#> number of elements: 6
#> [1] "--no-echo"     "--no-restore"  "--file=args.R" "--args"
#> [5] "a"
#> [1] "a"

# args.R: show what the script receives.
all_args <- commandArgs()
cat("number of elements:", length(all_args), "\n")
print(all_args[-1L])
print(commandArgs(trailingOnly = TRUE))

Rscript args.R a
#> number of elements: 8
#> [1] "--no-save"     "--no-restore"  "--no-echo"     "--no-restore"
#> [5] "--file=args.R" "--args"        "a"
#> [1] "a"

Rscript --vanilla args.R a
#> number of elements: 7
#> [1] "--no-echo"     "--no-restore"  "--vanilla"     "--file=args.R"
#> [5] "--args"        "a"
#> [1] "a"

Rscript -e 'cat("one\n")' -e '2 + 2' extra1 extra2
#> one
#> [1] 4

Rscript args.R --version --help -e 1
#> number of elements: 9
#> [1] "--no-echo"     "--no-restore"  "--file=args.R" "--args"
#> [5] "--version"     "--help"        "-e"            "1"
#> [1] "--version" "--help"    "-e"        "1"

Rscript -e 'commandArgs(TRUE)' a b c
#> [1] "a" "b" "c"
Rscript -e 'commandArgs()[-1]'
#> [1] "--no-echo"         "--no-restore"      "-e"
#> [4] "commandArgs()[-1]"

Rscript -e 'cat("one\n")' -e 'stop("second expression")' -e '3'; echo $?
#> one
#> Error: second expression
#> Execution halted
#> 1
Rscript -e ''; echo $?
#> ERROR: option '-e' requires a non-empty argument
#> 1

echo 'cat(1 + 1, "\n")' | Rscript -
#> 2

# packages.R: which packages are attached at startup.
attached <- grep("^package:", search(), value = TRUE)
cat("attached:", sub("^package:", "", attached), "\n")
cat("methods attached:", "package:methods" %in% attached, "\n")

Rscript packages.R
#> attached: stats graphics grDevices utils datasets methods base
#> methods attached: TRUE
Rscript --default-packages=NULL packages.R
#> attached: base
#> methods attached: FALSE
Rscript --default-packages=utils,stats packages.R
#> attached: stats utils base
#> methods attached: FALSE
R_SCRIPT_DEFAULT_PACKAGES=utils R_DEFAULT_PACKAGES=NULL Rscript packages.R
#> attached: utils base
#> methods attached: FALSE

Rscript nope.R; echo $?
#> Fatal error: cannot open file 'nope.R': No such file or directory
#> 2
Rscript --nonsense -e '1'; echo $?
#> WARNING: unknown option '--nonsense'
#>
#> [1] 1
#> 0

Rscript args.R --genre fiction "two words" -x 3
#> number of elements: 10
#> [1] "--no-echo"     "--no-restore"  "--file=args.R" "--args"
#> [5] "--genre"       "fiction"       "two words"     "-x"
#> [9] "3"
#> [1] "--genre"   "fiction"   "two words" "-x"        "3"

Rscript args.R
#> number of elements: 4
#> [1] "--no-echo"     "--no-restore"  "--file=args.R"
#> character(0)

# script-dir.R: find the directory of the running script.
file_arg <- grep("^--file=", commandArgs(), value = TRUE)
if (length(file_arg) == 0L) {
  stop("no --file= argument: not run as a script file")
}
script <- sub("^--file=", "", file_arg[[1L]])
script_dir <- dirname(script)
cat("script as given:   ", script, "\n")
cat("directory as given:", script_dir, "\n")
cat("books.csv beside the script:",
    file.exists(file.path(script_dir, "books.csv")), "\n")

mkdir sub
cp books.csv script-dir.R sub
Rscript sub/script-dir.R
cd sub
Rscript script-dir.R
cd ..
Rscript -e 'source("sub/script-dir.R")'
#> script as given:    sub/script-dir.R
#> directory as given: sub
#> books.csv beside the script: TRUE
#> script as given:    script-dir.R
#> directory as given: .
#> books.csv beside the script: TRUE
#> Error in eval(ei, envir) : no --file= argument: not run as a script file
#> Calls: source -> withVisible -> eval -> eval
#> Execution halted

# quit-status.R: leave with the status given as the first argument.
args <- commandArgs(trailingOnly = TRUE)
status <- if (length(args) >= 1L) as.integer(args[[1L]]) else 0L
.Last <- function() cat("goodbye from .Last()\n")
cat("about to quit with status", status, "\n")
quit(save = "no", status = status)
cat("this line is never reached\n")

Rscript quit-status.R 3
echo "exit status: $?"
#> about to quit with status 3
#> goodbye from .Last()
#> exit status: 3
Rscript quit-status.R 300
echo $?
#> about to quit with status 300
#> goodbye from .Last()
#> 44

# error-status.R: an uncaught error ends the run.
cat("before the error\n")
total <- sum(c(1, 2, 3)) + "a"
cat("after the error\n")

Rscript error-status.R
echo "exit status: $?"
#> before the error
#> Error in sum(c(1, 2, 3)) + "a" : non-numeric argument to binary operator
#> Execution halted
#> exit status: 1

# warning-status.R: a warning does not change the exit status.
cat("before the warning\n")
x <- as.integer("three")
cat("after the warning:", x, "\n")

Rscript warning-status.R
echo "exit status: $?"
#> before the warning
#> Warning message:
#> NAs introduced by coercion
#> after the warning: NA
#> exit status: 0

# warn-as-error.R: turn every warning into an error.
options(warn = 2)
cat("reading the year\n")
year <- as.integer("20x6")
cat("never reached:", year, "\n")

Rscript warn-as-error.R
echo "exit status: $?"
#> reading the year
#> Error: (converted from warning) NAs introduced by coercion
#> Execution halted
#> exit status: 1

# error-option.R: run a handler when an error reaches the top level.
options(error = function() {
  message("handler: the run failed, leaving with status 3")
  quit(save = "no", status = 3L, runLast = FALSE)
})
check_year <- function(year) {
  stopifnot(is.numeric(year), year > 0)
  year
}
check_year(2026)
check_year("2026")
cat("never reached\n")

Rscript error-option.R
echo "exit status: $?"
#> [1] 2026
#> Error in check_year("2026") : is.numeric(year) is not TRUE
#> Calls: check_year -> stopifnot
#> handler: the run failed, leaving with status 3
#> exit status: 3

# catch-script-errors.R: keep going after an error (R 4.4.0 and later).
options(catch.script.errors = TRUE)
cat("first\n")
stop("the first problem")
cat("second\n")
log("a")
cat("third\n")

Rscript catch-script-errors.R
echo "exit status: $?"
#> first
#> Error: the first problem
#> second
#> Error in log("a") : non-numeric argument to mathematical function
#> third
#> exit status: 0

# quit-cleanup.R: what still runs when quit() is called inside a function.
tmp <- tempfile(fileext = ".txt")
writeLines("scratch data", tmp)

e <- new.env()
invisible(reg.finalizer(e, \(env) cat("finalizer ran\n"), onexit = TRUE))

.Last <- function() cat(".Last() ran\n")

leave <- function(status) {
  on.exit(cat("on.exit handler ran\n"))
  tryCatch(
    quit(save = "no", status = status),
    finally = cat("finally ran\n")
  )
}

cat("file exists before quit:", file.exists(tmp), "\n")
leave(5L)

Rscript quit-cleanup.R
echo "exit status: $?"
#> file exists before quit: TRUE
#> .Last() ran
#> finalizer ran
#> exit status: 5

# error-cleanup.R: what still runs when an error reaches the top level.
.Last <- function() cat(".Last() ran\n")

load_data <- function() stop("the data are unusable")

work <- function() {
  on.exit(cat("on.exit handler ran\n"))
  tryCatch(load_data(), finally = cat("finally ran\n"))
}

work()

Rscript error-cleanup.R
echo "exit status: $?"
#> Error in load_data() : the data are unusable
#> Calls: work -> tryCatch -> tryCatchList -> load_data
#> finally ran
#> on.exit handler ran
#> Execution halted
#> exit status: 1

# sink.R: divert standard output to a file, then restore it.
log_file <- tempfile(fileext = ".log")
sink(log_file)
print("diverted to the file")
cat("also diverted\n")
message("messages are not diverted by sink()")
sink()
cat("back on the console\n")
readLines(log_file)

# The message stream needs an already open connection and its own sink() call.
con <- file(log_file, open = "wt")
sink(con, type = "message")
message("now the message goes to the file")
sink(type = "message")
close(con)
readLines(log_file)

Rscript sink.R
#> messages are not diverted by sink()
#> back on the console
#> [1] "[1] \"diverted to the file\"" "also diverted"
#> [1] "now the message goes to the file"

# stdin-csv.R: parse CSV and numbers from standard input.
loans <- read.csv(file("stdin"), colClasses = "character")
cat("rows:", nrow(loans), " columns:", ncol(loans), "\n")
print(head(loans, 3L))

# stdin-scan.R: read whitespace-separated numbers from standard input.
x <- scan("stdin", quiet = TRUE)
cat("n =", length(x), " mean =", mean(x), "\n")

head -n 4 loans.csv | Rscript stdin-csv.R
#> rows: 3  columns: 5
#>   loan_id          isbn     member  loan_date return_date
#> 1    L001 9780141439518 Hugo Silva 2025-01-14  2025-02-04
#> 2    L002 9780306406157 Ben Okafor 2025-01-16  2025-01-26
#> 3    L003 9780002000291  Dev Patel 2025-01-21  2025-01-22
printf '1 2 3\n4 5\n' | Rscript stdin-scan.R
#> n = 5  mean = 3

R --quiet --vanilla -f batch.R --args a b
#> > # batch.R: a small script for the batch interfaces.
#> > args <- commandArgs(trailingOnly = TRUE)
#> > books <- read.csv("books.csv")
#> > x <- nrow(books)
#> > x
#> [1] 16
#> > print(table(books$genre)[1:2])
#>
#> Classic fiction
#>       2       1
#> > cat("arguments:", args, "\n")
#> arguments: a b
#> > y <- x * 2
#> >
R --no-echo --vanilla --file=batch.R --args "two words"
#> [1] 16
#>
#> Classic fiction
#>       2       1
#> arguments: two words
R --quiet --vanilla < batch.R
#> > # batch.R: a small script for the batch interfaces.
#> > args <- commandArgs(trailingOnly = TRUE)
#> > books <- read.csv("books.csv")
#> > x <- nrow(books)
#> > x
#> [1] 16
#> > print(table(books$genre)[1:2])
#>
#> Classic fiction
#>       2       1
#> > cat("arguments:", args, "\n")
#> arguments:
#> > y <- x * 2
#> >
R --quiet --vanilla -e '1 + 1'
#> > 1 + 1
#> [1] 2
#> >

# secret.R: take a credential from the environment, never from the script.
password <- Sys.getenv("SHELF_DB_PASSWORD", unset = NA_character_)
if (is.na(password) || !nzchar(password)) {
  message("secret.R: set SHELF_DB_PASSWORD in the environment")
  quit(save = "no", status = 1L)
}
cat("password found,", nchar(password), "characters\n")

Rscript secret.R
echo $?
#> secret.R: set SHELF_DB_PASSWORD in the environment
#> 1
SHELF_DB_PASSWORD=placeholder-value Rscript secret.R
echo $?
#> password found, 17 characters
#> 0

# read-renviron.R: read variables from an environment file by hand.
env_file <- tempfile(fileext = ".Renviron")
writeLines(c(
  "# settings for the shelf report",
  "SHELF_FORMAT=csv",
  "SHELF_REPORT_DIR=\"${SHELF_BASE-/srv/shelf}/reports\""
), env_file)

Sys.getenv("SHELF_FORMAT", unset = NA)
readRenviron(env_file)
Sys.getenv("SHELF_FORMAT", unset = NA)
Sys.getenv("SHELF_REPORT_DIR")

Rscript read-renviron.R
#> [1] NA
#> [1] "csv"
#> [1] "/srv/shelf/reports"

TZ=Asia/Tokyo Rscript -e 'format(as.POSIXct("2026-06-30 12:00:00", tz = "UTC"), tz = "", usetz = TRUE)'
TZ=UTC Rscript -e 'format(as.POSIXct("2026-06-30 12:00:00", tz = "UTC"), tz = "", usetz = TRUE)'
#> [1] "2026-06-30 21:00:00 JST"
#> [1] "2026-06-30 12:00:00 UTC"
Rscript -e 'sQuote("x")'
LC_ALL=C Rscript -e 'sQuote("x")'
#> [1] "‘x’"
#> [1] "'x'"

# utf8.R: the same file under two locales.
word <- "café"
cat(word, "\n")
nchar(word)

Rscript utf8.R
LC_ALL=C Rscript utf8.R
#> café
#> [1] 4
#> café
#> [1] 5

# system2.R: run another R process and capture what it prints.
cat("Rscript found on the PATH:", nzchar(Sys.which("Rscript")), "\n")

Sys.setenv(SHELF_MODE = "child")
code <- "cat(Sys.getenv('SHELF_MODE'), commandArgs(TRUE), '\\n')"
out <- system2("Rscript", c("-e", shQuote(code), "a", "b"), stdout = TRUE)
out

# A failing child: with stdout = TRUE the output is kept and the status
# becomes an attribute (R also warns, which is suppressed here).
failing <- "cat('partial\\n'); quit(status = 4)"
bad <- suppressWarnings(
  system2("Rscript", c("-e", shQuote(failing)), stdout = TRUE)
)
as.vector(bad)
attr(bad, "status")

# Without capturing, system2() returns the exit status.
status <- system2(
  "Rscript", c("-e", shQuote("quit(status = 7)")),
  stdout = FALSE, stderr = FALSE
)
status

Rscript system2.R
#> Rscript found on the PATH: TRUE
#> [1] "child a b "
#> [1] "partial"
#> [1] 4
#> [1] 7

# parse-base.R: a small hand-written option parser (base R only).
usage <- function() {
  cat("Usage: Rscript parse-base.R [--today DATE] [--genre NAME]",
      "[--format text|csv] [--stdin] [FILE ...]\n")
}

usage_error <- function(...) {
  stop(structure(
    class = c("usage_error", "error", "condition"),
    list(message = paste0(...), call = NULL)
  ))
}

parse_options <- function(argv) {
  opts <- list(today = NA_character_, genre = NA_character_,
               format = "text", stdin = FALSE, files = character())
  i <- 1L
  while (i <= length(argv)) {
    arg <- argv[[i]]
    if (arg == "--") {
      opts$files <- c(opts$files, argv[-seq_len(i)])
      break
    }
    if (!startsWith(arg, "--")) {
      opts$files <- c(opts$files, arg)
      i <- i + 1L
      next
    }
    name <- sub("^--([^=]*).*$", "\\1", arg)
    if (!name %in% c("today", "genre", "format", "stdin")) {
      usage_error("unknown option: --", name)
    }
    if (name == "stdin") {
      opts$stdin <- TRUE
    } else if (grepl("=", arg, fixed = TRUE)) {
      opts[[name]] <- sub("^[^=]*=", "", arg)
    } else {
      i <- i + 1L
      if (i > length(argv)) usage_error("option --", name, " needs a value")
      opts[[name]] <- argv[[i]]
    }
    i <- i + 1L
  }
  opts$format <- tryCatch(
    match.arg(opts$format, c("text", "csv")),
    error = \(e) usage_error("--format: ", conditionMessage(e))
  )
  opts
}

argv <- commandArgs(trailingOnly = TRUE)
if (any(argv %in% c("-h", "--help"))) {
  usage()
  quit(save = "no", status = 0L)
}
opts <- tryCatch(parse_options(argv), usage_error = \(e) {
  message("parse-base.R: ", conditionMessage(e))
  usage()
  quit(save = "no", status = 2L)
})
str(opts)

Rscript parse-base.R --today 2026-06-30 --genre=fiction books.csv extra
#> List of 5
#>  $ today : chr "2026-06-30"
#>  $ genre : chr "fiction"
#>  $ format: chr "text"
#>  $ stdin : logi FALSE
#>  $ files : chr [1:2] "books.csv" "extra"
Rscript parse-base.R --stdin -- --odd
#> List of 5
#>  $ today : chr NA
#>  $ genre : chr NA
#>  $ format: chr "text"
#>  $ stdin : logi TRUE
#>  $ files : chr "--odd"
Rscript parse-base.R --help
echo $?
#> Usage: Rscript parse-base.R [--today DATE] [--genre NAME] [--format text|csv] [--stdin] [FILE ...]
#> 0
Rscript parse-base.R --colour red
echo $?
#> parse-base.R: unknown option: --colour
#> Usage: Rscript parse-base.R [--today DATE] [--genre NAME] [--format text|csv] [--stdin] [FILE ...]
#> 2
Rscript parse-base.R --format xml
echo $?
#> parse-base.R: --format: 'arg' should be one of “text”, “csv”
#> Usage: Rscript parse-base.R [--today DATE] [--genre NAME] [--format text|csv] [--stdin] [FILE ...]
#> 2
Rscript parse-base.R --genre
echo $?
#> parse-base.R: option --genre needs a value
#> Usage: Rscript parse-base.R [--today DATE] [--genre NAME] [--format text|csv] [--stdin] [FILE ...]
#> 2

# parse-optparse.R: the same options with optparse (a CRAN package).
library(optparse)

option_list <- list(
  make_option("--today", help = "report date, YYYY-MM-DD"),
  make_option("--genre", help = "only this genre"),
  make_option("--format", default = "text",
              help = "output format: text or csv [default: %default]"),
  make_option("--stdin", action = "store_true", default = FALSE,
              help = "read the loans from standard input")
)
parser <- OptionParser(
  usage = "Rscript %prog [options] [FILE ...]",
  option_list = option_list,
  description = "Print a loan report for the shelf catalogue."
)
parsed <- parse_args(parser, positional_arguments = TRUE)
str(parsed)

Rscript parse-optparse.R --help
echo $?
#> Usage: Rscript parse-optparse.R [options] [FILE ...]
#> Print a loan report for the shelf catalogue.
#>
#> Options:
#> 	--today=TODAY
#> 		report date, YYYY-MM-DD
#>
#> 	--genre=GENRE
#> 		only this genre
#>
#> 	--format=FORMAT
#> 		output format: text or csv [default: text]
#>
#> 	--stdin
#> 		read the loans from standard input
#>
#> 	-h, --help
#> 		Show this help message and exit
#>
#>
#> 0
Rscript parse-optparse.R --today 2026-06-30 --genre=fiction books.csv
#> List of 2
#>  $ options:List of 5
#>   ..$ today : chr "2026-06-30"
#>   ..$ genre : chr "fiction"
#>   ..$ format: chr "text"
#>   ..$ stdin : logi FALSE
#>   ..$ help  : logi FALSE
#>  $ args   : chr "books.csv"
Rscript parse-optparse.R --colour red
echo $?
#> Usage: Rscript parse-optparse.R [options] [FILE ...]
#>
#> parse-optparse.R: error: long flag "colour" is invalid
#> 1

# parse-argparse.R: the same options with argparse (needs Python 3).
library(argparse)

parser <- ArgumentParser(
  description = "Print a loan report for the shelf catalogue."
)
parser$add_argument("--today", help = "report date, YYYY-MM-DD")
parser$add_argument("--genre", help = "only this genre")
parser$add_argument("--format", choices = c("text", "csv"), default = "text",
                    help = "output format [default: %(default)s]")
parser$add_argument("--stdin", action = "store_true",
                    help = "read the loans from standard input")
parser$add_argument("files", nargs = "*", help = "CSV files")
args <- parser$parse_args()
str(args)

Rscript parse-argparse.R --help
echo $?
#> usage: parse-argparse.R [-h] [--today TODAY] [--genre GENRE]
#>                         [--format {text,csv}] [--stdin]
#>                         [files ...]
#>
#> Print a loan report for the shelf catalogue.
#>
#> positional arguments:
#>   files                CSV files
#>
#> options:
#>   -h, --help           show this help message and exit
#>   --today TODAY        report date, YYYY-MM-DD
#>   --genre GENRE        only this genre
#>   --format {text,csv}  output format [default: text]
#>   --stdin              read the loans from standard input
#> 0
Rscript parse-argparse.R --today 2026-06-30 --genre=fiction books.csv loans.csv
#> List of 5
#>  $ files : chr [1:2] "books.csv" "loans.csv"
#>  $ format: chr "text"
#>  $ genre : chr "fiction"
#>  $ stdin : logi FALSE
#>  $ today : chr "2026-06-30"
Rscript parse-argparse.R --format xml
echo $?
#> usage: parse-argparse.R [-h] [--today TODAY] [--genre GENRE]
#>                         [--format {text,csv}] [--stdin]
#>                         [files ...]
#> parse-argparse.R: error: argument --format: invalid choice: 'xml' (choose from 'text', 'csv')
#> 1
Rscript parse-argparse.R --gen fiction
#> List of 5
#>  $ files : list()
#>  $ format: chr "text"
#>  $ genre : chr "fiction"
#>  $ stdin : logi FALSE
#>  $ today : NULL

Error in findpython::find_python_cmd(required_modules = required_modules) :
  Couldn't find a sufficient Python binary. If you haven't installed the Python dependency yet please do so. If you have but it isn't on the system path (as is default on Windows) please add it to path or set options('python_cmd'='/path/to/binary')  or set the PYTHON, PYTHON2, or PYTHON3 environmental variables.   Python must have access to the modules: argparse, json | simplejson
Calls: ArgumentParser -> find_python_cmd -> <Anonymous>

# report.R: print a loan report for the shelf catalogue.
#
# Usage: Rscript report.R [--today DATE] [--genre NAME] [--format text|csv]
#                         [--books FILE] [--loans FILE | --stdin]
#
# Exit status: 0 success, 1 data error, 2 usage error.
suppressPackageStartupMessages(library(shelf))

usage <- function(con = stdout()) {
  cat("Usage: Rscript report.R [--today DATE] [--genre NAME]\n",
      "                       [--format text|csv] [--books FILE]\n",
      "                       [--loans FILE | --stdin]\n",
      "Without --today the variable SHELF_TODAY is used.\n",
      sep = "", file = con)
}

condition_class <- function(class, ...) {
  structure(class = c(class, "error", "condition"),
            list(message = paste0(...), call = NULL))
}
usage_error <- function(...) stop(condition_class("usage_error", ...))
data_error <- function(...) stop(condition_class("data_error", ...))

parse_options <- function(argv) {
  opts <- list(today = Sys.getenv("SHELF_TODAY", unset = ""), genre = "",
               format = "text", books = "books.csv", loans = "",
               stdin = FALSE)
  i <- 1L
  while (i <= length(argv)) {
    arg <- argv[[i]]
    name <- sub("^--([^=]*).*$", "\\1", arg)
    if (!startsWith(arg, "--") || !name %in% names(opts)) {
      usage_error("unknown argument: ", arg)
    }
    if (name == "stdin") {
      opts$stdin <- TRUE
    } else if (grepl("=", arg, fixed = TRUE)) {
      opts[[name]] <- sub("^[^=]*=", "", arg)
    } else {
      i <- i + 1L
      if (i > length(argv)) usage_error("option --", name, " needs a value")
      opts[[name]] <- argv[[i]]
    }
    i <- i + 1L
  }
  opts$format <- tryCatch(
    match.arg(opts$format, c("text", "csv")),
    error = \(e) usage_error("--format must be text or csv")
  )
  if (!nzchar(opts$today)) usage_error("--today (or SHELF_TODAY) is required")
  opts$today <- as.Date(opts$today, format = "%Y-%m-%d")
  if (is.na(opts$today)) usage_error("the report date must be YYYY-MM-DD")
  if (opts$stdin && nzchar(opts$loans)) {
    usage_error("--stdin and --loans exclude each other")
  }
  if (!nzchar(opts$loans)) opts$loans <- "loans.csv"
  opts
}

read_table <- function(path, what, columns) {
  if (!identical(path, "stdin") && !file.exists(path)) {
    data_error(what, " file not found: ", path)
  }
  con <- if (identical(path, "stdin")) file("stdin") else path
  table <- read.csv(con, colClasses = "character")
  missing <- setdiff(columns, names(table))
  if (length(missing) > 0L) {
    data_error(what, " data lacks the column(s): ", toString(missing))
  }
  table
}

run <- function(argv) {
  if (any(argv %in% c("-h", "--help"))) {
    usage()
    return(invisible())
  }
  opts <- parse_options(argv)
  books <- read_table(opts$books, "books", c("title", "isbn", "genre"))
  loans <- read_table(if (opts$stdin) "stdin" else opts$loans, "loans",
                      c("loan_id", "isbn", "loan_date", "return_date"))
  books <- clean_books(books)
  loans <- clean_loans(loans)

  report <- loan_summary(loans, books, opts$today)
  if (nzchar(opts$genre)) {
    if (!opts$genre %in% report$genre) {
      usage_error("unknown genre '", opts$genre, "'; known genres: ",
                  toString(report$genre))
    }
    report <- report[report$genre == opts$genre, , drop = FALSE]
  }
  report$overdue_rate <- round(report$overdue_rate, 3)

  n_bad_date <- sum(is.na(loans$loan_date))
  if (n_bad_date > 0L) {
    warning(n_bad_date, " loan(s) have no valid loan date", call. = FALSE)
  }
  n_unknown <- sum(!loans$isbn %in% books$isbn)
  if (n_unknown > 0L) {
    warning(n_unknown, " loan(s) match no book and are left out", call. = FALSE)
  }

  if (opts$format == "csv") {
    write.csv(report, row.names = FALSE)
  } else {
    cat("Loan report for ", format(opts$today), ", loan period ",
        getOption("shelf.loan_days"), " days\n\n", sep = "")
    print(report, row.names = FALSE)
    cat("\nOverdue: ", sum(report$overdue), " of ", sum(report$loans),
        " loans\n", sep = "")
  }
}

status <- tryCatch({
  run(commandArgs(trailingOnly = TRUE))
  0L
}, usage_error = \(e) {
  message("report.R: ", conditionMessage(e))
  usage(stderr())
  2L
}, data_error = \(e) {
  message("report.R: ", conditionMessage(e))
  1L
})
quit(save = "no", status = status)

Rscript report.R --today 2026-06-30
echo "exit status: $?"
#> Loan report for 2026-06-30, loan period 21 days
#>
#>            genre loans overdue overdue_rate
#>          classic     6       3        0.500
#>          fiction    23      13        0.565
#>          mystery     4       2        0.500
#>      non-fiction     3       2        0.667
#>           poetry     6       4        0.667
#>  science fiction    15       7        0.467
#>
#> Overdue: 31 of 57 loans
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out
#> exit status: 0

Rscript report.R --today 2026-06-30 --genre fiction
echo "exit status: $?"
#> Loan report for 2026-06-30, loan period 21 days
#>
#>    genre loans overdue overdue_rate
#>  fiction    23      13        0.565
#>
#> Overdue: 13 of 23 loans
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out
#> exit status: 0
Rscript report.R --today 2026-06-30 --format csv 2> warnings.txt | head -n 4
echo '--- warnings.txt:'
cat warnings.txt
#> "genre","loans","overdue","overdue_rate"
#> "classic",6,3,0.5
#> "fiction",23,13,0.565
#> "mystery",4,2,0.5
#> --- warnings.txt:
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out

Rscript report.R --today 2026-06-30 --format csv > loan-report.csv
echo $?
wc -l loan-report.csv
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out
#> 0
#> 7 loan-report.csv
Rscript report.R --today 2026-06-30 > /dev/null
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out

Rscript report.R --today 2026-06-30 --stdin < loans.csv
echo "exit status: $?"
#> Loan report for 2026-06-30, loan period 21 days
#>
#>            genre loans overdue overdue_rate
#>          classic     6       3        0.500
#>          fiction    23      13        0.565
#>          mystery     4       2        0.500
#>      non-fiction     3       2        0.667
#>           poetry     6       4        0.667
#>  science fiction    15       7        0.467
#>
#> Overdue: 31 of 57 loans
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out
#> exit status: 0
SHELF_TODAY=2026-03-31 Rscript report.R --genre poetry
echo "exit status: $?"
#> Loan report for 2026-03-31, loan period 21 days
#>
#>   genre loans overdue overdue_rate
#>  poetry     6       3          0.5
#>
#> Overdue: 3 of 6 loans
#> Warning messages:
#> 1: 1 loan(s) have no valid loan date
#> 2: 3 loan(s) match no book and are left out
#> exit status: 0
Rscript report.R --today 2026-06-30 --genre fiction --format csv 2> /dev/null |
  Rscript -e 'x <- read.csv(file("stdin")); cat(x$genre, x$overdue_rate, "\n")'
#> fiction 0.565

Rscript report.R --today 2026-06-30 --genre nonsense
echo "exit status: $?"
#> report.R: unknown genre 'nonsense'; known genres: classic, fiction, mystery, non-fiction, poetry, science fiction
#> Usage: Rscript report.R [--today DATE] [--genre NAME]
#>                        [--format text|csv] [--books FILE]
#>                        [--loans FILE | --stdin]
#> Without --today the variable SHELF_TODAY is used.
#> exit status: 2
Rscript report.R
echo "exit status: $?"
#> report.R: --today (or SHELF_TODAY) is required
#> Usage: Rscript report.R [--today DATE] [--genre NAME]
#>                        [--format text|csv] [--books FILE]
#>                        [--loans FILE | --stdin]
#> Without --today the variable SHELF_TODAY is used.
#> exit status: 2
Rscript report.R --today 2026-06-30 --format xml
echo "exit status: $?"
#> report.R: --format must be text or csv
#> Usage: Rscript report.R [--today DATE] [--genre NAME]
#>                        [--format text|csv] [--books FILE]
#>                        [--loans FILE | --stdin]
#> Without --today the variable SHELF_TODAY is used.
#> exit status: 2
Rscript report.R --today 2026-06-30 --stdin --loans loans.csv < loans.csv
echo "exit status: $?"
#> report.R: --stdin and --loans exclude each other
#> Usage: Rscript report.R [--today DATE] [--genre NAME]
#>                        [--format text|csv] [--books FILE]
#>                        [--loans FILE | --stdin]
#> Without --today the variable SHELF_TODAY is used.
#> exit status: 2
Rscript report.R --help
echo "exit status: $?"
#> Usage: Rscript report.R [--today DATE] [--genre NAME]
#>                        [--format text|csv] [--books FILE]
#>                        [--loans FILE | --stdin]
#> Without --today the variable SHELF_TODAY is used.
#> exit status: 0

Rscript report.R --today 2026-06-30 --loans nope.csv
echo "exit status: $?"
#> report.R: loans file not found: nope.csv
#> exit status: 1
Rscript report.R --today 2026-06-30 --loans books.csv
echo "exit status: $?"
#> report.R: loans data lacks the column(s): loan_id, loan_date, return_date
#> exit status: 1

# read-missing.R: read the CSV file named on the command line.
args <- commandArgs(trailingOnly = TRUE)
loans <- read.csv(args[[1L]])
cat(nrow(loans), "rows\n")

Rscript read-missing.R nope.csv
echo "exit status: $?"
#> Error in file(file, "rt") : cannot open the connection
#> Calls: read.csv -> read.table -> file
#> In addition: Warning message:
#> In file(file, "rt") :
#>   cannot open file 'nope.csv': No such file or directory
#> Execution halted
#> exit status: 1
Rscript read-missing.R
echo "exit status: $?"
#> Error in args[[1L]] : subscript out of bounds
#> Calls: read.csv -> read.table
#> Execution halted
#> exit status: 1