Command Line Option Parser

A command line parser inspired by Python's 'optparse' library to be used with Rscript to write "#!" shebang scripts that accept short and long flag/options.


CRAN Status Badge

Travis-CI Build Status

AppVeyor Build Status

Coverage Status

RStudio CRAN mirror downloads

A pure R language command line parser inspired by Python's 'optparse' library to be used with Rscript to write "#!" shebang scripts that accept short and long flag/options.

To install the last version released on CRAN use the following command:

To install the development version use the following command:

> remotes::install_github("trevorld/r-optparse")

dependencies

This package depends on the R package getopt.

To run the unit tests you will need the suggested R package testthat and in order to build the vignette you will need the suggested R package knitr which in turn probably requires the system tool pandoc:

$ sudo apt-get install pandoc

examples

A simple example:

> library("optparse")
> parser <- OptionParser()
> parser <- add_option(parser, c("-v", "--verbose"), action="store_true", 
>                 default=TRUE, help="Print extra output [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")
> parse_args(parser, args = c("--quietly", "--count=15"))
$help
[1] FALSE

$verbose
[1] FALSE

$count
[1] 15

Note that the args argument of parse_args default is commandArgs(trailing=TRUE) so it typically doesn't need to be explicitly set if writing an Rscript.

One can also equivalently make options in a list:

> library("optparse")
> option_list <- list( 
>     make_option(c("-v", "--verbose"), action="store_true", default=TRUE,
>         help="Print extra output [default]"),
>     make_option(c("-q", "--quietly"), action="store_false", 
>         dest="verbose", help="Print little output"),
>     make_option(c("-c", "--count"), type="integer", default=5, 
>         help="Number of random normals to generate [default %default]",
>         metavar="number")
>     )
>                                     
> parse_args(OptionParser(option_list=option_list), args = c("--verbose", "--count=11"))
$verbose
[1] TRUE

$count
[1] 11

$help
[1] FALSE

optparse automatically creates a help option:

> parse_args(parser, args = c("--help"))

Usage: %prog [options]


Options:
    -h, --help
        Show this help message and exit

    -v, --verbose
        Print extra output [default]

    -q, --quietly
        Print little output

    -c NUMBER, --count=NUMBER
        Number of random normals to generate [default 5]


Error in parse_args(parser, args = c("--help")) : help requested

Note by default when optparse::parse_args sees a --help flag it will first print out a usage message and then either throw an error in interactive use or call quit in non-interactive use (i.e. when used within an Rscript called by a shell). To disable the error/quit set the argument print_help_and_exit to FALSE in parse_args and to simply print out the usage string one can also use the function print_usage.

optparse has limited positional argument support, other command-line parsers for R such as argparse have richer positional argument support:

> parse_args(parser, args = c("-v", "-c25", "75", "22"), positional_arguments = TRUE)

$options
$options$help
[1] FALSE

$options$verbose
[1] TRUE

$options$count
[1] 5


$args
[1] "75"   "22"  

The function parse_args2 wraps parse_args while setting positional_arguments=TRUE and convert_hyphens_to_underscores=TRUE:

> parse_args2(parser, args = c("-v", "-c25", "75", "22"))

$options
$options$help
[1] FALSE

$options$verbose
[1] TRUE

$options$count
[1] 5


$args
[1] "75"   "22"  

News

optparse 1.6.1

  • Improve accuracy of README (#27). Thanks Alex Penson for bug report.

optparse 1.6.0

  • Support for callback actions (#26). Thanks Gyu Jin Choi for patch.

optparse 1.5.0

  • If interactive() == FALSE and print_help_and_exit == TRUE then optparse will now call quit(status=0) instead of quit(status=1) after printing the help message (this matches behaviour of the python package).
  • Better error message when forgetting to set add_help_option=FALSE when defining an -h or --help flag. Thanks Jeff P. Bruce for bug report.
  • Increment getopt requirement so that empty strings are parsed correctly. Thanks Matthew Flickinger for bug report.

optparse 1.4.4

  • Minor documentation fixes. Thanks J. J. Ramsey and Daeyoung Kim for bug reports.

optparse 1.4.1

  • Fix bug when add_help_option in OptionParser set to FALSE. Thanks to Jeff Bruce for bug report.

optparse 1.4.0

  • parse_args now supports convert_hyphens_to_underscores argument which converts any hyphens to underscores when returning the list of options
  • Now includes the convenience function parse_args2 which wraps parse_args with positional_arguments set to TRUE and convert_hyphens_to_underscores set to TRUE.

optparse 1.3.1

  • optparse should no longer give any warnings when options(warnPartialMatchArgs=TRUE). Thanks Rich FitzJohn for patch.
  • print_help no longer throws an error if we have a default argument of length zero. Thanks Benjamin Tyner for bug report.

optparse 1.3.0

  • OptionParser and OptionParserOption S4 classes are now exported. Thanks Peter Humburg for patch.

optparse 1.2.0

  • Parameter positional_arguments of function parse_args now accepts one or two numeric values that denote the minimum and maximum number of supported positional arguments. Thanks Kirill Müller for patch.
  • If interactive() == TRUE then parse_args will no longer quit(status=1) after printing a help message but will instead throw an error. optparse will continue to quit(status=1) after printing a help message for non-interactive Rscripts unless print_help_and_exit == FALSE.

optparse 1.1.0

  • In make_option argument type="numeric" automatically cast to double. Previously users might have received an error passing negative numbers if they accidentally specified "numeric" instead of "double".
  • Bug fixed in printing usage message for options with default value of NA and a help string including "%default". Thanks Stefan Seemayer for bug report and patch.

optparse 1.0.2

  • Project website moved to https://github.com/trevorld/optparse
  • We now replace all occurrences of %prog in usage message (including description and epilogue). Previously we would only replace one occurrence and didn't make replacements in description and epilogue.
  • Fix bug in parse_args when we have options with no short flag and positional_arguments=TRUE. Thanks Miroslav Posta for bug report.

optparse 1.0.0

  • Added description and epilogue arguments to OptionParser to allow users to add more information to generated help messages
  • Slightly alters the generated usage string to match more closely what the Python module does
  • No longer exports S4 classes that represent OptionParser and OptionParserOption
  • Now requires package getopt (>= 1.19) which has also been moved to Imports field from Depends field in DESCRIPTION
  • Now also Suggests stringr package in DESCRIPTION

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("optparse")

1.6.4 by Trevor L Davis, 3 months ago


https://github.com/trevorld/r-optparse


Report a bug at https://github.com/trevorld/r-optparse/issues


Browse source code at https://github.com/cran/optparse


Authors: Trevor L Davis [aut, cre] , Allen Day [ctb] (Some documentation and examples ported from the getopt package.) , Python Software Foundation [ctb] (Some documentation from the optparse Python module.) , Steve Lianoglou [ctb] , Jim Nikelski [ctb] , Kirill Müller [ctb] , Peter Humburg [ctb] , Rich FitzJohn [ctb] , Gyu Jin Choi [ctb]


Documentation:   PDF Manual  


GPL (>= 2) license


Imports methods, getopt

Suggests covr, knitr, stringr, testthat


Imported by PACVr, PhenotypeSimulator, REPTILE, SafeQuant, fmriqa, ngstk, plinkQC.

Suggested by TexExamRandomizer, enveomics.R.


See at CRAN