feat: Add 'formatter' argument to 'OptionParser()'

* Add a ``formatter`` argument to ``OptionParser()`` for a function to format the usage message (#30). By default uses the new function ``IndentedHelpFormatter()``. `{optparse}` also provides the new function ``TitledHelpFormatter()``. Thanks Ni Huang for suggestion. closes #30
trevorld · Sep 12, 2021 · dc23055 · dc23055
1 parent f7edc67
commit dc23055
Show file tree

Hide file tree

Showing 14 changed files with 163 additions and 52 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -2,7 +2,7 @@ Encoding: UTF-8
 Package: optparse
 Type: Package
 Title: Command Line Option Parser
-Version: 1.6.6
+Version: 1.7.0-1
 Authors@R: c(person("Trevor L", "Davis", role = c("aut", "cre"), email="trevor.l.davis@gmail.com"),
     person("Allen", "Day", role="ctb", comment="Some documentation and examples ported from the getopt package."),
     person("Python Software Foundation", role="ctb", comment="Some documentation from the optparse Python module."),
@@ -26,9 +26,9 @@ Imports:
     methods,
     getopt (>= 1.20.2)
 Suggests:
-    covr,
     knitr (>= 1.15.19),
     stringr,
     testthat
 VignetteBuilder: knitr
-RoxygenNote: 7.0.2
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.1.1
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,7 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+export(IndentedHelpFormatter)
 export(OptionParser)
 export(OptionParserOption)
+export(TitledHelpFormatter)
 export(add_option)
 export(make_option)
 export(parse_args)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,11 @@
+optparse 1.7.0
+==============
+
+* Add a ``formatter`` argument to ``OptionParser()`` for a function to format the usage message (#30).
+  By default uses the new function ``IndentedHelpFormatter()``.
+  `{optparse}` also provides the new function ``TitledHelpFormatter()``.
+  Thanks Ni Huang for suggestion.
+
 optparse 1.6.6
 ==============
 

diff --git a/R/optparse.R b/R/optparse.R
@@ -41,12 +41,16 @@
 #'     usage statement and options statement
 #' @slot epilogue  Additional text for \code{print_help} to print out after
 #'     the options statement
+#' @slot formatter  A function that \code{print_help} will use to print out after
+#'     the options statement.  Default is [IndentedHelpFormatter()].  This
+#'     package also provides the builtin formatter [TitledHelpFormatter()].
 #' @author Trevor Davis.
 #' @seealso \code{\link{OptionParserOption}}
 #' @import methods
 #' @exportClass OptionParser
 setClass("OptionParser", representation(usage = "character", options = "list",
-                description = "character", epilogue = "character"))
+                description = "character", epilogue = "character",
+                formatter = "function"))
 
 #' Class to hold information about command-line options
 #'
@@ -118,6 +122,10 @@ OptionParserOption <- setClass("OptionParserOption", representation(short_flag =
 #'     usage statement and options statement
 #' @param epilogue  Additional text for \code{print_help} to print out after
 #'     the options statement
+#' @param formatter A function that formats usage text.
+#'                  The function should take only one argument (an `OptionParser()` object).
+#'                  Default is [IndentedHelpFormatter()].
+#'                  The other builtin formatter provided by this package is [TitledHelpFormatter()].
 #' @return An instance of the \code{OptionParser} class.
 #' @author Trevor Davis.
 #'
@@ -129,7 +137,8 @@ OptionParserOption <- setClass("OptionParserOption", representation(short_flag =
 #' @export
 OptionParser <- function(usage = "usage: %prog [options]", option_list = list(), # nolint
                             add_help_option = TRUE, prog = NULL,
-                            description = "", epilogue = "") {
+                            description = "", epilogue = "",
+                            formatter = IndentedHelpFormatter) {
 
     if (is.null(prog)) {
         prog <- get_Rscript_filename()
@@ -150,7 +159,8 @@ OptionParser <- function(usage = "usage: %prog [options]", option_list = list(),
     }
 
     return(new("OptionParser", usage = usage, options = option_list,
-                    description = description, epilogue = epilogue))
+                    description = description, epilogue = epilogue,
+                    formatter = formatter))
 }
 
 #' Functions to enable our OptionParser to recognize specific command line
@@ -326,6 +336,29 @@ add_option <- function(object, opt_str, action = NULL, type = NULL,
 #'     is described here: \url{http://docs.python.org/library/optparse.html}
 #' @export
 print_help <- function(object) {
+    object@formatter(object)
+}
+
+#' Builtin help text formatters
+#'
+#' `IndentedHelpFormatter()` is the default help text formatter.
+#' `TitledHelpFormatter()` is an alternative help text formatter.
+#'
+#' @param object An [OptionParser()] object.
+#' @examples
+#'  parser <- OptionParser(formatter = IndentedHelpFormatter)
+#'  parser <- add_option(parser, "--generator", help = "Generator option")
+#'  parser <- add_option(parser, "--count", help = "Count option")
+#'  print_help(parser)
+#'
+#'  parser <- OptionParser(formatter = TitledHelpFormatter)
+#'  parser <- add_option(parser, "--generator", help = "Generator option")
+#'  parser <- add_option(parser, "--count", help = "Count option")
+#'  print_help(parser)
+#' @return `NULL` invisibly.  As a side effect prints out help text.
+#' @rdname formatter
+#' @export
+IndentedHelpFormatter <- function(object) {
     cat(object@usage, fill = TRUE)
     cat(object@description, fill = TRUE)
     cat("\n")
@@ -356,6 +389,39 @@ print_help <- function(object) {
     return(invisible(NULL))
 }
 
+#' @rdname formatter
+#' @export
+TitledHelpFormatter <- function(object) {
+    usage <- c("Usage\n=====\n", gsub("Usage: ", "", object@usage))
+    cat(usage, fill = TRUE)
+    cat(object@description, fill = TRUE)
+    cat("\n")
+    cat("Options", "=======", sep = "\n")
+
+    options_list <- object@options
+    for (ii in seq_along(options_list)) {
+        option <- options_list[[ii]]
+        if (!is.null(option@long_flag)) {
+            cat(option@long_flag)
+            if (.option_needs_argument(option)) {
+                cat("=", toupper(option@metavar), sep = "")
+            }
+        }
+        if (!is.na(option@short_flag)) {
+            cat(", ")
+            cat(option@short_flag)
+            if (.option_needs_argument(option)) {
+                cat(" ", toupper(option@metavar), sep = "")
+            }
+        }
+        cat("\n\t\t")
+        cat(sub("%default", .as_string(option@default), option@help))
+        cat("\n\n")
+    }
+    cat(object@epilogue, fill = TRUE)
+    return(invisible(NULL))
+}
+
 # Turn default values into a string we can cat, handles NA's and NULL's
 .as_string <- function(default) {
     if (is.null(default)) {

diff --git a/README.Rrst b/README.Rrst
@@ -5,13 +5,9 @@ optparse: Command line optional argument parser
     :target: https://cran.r-project.org/package=optparse
     :alt: CRAN Status Badge
 
-.. image:: https://travis-ci.org/trevorld/r-optparse.svg?branch=master
-    :target: https://travis-ci.org/trevorld/r-optparse
-    :alt: Travis-CI Build Status
-
-.. image:: https://ci.appveyor.com/api/projects/status/github/trevorld/r-optparse?branch=master&svg=true 
-    :target: https://ci.appveyor.com/project/trevorld/r-optparse
-    :alt: AppVeyor Build Status
+.. 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://img.shields.io/codecov/c/github/trevorld/r-optparse/master.svg
     :target: https://codecov.io/github/trevorld/r-optparse?branch=master
@@ -21,7 +17,6 @@ optparse: Command line optional argument parser
     :target: https://cran.r-project.org/package=optparse
     :alt: 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.
@@ -125,12 +120,12 @@ Note by default when ``optparse::parse_args`` sees a ``--help`` flag it will fir
 have richer positional argument support:
 
 .. {r positional_example}
-    parse_args(parser, args = c("-v", "-c25", "75", "22"), positional_arguments = TRUE)
+    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("-v", "-c25", "75", "22"))
+    parse_args2(parser, args = c("-vc", "25", "75", "22"))
 .. ..
diff --git a/README.rst b/README.rst
@@ -5,13 +5,9 @@ optparse: Command line optional argument parser
     :target: https://cran.r-project.org/package=optparse
     :alt: CRAN Status Badge
 
-.. image:: https://travis-ci.org/trevorld/r-optparse.svg?branch=master
-    :target: https://travis-ci.org/trevorld/r-optparse
-    :alt: Travis-CI Build Status
-
-.. image:: https://ci.appveyor.com/api/projects/status/github/trevorld/r-optparse?branch=master&svg=true 
-    :target: https://ci.appveyor.com/project/trevorld/r-optparse
-    :alt: AppVeyor Build Status
+.. 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://img.shields.io/codecov/c/github/trevorld/r-optparse/master.svg
     :target: https://codecov.io/github/trevorld/r-optparse?branch=master
@@ -21,7 +17,6 @@ optparse: Command line optional argument parser
     :target: https://cran.r-project.org/package=optparse
     :alt: 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.
@@ -159,7 +154,7 @@ have richer positional argument support:
 .. sourcecode:: r
 
 
-    parse_args(parser, args = c("-v", "-c25", "75", "22"), positional_arguments = TRUE)
+    parse_args(parser, args = c("-vc", "25", "75", "22"), positional_arguments = TRUE)
 
 
 ::
@@ -172,11 +167,11 @@ have richer positional argument support:
     ## [1] TRUE
     ## 
     ## $options$count
-    ## [1] 5
+    ## [1] 25
     ## 
     ## 
     ## $args
-    ## [1] "-c25" "75"   "22"
+    ## [1] "75" "22"
 
 
 
@@ -186,7 +181,7 @@ The function ``parse_args2`` wraps ``parse_args`` while setting ``positional_arg
 .. sourcecode:: r
 
 
-        parse_args2(parser, args = c("-v", "-c25", "75", "22"))
+        parse_args2(parser, args = c("-vc", "25", "75", "22"))
 
 
 ::
@@ -199,10 +194,10 @@ The function ``parse_args2`` wraps ``parse_args`` while setting ``positional_arg
     ## [1] TRUE
     ## 
     ## $options$count
-    ## [1] 5
+    ## [1] 25
     ## 
     ## 
     ## $args
-    ## [1] "-c25" "75"   "22"
+    ## [1] "75" "22"
 
 
diff --git a/man/OptionParser-class.Rd b/man/OptionParser-class.Rd
diff --git a/man/OptionParser.Rd b/man/OptionParser.Rd
diff --git a/man/add_make_option.Rd b/man/add_make_option.Rd
diff --git a/man/formatter.Rd b/man/formatter.Rd
diff --git a/man/optparse-package.Rd b/man/optparse-package.Rd