README.md
1optparse: Command line optional argument parser
2===============================================
3
4[](https://cran.r-project.org/package=optparse)
5
6[](https://travis-ci.org/trevorld/r-optparse)
7
8[](https://ci.appveyor.com/project/trevorld/r-optparse)
9
10[](https://codecov.io/github/trevorld/r-optparse?branch=master)
11
12[](https://cran.r-project.org/package=optparse)
13
14A pure R language command line parser inspired by Python\'s \'optparse\'
15library to be used with Rscript to write \"\#!\" shebang scripts that
16accept short and long flag/options.
17
18To install the last version released on CRAN use the following command:
19
20``` {.r}
21install.packages("optparse")
22```
23
24To install the development version use the following command:
25
26``` {.r}
27install.packages("remotes")
28remotes::install_github("trevorld/r-optparse")
29```
30
31dependencies
32------------
33
34This package depends on the R package `getopt`.
35
36To run the unit tests you will need the suggested R package `testthat`
37and in order to build the vignette you will need the suggested R package
38`knitr` which in turn probably requires the system tool `pandoc`:
39
40``` {.bash}
41sudo apt install pandoc
42```
43
44examples
45--------
46
47A simple example:
48
49``` {.r}
50library("optparse")
51parser <- OptionParser()
52parser <- add_option(parser, c("-v", "--verbose"), action="store_true",
53 default=TRUE, help="Print extra output [default]")
54parser <- add_option(parser, c("-q", "--quietly"), action="store_false",
55 dest="verbose", help="Print little output")
56parser <- add_option(parser, c("-c", "--count"), type="integer", default=5,
57 help="Number of random normals to generate [default %default]",
58 metavar="number")
59parse_args(parser, args = c("--quietly", "--count=15"))
60```
61
62 ## $help
63 ## [1] FALSE
64 ##
65 ## $verbose
66 ## [1] FALSE
67 ##
68 ## $count
69 ## [1] 15
70
71Note that the `args` argument of `parse_args` default is
72`commandArgs(trailing=TRUE)` so it typically doesn\'t need to be
73explicitly set if writing an Rscript.
74
75One can also equivalently make options in a list:
76
77``` {.r}
78library("optparse")
79option_list <- list(
80 make_option(c("-v", "--verbose"), action="store_true", default=TRUE,
81 help="Print extra output [default]"),
82 make_option(c("-q", "--quietly"), action="store_false",
83 dest="verbose", help="Print little output"),
84 make_option(c("-c", "--count"), type="integer", default=5,
85 help="Number of random normals to generate [default %default]",
86 metavar="number")
87 )
88
89parse_args(OptionParser(option_list=option_list), args = c("--verbose", "--count=11"))
90```
91
92 ## $verbose
93 ## [1] TRUE
94 ##
95 ## $count
96 ## [1] 11
97 ##
98 ## $help
99 ## [1] FALSE
100
101`optparse` automatically creates a help option:
102
103``` {.r}
104parse_args(parser, args = c("--help"))
105```
106
107 Usage: %prog [options]
108
109
110 Options:
111 -h, --help
112 Show this help message and exit
113
114 -v, --verbose
115 Print extra output [default]
116
117 -q, --quietly
118 Print little output
119
120 -c NUMBER, --count=NUMBER
121 Number of random normals to generate [default 5]
122
123
124 Error in parse_args(parser, args = c("--help")) : help requested
125
126Note by default when `optparse::parse_args` sees a `--help` flag it will
127first print out a usage message and then either throw an error in
128interactive use or call `quit` in non-interactive use (i.e. when used
129within an Rscript called by a shell). To disable the error/quit set the
130argument `print_help_and_exit` to `FALSE` in `parse_args` and to simply
131print out the usage string one can also use the function `print_usage`.
132
133`optparse` has limited positional argument support, other command-line
134parsers for R such as `argparse` have richer positional argument
135support:
136
137``` {.r}
138parse_args(parser, args = c("-v", "-c25", "75", "22"), positional_arguments = TRUE)
139```
140
141 ## $options
142 ## $options$help
143 ## [1] FALSE
144 ##
145 ## $options$verbose
146 ## [1] TRUE
147 ##
148 ## $options$count
149 ## [1] 5
150 ##
151 ##
152 ## $args
153 ## [1] "-c25" "75" "22"
154
155The function `parse_args2` wraps `parse_args` while setting
156`positional_arguments=TRUE` and `convert_hyphens_to_underscores=TRUE`:
157
158``` {.r}
159parse_args2(parser, args = c("-v", "-c25", "75", "22"))
160```
161
162 ## $options
163 ## $options$help
164 ## [1] FALSE
165 ##
166 ## $options$verbose
167 ## [1] TRUE
168 ##
169 ## $options$count
170 ## [1] 5
171 ##
172 ##
173 ## $args
174 ## [1] "-c25" "75" "22"
175
){kind=link}
){kind=link}