Argument parser

A Parser R6 object wraps a Python argparse argument parser. Objects of this class are returned by ArgumentParser() and by the add_parser() method of Subparsers objects.

If a parse error occurs (or help or version information is requested) then in an interactive session an error is raised whereas in a non-interactive session (i.e. a script) a message is printed and R exits.

References

Python's argparse documentation: https://docs.python.org/3/library/argparse.html

See also

ArgumentParser(), ArgumentGroup, MutuallyExclusiveGroup, Subparsers

Methods

Public methods

• Parser$parse_args()

• Parser$parse_intermixed_args()

• Parser$parse_known_args()

• Parser$parse_known_intermixed_args()

• Parser$format_help()

• Parser$format_usage()

• Parser$print_help()

• Parser$print_usage()

• Parser$get_default()

• Parser$set_defaults()

• Parser$add_argument()

• Parser$add_argument_group()

• Parser$add_mutually_exclusive_group()

• Parser$add_subparsers()

• Parser$new()

---

Parser$parse_args()

Parse command line arguments.

Usage

Parser$parse_args(args = commandArgs(TRUE))

Arguments

args

A character vector of command line arguments.

Returns

A named list of argument values.

---

Parser$parse_intermixed_args()

Parse command line arguments allowing optional and positional arguments to be intermixed.

Usage

Parser$parse_intermixed_args(args = commandArgs(TRUE))

Arguments

args

A character vector of command line arguments.

Returns

A named list of argument values.

---

Parser$parse_known_args()

Parse command line arguments without raising an error for unrecognized arguments.

Usage

Parser$parse_known_args(args = commandArgs(TRUE))

Arguments

args

A character vector of command line arguments.

Returns

A list of length two. The first element is a named list of argument values. The second element is a character vector of the remaining unrecognized arguments.

---

Parser$parse_known_intermixed_args()

Parse command line arguments allowing optional and positional arguments to be intermixed and without raising an error for unrecognized arguments.

Usage

Parser$parse_known_intermixed_args(args = commandArgs(TRUE))

Arguments

args

A character vector of command line arguments.

Returns

A list of length two. The first element is a named list of argument values. The second element is a character vector of the remaining unrecognized arguments.

---

Parser$format_help()

Format the help message.

Usage

Parser$format_help()

Returns

A string containing the help message.

---

Parser$format_usage()

Format the usage message.

Usage

Parser$format_usage()

Returns

A string containing the usage message.

---

Parser$print_help()

Print the help message.

Usage

Parser$print_help()

Returns

NULL (invisibly).

---

Parser$print_usage()

Print the usage message.

Usage

Parser$print_usage()

Returns

NULL (invisibly).

---

Parser$get_default()

Not currently supported. Always raises an error.

Usage

Parser$get_default(...)

Arguments

...

Ignored.

---

Parser$set_defaults()

Set parser-level default values for arguments.

Usage

Parser$set_defaults(...)

Arguments

...

Named arguments cleaned and passed to Python's set_defaults() method.

Returns

NULL (invisibly).

---

Parser$add_argument()

Define how a single command line argument should be parsed.

Usage

Parser$add_argument(...)

Arguments

...

Arguments cleaned and passed to Python's add_argument() method. The type argument may be one of "logical", "integer", "double", "numeric", or "character".

Returns

NULL (invisibly).

---

Parser$add_argument_group()

Create an argument group. Arguments added to the group are displayed together in the help message.

Usage

Parser$add_argument_group(...)

Arguments

...

Arguments cleaned and passed to Python's add_argument_group() method such as title and description.

Returns

An ArgumentGroup object.

---

Parser$add_mutually_exclusive_group()

Create a mutually exclusive group. Only one of the arguments added to the group may be present on the command line.

Usage

Parser$add_mutually_exclusive_group(required = FALSE)

Arguments

required

If TRUE then exactly one of the arguments in the group must be present on the command line.

Returns

A MutuallyExclusiveGroup object.

---

Parser$add_subparsers()

Add support for sub-commands.

Usage

Parser$add_subparsers(...)

Arguments

...

Arguments cleaned and passed to Python's add_subparsers() method such as title, description, help, dest, and required.

Returns

A Subparsers object.

---

Parser$new()

Create a new Parser object. Users should not call this directly but instead use ArgumentParser().

Usage

Parser$new(python_code, name)

Arguments

python_code

An internal object that accumulates the Python code used to build the parser.

name

Name of the Python variable holding this object.

Examples

run_example <- argparse:::detects_python()
if (run_example) {
  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_usage()
}
#> usage: PROGRAM [-h] [--sum] N [N ...]
if (run_example) {
  args <- parser$parse_args(c("--sum", "1", "2", "3"))
  print(args)
}
#> $accumulate
#> [1] "sum"
#> 
#> $integers
#> [1] 1 2 3
#> 
if (run_example) {
  args <- parser$parse_known_args(c("--sum", "1", "2", "--unknown"))
  print(args)
}
#> [[1]]
#> [[1]]$integers
#> [1] 1 2
#> 
#> [[1]]$accumulate
#> [1] "sum"
#> 
#> 
#> [[2]]
#> [1] "--unknown"
#>