| Title: | Command Line Optional and Positional Argument Parser |
|---|---|
| Description: | A command line parser to be used with 'Rscript' to write "#!" shebang scripts that gracefully accept positional and optional arguments and automatically generate usage. |
| Authors: | Trevor L. Davis [aut, cre] (ORCID: <https://orcid.org/0000-0001-6341-4639>), Allen Day [ctb] (Some documentation and examples ported from the getopt package.), Python Software Foundation [ctb] (Some documentation from the argparse Python module.), Paul Newell [ctb] |
| Maintainer: | Trevor L. Davis <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 2.3.3 |
| Built: | 2026-10-31 18:50:59 UTC |
| Source: | https://github.com/cran/argparse |
An ArgumentGroup R6 object wraps a Python argparse argument group.
Objects of this class are returned by the add_argument_group() method
of Parser objects.
Argument groups are used to group related arguments together in the
help message.
Group -> ArgumentGroup
ArgumentGroup$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.
ArgumentGroup$add_mutually_exclusive_group(required = FALSE)
requiredIf TRUE then exactly one of the arguments in the
group must be present on the command line.
A MutuallyExclusiveGroup object.
https://docs.python.org/3/library/argparse.html#argument-groups
ArgumentParser(), Parser, MutuallyExclusiveGroup
if (argparse:::detects_python()) { parser <- ArgumentParser(prog = "PROG", add_help = FALSE) group <- parser$add_argument_group("group") group$add_argument("--foo", help = "foo help") group$add_argument("bar", help = "bar help") parser$print_help() }if (argparse:::detects_python()) { parser <- ArgumentParser(prog = "PROG", add_help = FALSE) group <- parser$add_argument_group("group") group$add_argument("--foo", help = "foo help") group$add_argument("bar", help = "bar help") parser$print_help() }
ArgumentParser() creates a parser object that acts as
a wrapper to Python's argparse module
ArgumentParser(..., python_cmd = NULL)ArgumentParser(..., python_cmd = NULL)
... |
Arguments cleaned and passed to Pythons |
python_cmd |
Python executable for |
ArgumentParser() returns a Parser R6 object which contains
an add_argument() function to add arguments to the parser,
a parse_args() function to parse command line arguments into
a list, a print_help() and a print_usage() function to print
usage information. See code examples, package vignette,
and corresponding python module for more information on how to use it.
Python's argparse library, which this package is based on,
is described here: https://docs.python.org/3/library/argparse.html
Parser, ArgumentGroup, MutuallyExclusiveGroup, and
Subparsers for
documentation of the R6 objects returned by ArgumentParser() and its
methods.
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_help() } if (run_example) { # 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)) }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_help() } if (run_example) { # 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)) }
A MutuallyExclusiveGroup R6 object wraps a Python argparse mutually
exclusive group.
Objects of this class are returned by the add_mutually_exclusive_group()
method of Parser and ArgumentGroup objects.
Only one of the arguments added to a mutually exclusive group may be
present on the command line.
Unlike an ArgumentGroup, a mutually exclusive group can't contain nested groups (Python 3.14 and later no longer allow this).
Group -> MutuallyExclusiveGroup
https://docs.python.org/3/library/argparse.html#mutual-exclusion
ArgumentParser(), Parser, ArgumentGroup
if (argparse:::detects_python()) { 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") }if (argparse:::detects_python()) { 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") }
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.
Parser$parse_args()Parse command line arguments.
Parser$parse_args(args = commandArgs(TRUE))
argsA character vector of command line arguments.
A named list of argument values.
Parser$parse_intermixed_args()Parse command line arguments allowing optional and positional arguments to be intermixed.
Parser$parse_intermixed_args(args = commandArgs(TRUE))
argsA character vector of command line arguments.
A named list of argument values.
Parser$parse_known_args()Parse command line arguments without raising an error for unrecognized arguments.
Parser$parse_known_args(args = commandArgs(TRUE))
argsA character vector of command line arguments.
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.
Parser$parse_known_intermixed_args(args = commandArgs(TRUE))
argsA character vector of command line arguments.
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.
Parser$format_help()
A string containing the help message.
Parser$format_usage()Format the usage message.
Parser$format_usage()
A string containing the usage message.
Parser$print_help()Print the help message.
Parser$print_help()
NULL (invisibly).
Parser$print_usage()Print the usage message.
Parser$print_usage()
NULL (invisibly).
Parser$get_default()Not currently supported. Always raises an error.
Parser$get_default(...)
...Ignored.
Parser$set_defaults()Set parser-level default values for arguments.
Parser$set_defaults(...)
...Named arguments cleaned and passed to Python's
set_defaults() method.
NULL (invisibly).
Parser$add_argument()Define how a single command line argument should be parsed.
Parser$add_argument(...)
...Arguments cleaned and passed to Python's
add_argument() method. The type argument may be one of
"logical", "integer", "double", "numeric", or
"character".
NULL (invisibly).
Parser$add_argument_group()Create an argument group. Arguments added to the group are displayed together in the help message.
Parser$add_argument_group(...)
...Arguments cleaned and passed to Python's
add_argument_group() method such as title and description.
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.
Parser$add_mutually_exclusive_group(required = FALSE)
requiredIf TRUE then exactly one of the arguments in the
group must be present on the command line.
A MutuallyExclusiveGroup object.
Parser$add_subparsers()Add support for sub-commands.
Parser$add_subparsers(...)
...Arguments cleaned and passed to Python's
add_subparsers() method such as title, description, help,
dest, and required.
A Subparsers object.
Parser$new()Create a new Parser object.
Users should not call this directly but instead use ArgumentParser().
Parser$new(python_code, name)
python_codeAn internal object that accumulates the Python code used to build the parser.
nameName of the Python variable holding this object.
Python's argparse documentation:
https://docs.python.org/3/library/argparse.html
ArgumentParser(), ArgumentGroup, MutuallyExclusiveGroup,
Subparsers
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() } if (run_example) { args <- parser$parse_args(c("--sum", "1", "2", "3")) print(args) } if (run_example) { args <- parser$parse_known_args(c("--sum", "1", "2", "--unknown")) print(args) }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() } if (run_example) { args <- parser$parse_args(c("--sum", "1", "2", "3")) print(args) } if (run_example) { args <- parser$parse_known_args(c("--sum", "1", "2", "--unknown")) print(args) }
A Subparsers R6 object wraps the Python argparse object used to add
sub-commands.
Objects of this class are returned by the add_subparsers() method of
Parser objects.
Subparsers$new()Create a new Subparsers object.
Users should not call this directly but instead use the add_subparsers() method of a Parser object.
Subparsers$new(python_code, name)
python_codeAn internal object that accumulates the Python code used to build the parser.
nameName of the Python variable holding this object.
Subparsers$add_parser()Add a sub-command parser.
Subparsers$add_parser(...)
...Arguments cleaned and passed to Python's add_parser()
method. The first argument is usually the name of the
sub-command. Accepts the same arguments as ArgumentParser()
as well as help and aliases.
A Parser object.
https://docs.python.org/3/library/argparse.html#sub-commands
if (argparse:::detects_python()) { parser <- ArgumentParser(prog = "PROG") parser$add_argument("--foo", action = "store_true", help = "foo help") subparsers <- parser$add_subparsers(help = "sub-command help") parser_a <- subparsers$add_parser("a", help = "a help") parser_a$add_argument("bar", type = "integer", help = "bar help") parser$parse_args(c("a", "12")) }if (argparse:::detects_python()) { parser <- ArgumentParser(prog = "PROG") parser$add_argument("--foo", action = "store_true", help = "foo help") subparsers <- parser$add_subparsers(help = "sub-command help") parser_a <- subparsers$add_parser("a", help = "a help") parser_a$add_argument("bar", type = "integer", help = "bar help") parser$parse_args(c("a", "12")) }