arg_reconcile: Reconcile an argument list to any function signature.

Description

Adapt an argument list to a function excluding arguments that will not be recognized by it, redundant arguments, and un-named arguments.

Usage

arg_reconcile(
  fun,
  ...,
  .args = alist(),
  .docall = FALSE,
  .include = c(),
  .exclude = c(),
  .remap = list(),
  .warn = TRUE,
  .error = "default",
  .finish = identity
)

Arguments

fun

A function to which an argument list needs to be adapted. Use the unquoted name of the function. If it's in a different package then the fully qualified unquoted name (e.g. utils::read.table)

...

An arbitrary list of named arguments (unnamed ones will be ignored). Arguments in .args are overridden by arguments of the same name (if any) in ...

.args

A list or alist of named arguments, to be merged with .... Arguments in .args are overridden by arguments of the same name (if any) in ...

.docall

If set to TRUE will not only clean up the arguments but also execute fun with those arguments (FALSE by default) and return the results

.include

Whitelist. If not empty, only arguments named here will be permitted, and only if they satisfy the conditions implied by the other arguments. Evaluated before .remap.

.exclude

Blacklist. If not empty, arguments named here will be removed even if they satisfy the conditions implied by the other arguments. Evaluated before .remap.

.remap

An optional named character vector or named list of character values for standardizing arguments that play the same role but have different names in different functions. Evaluated after .exclude and .include.

.warn

Whether to issue a warning message (default) when invalid arguments need to be discarded.

.error

If specified, should be the object to return in the event of error. This object will have the error as its error attribute. If not specified an ordinary error is thrown with an added hint on the documentation to read for troubleshooting. Ignored if .docall is FALSE. The point of doing this is fault-tolerance-- if this function is part of a lengthy process where you want to document an error but keep going, you can set .error to some object of a compatible type. That object will be returned in the event of error and will have as its "error" attribute the error object.

.finish

A function to run on the result before returning it. Ignored if .docall is FALSE.

Value

Either a named list or the result of calling fun with the supplied arguments