R/dots.R

In lcolladotor/dots: Simplifying function calls

#' Set an advanced argument
#'
#' From the \code{...} argument used in your function, find if a specific 
#' argument was included and extract its value.
#'
#' @param name Name of the advanced argument to look for in \code{...}
#' @param value The default value of the advanged argument. If this advanced 
#' argument is used in several of your functions, we recommend using 
#' \code{getOption('value')} and explaining this option in your package 
#' vignette geared towards experienced users.
#' @param ... Advanced arguments. See \link[methods]{dotsMethods}.
#'
#' @details
#' Note that you can make dots() even more powerful by using \link{getOption}
#' to define \code{value}. This is particularly useful if you use the
#' same advanced argument in several functions.
#'
#' @export
#' @seealso \link[methods]{dotsMethods}
#' @aliases advanced...
#' @author L. Collado-Torres
#'
#'
#' @examples
#'
#' ## Simple example that calculates the max between 'x' and 'y' with a 
#' ## specified minimum value to return.
#'
#' minMax <- function(x, y, ...) {
#'     minValue <- dots('minValue', 0, ...)
#'     res <- max(x, y, minValue)
#'     return(res)
#' }
#' minMax(1:2, 3:4)
#' minMax(1:2, 3:4, minValue = 5)
#' 
#' ## See the function 'last' included in this package.
#' ## It's an example where most users don't need the 'selector' argument
#' ## but the experienced users can find it and use it.
#' last
#
#' ## Examples using this function
#' l <- list(a = 1:10, b = 11:20)
#' last(l)
#' last(l, selector = '[[')
#'
#' 
#' ## A more complicated example is 'recursive_last' where we specifically
#' ## define the 'selector' argument that is the then passed to 'last'
#' recursive_last
#' 
#' ## Example usages of 'recursive_last'
#' l2 <- list(j = 21:30, k = list(a = 1:10, b = 11:20))
#' recursive_last(l2)
#' recursive_last(l2, level = 2L, selector = '[[')
#' recursive_last(l2, level = 3L, selector = '[[')
#' recursive_last(l2, level = 2L, selector = c('[', '[['))
#'
#' ## Arguably these examples are simple, but the idea is that dots()
#' ## can simplify very long function calls where some parameters will be used
#' ## by a minority of the users.
#'

dots <- function(name, value, ...) {
    args <- list(...)
    if(!name %in% names(args)) {
        ## Default value
        return(value)
    } else {
        ## If the argument was defined in the ... part, return it
        return(args[[name]])
    }
}

#' @export
advanced... <- dots