Command Line Optional and Positional Argument Parser

A command line parser to be used with Rscript to write "#!" shebang scripts that gracefully accept positional and optional arguments and automatically generate usage.


CRAN Status Badge

Travis-CI Build Status

AppVeyor Build Status

Coverage Status

RStudio CRAN mirror downloads

Project Status: Active -- The project has reached a stable, usable state and is being actively developed.

argparse is an R package which provides a command line parser to be used with Rscript to write "#!" shebang scripts that gracefully accept positional and optional arguments and automatically generate usage.

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

To install the development version use the following command:

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

dependencies

The package has a Python dependency. It is easily satisfied if you have Python (version 3.2 or higher) on your PATH. Read the INSTALL file for more information if this doesn't describe you.

Additionally this package depends on the R packages R6, findpython, getopt, and jsonlite.

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

> library("argparse")
> parser <- ArgumentParser(description='Process some integers')
> parser$add_argument('integers', metavar='N', type="integer", nargs='+',
+                    help='an integer for the accumulator')
> parser$add_argument('--sum', dest='accumulate', action='store_const',
+                    const='sum', default='max',
+                    help='sum the integers (default: find the max)')
> parser$print_help()
usage: PROGRAM [-h] [--sum] N [N ...]

Process some integers

positional arguments:
  N           an integer for the accumulator

optional arguments:
  -h, --help  show this help message and exit
  --sum       sum the integers (default: find the max)

Default args for ArgumentParser()$parse_args are commandArgs(TRUE) which is what you'd want for an Rscript but not for interactive use:

> args <- parser$parse_args(c("--sum", "1", "2", "3")) 
> accumulate_fn <- get(args$accumulate)
> print(accumulate_fn(args$integers))
[1] 6

Beginning with version 2.0 argparse also supports argument groups:

> parser = ArgumentParser(prog='PROG', add_help=FALSE)
> group1 = parser$add_argument_group('group1', 'group1 description')
> group1$add_argument('foo', help='foo help')
> group2 = parser$add_argument_group('group2', 'group2 description')
> group2$add_argument('--bar', help='bar help')
> expect_output(parser$print_help(), "group1 description")
> parser$print_help()
usage: PROG [-h] [--bar BAR] foo

optional arguments:
  -h, --help  show this help message and exit

group1:
  group1 description

  foo         foo help

group2:
  group2 description

  --bar BAR   bar help

as well as mutually exclusive groups:

> parser = ArgumentParser(prog='PROG')
> group = parser$add_mutually_exclusive_group()
> group$add_argument('--foo', action='store_true')
> group$add_argument('--bar', action='store_false')
> parser$parse_args('--foo')
$bar
[1] TRUE

$foo
[1] TRUE

> parser$parse_args('--bar')
$bar
[1] FALSE

$foo
[1] FALSE
> parser$parse_args(c('--foo', '--bar'))
Error in .stop(output, "parse error:") : parse error:
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

and even basic support for sub-commands!:

> # create the top-level parser
> parser = ArgumentParser(prog='PROG')
> parser$add_argument('--foo', action='store_true', help='foo help')
> subparsers = parser$add_subparsers(help='sub-command help')

> # create the parser for the "a" command
> parser_a = subparsers$add_parser('a', help='a help')
> parser_a$add_argument('bar', type='integer', help='bar help')

> # create the parser for the "b" command
> parser_b = subparsers$add_parser('b', help='b help')
> parser_b$add_argument('--baz', choices='XYZ', help='baz help')

> # parse some argument lists
> parser$parse_args(c('a', '12'))
$bar
[1] 12

$foo
[1] FALSE

> parser$parse_args(c('--foo', 'b', '--baz', 'Z'))
$baz
[1] "Z"

$foo
[1] TRUE

> parser$print_help()
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}       sub-command help
    a         a help
    b         b help

optional arguments:
  -h, --help  show this help message and exit
  --foo       foo help

> parser_a$print_help()
usage: PROG a [-h] bar

positional arguments:
  bar         bar help

optional arguments:
  -h, --help  show this help message and exit

> parser_b$print_help()
usage: PROG b [-h] [--baz {X,Y,Z}]

optional arguments:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

News

argparse 1.1.1

  • Better support for machines only running Python 2.7.
  • DESCRIPTION makes explicit that it requires version 1.0.0 of proto dependency. Thanks Christophe Poulet for bug report.

argparse 1.1.0

  • Better support for Unicode arguments/options. Thanks Erick Rocha Fonseca for bug report.
  • Fix bug when setting type='integer' in add_argument. Thanks Dominik Mueller for bug report and suggested solution.
  • The package proto has been moved from Depends to Imports in DESCRIPTION. We now use jsonlite package instead of rjson to parse JSON.
  • Better error message when accidentally trying to define a positional argument in ArgumentParser() Suggestion of Alex Reinhart.
  • Other error message output when an parsing error is detected have been tweaked slightly.

argparse 1.0.7

  • Now supports showing program's version with action='version'. Suggestion of Dario Beraldi.

argparse 1.0.6

  • Fix bug when setting required=FALSE in add_argument. Thanks Claire D. McWhite for bug report.

argparse 1.0.4

  • You can now pass in a character vector to the metavar argument of add_argument. Thanks Paul Newell for bug report and a patch.

argparse 1.0.3

  • add_argument now throws a warning recommending using action "store_true" or "store_false" if type set to "logical" and action set to "store". Suggestion of Martí Duran Ferrer
  • You can now explicitly set a NULL default in add_argument.
    Previously one could only implicitly set a NULL default by not setting any default at all. Suggestion of Hyunsoo Kim.

argparse 1.0.2

  • Fixes parsing bug when using a very large argument list. Thanks Taylor Pospisil for bug report.
  • Parse error usage message now prints to standard error. User requested help message quit status is now zero.
    Thanks to PlasmaBinturong for report/request.
  • If Python script fails with error pass on error message to user. Thanks to Martí Duran Ferrer for report/request.

argparse 1.0.1

  • Fix minor bug when running package tests on machines with both old and new versions of Python. Thanks Prof. Brian Ripley for bug report.

argparse 1.0.0

  • Some support for choices argument in parser$add_argument. Thanks Christopher Small for report/request.

  • Some support for formatter_class argument in ArgumentParser. Thanks Costas Bouyioukos for report/request.

  • Package now looks for Python binaries with findpython::find_python_cmd which is a little bit more robust than the previous argparse::find_python_cmd.

  • If interactive() == TRUE then parse_args will no longer quit(status=1) after printing a help message but will instead throw an error. argparse will continue to quit(status=1) after printing a help message for non-interactive Rscripts.

argparse 0.5.3

  • Fix bug in parser$add_argument for case when we specify a default vector instead of scalar. Thanks Martin Diehl for bug report.

  • find_python_cmd will now also look for a python2.7 binary.

  • Website moved to https://github.com/trevorld/argparse

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("argparse")

2.0.0 by Trevor L Davis, 3 months ago


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


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


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


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.) , Paul Newell [ctb]


Documentation:   PDF Manual  


GPL (>= 2) license


Imports R6, findpython, getopt, jsonlite

Suggests knitr, testthat

System requirements: python (>= 3.2)


See at CRAN