importDefaults: Import Global Default Argument Values

Description Usage Arguments Details Value Note Author(s) See Also Examples

Description

Use globally specified defaults, if set, in place of formally specified default argument values. Allows user to specify function defaults different than formally supplied values, e.g. to change poorly performing defaults, or satisfy a different preference.

Usage

1
importDefaults(calling.fun)

Arguments

calling.fun

name of function to act upon

Details

Placed immediately after the function declaration, a call to importDefaults checks the user's environment for globally specified default values for the called function. These defaults can be specified by the user with a call to setDefaults, and will override any default formal parameters, in effect replacing the original defaults with user supplied values instead.

If a function has not been written with importDefaults (most R functions, so far...), it is possible to simply call useDefaults to achieve the same results. As of version 1.1-0, simply calling setDefaults will call useDefaults internally, removing the need to explicitly call. See the related help page.

Any values specified by the user in a in the parent function (that is, the function containing importDefaults) will override the values set in the global default environment.

Value

Used for its side-effects, a call to importDefaults loads all non-NULL default values specified by the user into the current function's environment, effectively changing the default values passed in the parent function call.

importDefaults values, like formally defined defaults in the function definition, take lower precedence than arguments specified by the user in the function call.

An alias to importDefaults, .importDefaults is the actual function added when useDefaults is called on a function. The naming convention is designed to facilitate setting and unsetting, and should NOT be used by the function developer. Please use only importDefaults

Note

It is important to note that when a function implements importDefaults, non-named arguments may be ignored if a global Default has been set (i.e. not NULL).

If this is the case, simply name the arguments in the calling function.

This should also work for functions retrieving formal parameter values from options, as it assigns a value to the parameter in a way that looks like it was passed in the function call. So any check on options would presumably disregard importDefaults values if an argument was passed to the function (what useDefaults does)

Author(s)

Jeffrey A. Ryan

See Also

useDefaults,setDefaults

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
my.fun <- function(x=3)
{
  importDefaults('my.fun')
  x ^ 2
}

my.fun()        #returns 9

setDefaults(my.fun,x=10)
my.fun()        #returns 100
my.fun(x=4)     #returns 16

getDefaults(my.fun)
formals(my.fun)
unsetDefaults(my.fun,confirm=FALSE)
getDefaults(my.fun)

my.fun()        #returns 9

joshuaulrich/Defaults documentation built on May 19, 2019, 8:54 p.m.