optparse is a command line option parser inspired by Python’s “optparse” library. Use this with Rscript to write “#!”-shebang scripts that accept short and long flags/options, generate a usage statement, and set default values for options that are not specified on the command line.
In our working directory we have two example R scripts, named “example.R” and “display_file.R” illustrating the use of the optparse package.
bash$ ls
display_file.R
example.RIn order for a *nix system to recognize a “#!”-shebang line you need to mark the file executable with the chmod command, it also helps to add the directory containing your Rscripts to your path:
bash$ chmod ug+x display_file.R example.R
bash$ export PATH=$PATH:$(pwd)
Here is what example.R contains:
bash$ display_file.R example.R
#!/usr/bin/env Rscript
# Copyright 2010-2013 Trevor L Davis <trevor.l.davis@gmail.com>
# Copyright 2008 Allen Day
#
# This file is free software: you may copy, redistribute and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation, either version 2 of the License, or (at your
# option) any later version.
#
# This file is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
suppressPackageStartupMessages(library("optparse"))
suppressPackageStartupMessages(library("stats"))
# specify our desired options in a list
# by default OptionParser will add an help option equivalent to
# make_option(c("-h", "--help"), action="store_true", default=FALSE,
# help="Show this help message and exit")
parser <- OptionParser()
parser <- add_option(
parser,
c("-v", "--verbose"),
action = "store_true",
default = TRUE,
help = "Print extra output [default %default]"
)
parser <- add_option(
parser,
c("-q", "--quietly"),
action = "store_false",
dest = "verbose",
help = "Print little output"
)
parser <- add_option(
parser,
c("-c", "--count"),
type = "integer",
default = 5,
help = "Number of random normals to generate [default %default]",
metavar = "number"
)
parser <- add_option(
parser,
"--generator",
default = "rnorm",
help = "Function to generate random deviates [default \"%default\"]"
)
parser <- add_option(
parser,
"--mean",
default = 0,
help = "Mean if generator == \"rnorm\" [default %default]"
)
parser <- add_option(
parser,
"--sd",
default = 1,
metavar = "standard deviation",
help = "Standard deviation if generator == \"rnorm\" [default %default]"
)
# get command line options, if help option encountered print help and exit,
# otherwise if options not found on command line then set defaults,
opt <- parse_args(parser)
# print some progress messages to stderr if "quietly" wasn't requested
if (opt$verbose) {
write("writing some verbose output to standard error...\n", stderr())
}
# do some operations based on user input
if (opt$generator == "rnorm") {
cat(paste(rnorm(opt$count, mean = opt$mean, sd = opt$sd), collapse = "\n"))
} else {
cat(paste(do.call(opt$generator, list(opt$count)), collapse = "\n"))
}
cat("\n")By default optparse will generate a help message if it encounters --help or -h on the command line. Note how %default in the example program was replaced by the actual default values in the help statement that optparse generated.
bash$ example.R –help
Usage: example.R [options]
Options:
-h, --help
Show this help message and exit
-v, --verbose
Print extra output [default TRUE]
-q, --quietly
Print little output
-c NUMBER, --count=NUMBER
Number of random normals to generate [default 5]
--generator=GENERATOR
Function to generate random deviates [default "rnorm"]
--mean=MEAN
Mean if generator == "rnorm" [default 0]
--sd=STANDARD DEVIATION
Standard deviation if generator == "rnorm" [default 1]If you specify default values when creating your OptionParser then optparse will use them as expected.
bash$ example.R
writing some verbose output to standard error...
1.41264109567518
-0.779564831143886
-1.23622999520547
0.119929588733938
1.42498571408384Or you can specify your own values.
bash$ example.R –mean=10 –sd=10 –count=3
writing some verbose output to standard error...
12.9747492282234
11.6133792697492
-3.49399887964845If you remember from the example program that --quietly had action="store_false" and dest="verbose". This means that --quietly is a switch that turns the verbose option from its default value of TRUE to FALSE. Note how the verbose and quietly options store their value in the exact same variable.
bash$ example.R –quiet -c 4 –generator=“runif”
0.720334429992363
0.071449444629252
0.239036649698392
0.265581218758598If you specify an illegal flag then optparse will throw an error.
bash$ example.R –silent -m 5
Usage: example.R [options]
example.R: error: long flag "silent" is invalidIf you specify the same option multiple times then optparse will use the value of the last option specified.
bash$ example.R -c 100 -c 2 -c 1000 -c 7
writing some verbose output to standard error...
0.797204792397212
-0.182394785369143
-0.04490988099242
0.562906275827394
-0.0443860969096171
0.681366292224717
-0.301278807414258optparse can also recognize positional arguments if parse_args is given the option positional_arguments = c(min_pa, max_pa) where min_pa is the minimum and max_pa is the maximum number of supported positional arguments. (A single numeric corresponds to min_pa == max_pa, TRUE is equivalent to c(0, Inf), and FALSE, the default, is equivalent to 0.) Below we give an example program display_file.R, which is a program that prints out the contents of a single file (the required positional argument, not an optional argument) and which accepts the normal help option as well as an option to add line numbers to the output. Note that the positional arguments need to be placed after the optional arguments.
bash$ display_file.R –help
Usage: display_file.R [options] file
Options:
-h, --help
Show this help message and exit
-n, --add_numbers
Print line number at the beginning of each line [default]bash$ display_file.R –add_numbers display_file.R
1 #!/usr/bin/env Rscript
2 # Copyright 2010-2013 Trevor L Davis <trevor.l.davis@gmail.com>
3 # Copyright 2013 Kirill Müller
4 #
5 # This file is free software: you may copy, redistribute and/or modify it
6 # under the terms of the GNU General Public License as published by the
7 # Free Software Foundation, either version 2 of the License, or (at your
8 # option) any later version.
9 #
10 # This file is distributed in the hope that it will be useful, but
11 # WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 # General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program. If not, see <http://www.gnu.org/licenses/>.
17 suppressPackageStartupMessages(library("optparse"))
18
19 parser <- OptionParser(usage = "%prog [options] file")
20 parser <- add_option(
21 parser,
22 c("-n", "--add_numbers"),
23 action = "store_true",
24 default = FALSE,
25 help = "Print line number at the beginning of each line [default]"
26 )
27
28 arguments <- parse_args(parser, positional_arguments = 1)
29 opt <- arguments$options
30 file <- arguments$args
31
32 if (!file.exists(file)) {
33 stop(sprintf("Specified file ( %s ) does not exist", file))
34 } else {
35 file_text <- readLines(file)
36 }
37
38 if (opt$add_numbers) {
39 cat(paste(seq_along(file_text), file_text), sep = "\n")
40 } else {
41 cat(file_text, sep = "\n")
42 }bash$ display_file.R non_existent_file.txt
Error: Specified file ( non_existent_file.txt ) does not exist
Execution haltedbash$ display_file.R
Usage: display_file.R [options] file
display_file.R: error: required at least 1 positional arguments, got 0