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

command-line optional argument parser
https://github.com/trevorld/r-optparse

Last synced: 8 days ago
JSON representation

command-line optional argument parser

• Host: GitHub
• URL: https://github.com/trevorld/r-optparse
• Owner: trevorld
• License: gpl-2.0
• Created: 2013-05-04T01:09:16.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2024-05-17T17:58:59.000Z (11 months ago)
• Last Synced: 2025-04-03T16:12:05.236Z (17 days ago)
• Language: R
• Homepage: http://trevorldavis.com/R/optparse/dev/
• Size: 207 KB
• Stars: 150
• Watchers: 5
• Forks: 11
• Open Issues: 6
• Metadata Files:
  • Readme: README.Rrst
  • Contributing: CONTRIBUTING
  • License: COPYING

Awesome Lists containing this project

• jimsghstars - trevorld/r-optparse - command-line optional argument parser (R)

README

        
optparse: Command line optional argument parser

===============================================

.. image:: https://www.r-pkg.org/badges/version/optparse

    :target: https://cran.r-project.org/package=optparse

    :alt: CRAN Status Badge

.. image:: https://github.com/trevorld/r-optparse/workflows/R-CMD-check/badge.svg

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

    :alt: R-CMD-check

.. image:: https://codecov.io/github/trevorld/r-optparse/branch/master/graph/badge.svg

    :target: https://app.codecov.io/github/trevorld/r-optparse?branch=master

    :alt: Coverage Status

.. image:: https://cranlogs.r-pkg.org/badges/optparse

    :target: https://cran.r-project.org/package=optparse

    :alt: RStudio CRAN mirror downloads

.. raw:: html

   

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:

.. code:: r

    install.packages("optparse")

To install the development version use the following command:

.. code:: r

    install.packages("remotes")

    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``:

.. code:: bash

    sudo apt install pandoc

examples

--------

A simple example:

.. {r 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"))

.. ..

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:

.. {r list_example}

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

.. ..

``optparse`` automatically creates a help option:

.. code:: r

    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:

.. {r positional_example}

    parse_args(parser, args = c("-vc", "25", "75", "22"), positional_arguments = TRUE)

.. ..

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

.. {r parse_args2}

    parse_args2(parser, args = c("-vc", "25", "75", "22"))

.. ..