Example for custom class specification within add_argument

Something that is more commonly used in the python equivalent module argparse is custom input types. In argparser (great package) one has to dig around quite a bit, if one wishes to figure out how to utilize the same capabilities. Currently the process on my part was:

Dig through the source code, and realize that as is used to convert the package
Look through the quite confusing help(as) page, and realize that as calls coerce
Realize that coerce is an S4 and not S3 method, so a simple as.[class] do not suffice
Search Hadley’s advanced R book, because who knows how long it has been since I last used S4 rather than S3 or R6 objects
Finally define a new S4 class and method and test the result.

It could likely be very helpful to change the following parts of the documentation of add_argument

Arguments (type):

Currently:

#' @param type    variable type of the argument (which can be inferred from 
#'                \code{default}); assumed to be \code{character} otherwise

Proposal:

#' @param type    variable type of the argument (which can be inferred 
#'                from \code{default}); assumed to be character otherwise. 
#'                See details for more information

Details:

Currently:

#' This function supports multiple arguments in a vector. To ensure that the
#' argument variable type is set correctly, either specify \code{type} directly
#' or supply \code{default} argument values as a list. Argument names
#' that contain dash \code{-} in the stem are converted to \code{_}.

Proposal:

#' @details
#' This function is vectorized to support multiple arguments. 
#' To ensure that the argument variable type is set correctly, 
#' either specify \code{type} directly or supply \code{default} 
#' argument values as a an unnamed list. Custom types are supported 
#' by defining a new class and S4 method for \code{coerce}, 
#' see the examples section for a step-by-step example.

Notes:

Currently: Empty

Proposal:

#' @note Argument names that contain dash \code{-} in the stem are
#' converted to underscore \code{_} in value.

Examples:

Proposal:

#' @examples
#' p <- arg_parser("A text file modifying program")
#'
#' # Add a positional argument
#' p <- add_argument(p, "input", help="input file")
#'
#' # Add an optional argument
#' p <- add_argument(p, "--output", help="output file", default="output.txt")
#'
#' # Add a flag
#' p <- add_argument(p, "--append", help="append to file", flag=TRUE)
#'
#' # Add multiple arguments together
#' p <- add_argument(p,
#'     c("ref", "--date", "--sort"),
#'     help = c("reference file", "date stamp to use", "sort lines"),
#'     flag = c(FALSE, FALSE, TRUE))
#'
#' # Print the help message
#' print(p)
#'  
#' # Example of custom type, using the example from pythons argparse
#' setClass('perfectSquare')
#' setMethod('coerce', c(from = 'ANY', to = 'perfectSquare'), function(from, to){
#'   from <- as.numeric(from)
#'   if(!all.equal(from, as.integer(from)))
#'     stop(paste0(from, ' is not a perfect integer!'))
#'   sqt <- sqrt(from)
#'   if(sqt != as.integer(sqt))
#'     stop('from is not a perfect integer!')
#'   from
#' })
#' p2 <- arg_parser('A perfect square')
#' p2 <- add_argument(p2, arg = c('--perfect-square'), 
#'                    help = ('A perfect square integer'),
#'                    type = 'perfectSquare')
#' parse_args(p2, c('--perfect-square', 4))
#' parse_args(p2, c('--perfect-square', 5))
#'

These proposals are gathered in the attached R file using standard roxygen2 syntax

Comments (3)