package options

Description Usage Arguments Path-like identifiers Author(s) References See Also Examples

Sets generic option inside an option container created via initializeOptionContainer or any of its subcontainers.

setAnywhereOption(id, value,
  where = tryCatch(devtools::as.package(".")$package, error = function(cond) {
      stop("Invalid default value for `where`") }), fail_value = NULL,
  force = FALSE, gap = TRUE, must_exist = FALSE, reactive = FALSE,
  return_status = TRUE, strict = c(0, 1, 2), typed = FALSE, ...)

`id`	Signature argument. Object containing path-like ID information.
`value`	Signature argument. Object containing value information.
`where`	Signature argument. Object containing information about the location of the option container that is to be used. Typically, this either corresponds to the name/ID of a package/package project or an instance of a custom class for which suitable methods in the context of managing options are defined (see other methods of this package that have signature arguments `id` or `where`).
`fail_value`	`ANY`. Value that is returned if assignment failed and `return_status = FALSE`.
`force`	`logical`. `TRUE`: when `dirname(id)` points to a leaf instead of a branch (i.e. `dirname(id)` is not an `environment`), overwrite it to turn it into a branch and vice versa when `id` points to a branch that is to be transformed into a leaf; `FALSE`: either return with `fail_value` or signal condition depending on value of `strict`.
`gap`	`logical`. `TRUE`: when `dirname(id)` points to a non-existing parent branch or if there are any missing branches in the nested structure, then auto-create all missing branches; `FALSE`: either return with `fail_value` or throw a condition in such cases (depending on `strict`);
`must_exist`	`logical`. `TRUE`: `id` pointing to a non-existing option object either results in return value `fail_value` or signal a condition depending on `strict`; `FALSE`: option object that `id` points to is set.
`reactive`	`logical`. `TRUE`: set reactive option object via `setShinyReactive`. `FALSE`: set regular/non-reactive option object value. Note that if `value` inherits from `ReactiveExpression` (which it does if `reactiveExpression` or wrappers around this function are used), `reactive` is automatically set to `TRUE`.
`return_status`	`logical`. `TRUE`: return status (`TRUE` for successful assignment, `FALSE` for failed assignment); `FALSE`: return actual assignment value (`value`) or `fail_value`.
`strict`	`logical`. Controls what happens when `id` points to a non-existing option object: 0: ignore and return `FALSE` to signal that the assignment process was not successful or `fail_value` depending on the value of `return_status` 1: ignore and with warning and return `FALSE` 2: ignore and with error
`typed`	`logical`. `TRUE`: create an implicitly typed option object; `FALSE`: create a regular option object.
`Further`	arguments to be passed along to subsequent functions. In particular: `setNested` and any function that it calls and that take `...`

Values for id are expected to be of structure a/b/c/.../z, i.e. path-like identifiers using a slash as separator. The identifier is transformed to a$b$c$...$z and then in turn to a valid get or assign expression (i.e. something similar to getOptionContainer(...)$a$b$c$...$z and getOptionContainer(...)$a$b$c$...$z <- value). Of course, "atomic" paths (e.g. only a) are also valid.

Janko Thyson janko.thyson@gmail.com

http://github.com/Rappster/optionr

setAnywhereOption-char-any-char-method, getAnywhereOption, existsAnywhereOption, rmAnywhereOption

## Not run: 

##------------------------------------------------------------------------------
## Basics //
##------------------------------------------------------------------------------

container <- initializeOptionContainer(overwrite = TRUE)

## Simple name/ID //
setAnywhereOption(id = "test", value = TRUE)
getAnywhereOption(id = "test")

## Path-like name/ID //
setAnywhereOption(id = "test", value = new.env())
## --> note that `test` is overwritten and thus transformed from a "leaf"
## to a "branch" component (i.e. an environment)
getAnywhereOption(id = "test")
ls(getAnywhereOption(id = "test"))

setAnywhereOption(id = "test/a", value = TRUE)
ls(getAnywhereOption(id = "test"))
getAnywhereOption(id = "test/a")

## Must exist //
setAnywhereOption(id = "test/b", value = TRUE, must_exist = TRUE)
try(setAnywhereOption(id = "test/b", value = TRUE, must_exist = TRUE, strict = 2))

## Typed //
setAnywhereOption(id = "test/c", value = "hello world!", typed = TRUE)
setAnywhereOption(id = "test/c", value = 1:3)
## --> wrong class, but `strict = 0` --> disregarded without warning or error
getAnywhereOption(id = "test/c")
## --> still `hello world!` because `value = 1:3` had wrong class

setAnywhereOption(id = "test/c", value = "hello world!", typed = TRUE, strict = 1)
try(setAnywhereOption(id = "test/c", value = 1:3))
## --> warning and no assignment
getAnywhereOption(id = "test/c")
## --> still `hello world!`

setAnywhereOption(id = "test/c", value = "hello world!", typed = TRUE, strict = 2)
try(setAnywhereOption(id = "test/c", value = 1:3))
## --> error
getAnywhereOption(id = "test/c")
## --> still `hello world!`

setAnywhereOption(id = "test/a", value = "something else")
## --> correct class --> value changed 
getAnywhereOption(id = "test/a")
  
##------------------------------------------------------------------------------
## Numerical names/IDs //
##------------------------------------------------------------------------------

container <- initializeOptionContainer(overwrite = TRUE)
setAnywhereOption(id = "20140101", value = TRUE)
ls(container, all.names = TRUE)
getAnywhereOption(id = "20140101")

##------------------------------------------------------------------------------
## Branch gaps //
##------------------------------------------------------------------------------
  
container <- initializeOptionContainer(overwrite = TRUE)
setAnywhereOption(id = "a/b/c/d", value = TRUE)
try(setAnywhereOption(id = "a/b/c/d", value = TRUE, strict = 2))
## --> branch gap: branches a, b and c do not exist yet

## Closing the gap //
setAnywhereOption(id = "a/b/c/d", value = TRUE)

## Inspect //
ls(container)
getAnywhereOption(id = "a")
getAnywhereOption(id = "a/b")
getAnywhereOption(id = "a/b/c")
getAnywhereOption(id = "a/b/c/d")

##------------------------------------------------------------------------------
## Forcing leafs to branches //
##------------------------------------------------------------------------------
  
container <- initializeOptionContainer(overwrite = TRUE)
setAnywhereOption(id = "a", value = "hello world!")
setAnywhereOption(id = "a/b", value = 10)
try(setAnywhereOption(id = "a/b", value = 10, strict = 2))
## --> starting branch `a` is not an environment 
getAnywhereOption(id = "a")

## Forcing leaf into a branch //
setAnywhereOption(id = "a/b", value = 10, force = TRUE)
getAnywhereOption(id = "a")
getAnywhereOption(id = "a/b")

##------------------------------------------------------------------------------
## Different `where` //
##------------------------------------------------------------------------------

where <- "test"
container <- initializeOptionContainer(id = where, overwrite = TRUE)
setAnywhereOption(id = "a/b/c", value = 10, where = where)
getAnywhereOption(id = "a/b/c", where = where)
identical(getOptionContainer(where), container)
exists("a", container)

where <- structure(list(id = "test"), class = "OptionContext.Test")
container <- initializeOptionContainer(id = where, overwrite = TRUE)
setAnywhereOption(id = "a/b/c", value = 10, where = where)
getAnywhereOption(id = "a/b/c", where = where)
identical(getOptionContainer(where), container)
exists("a", container)

##------------------------------------------------------------------------------
## Reactive options: simple name/ID //
##------------------------------------------------------------------------------

container <- initializeOptionContainer(overwrite = TRUE)  
setAnywhereOption(id = "x_1", value = TRUE, reactive = TRUE)
setAnywhereOption(
  id = "x_2", 
  value = reactiveOption(!getAnywhereOption(id = "x_1"))
)
## `x_2` should always be the opposite of `x_1`
## Note that you can ommit `reactive = TRUE` when `value = reactiveOption(...)`

getAnywhereOption(id = "x_1")
getAnywhereOption(id = "x_2")

## Changing via options //
setAnywhereOption(id = "x_1", value = FALSE)
getAnywhereOption(id = "x_1")
getAnywhereOption(id = "x_2")

## When changed manually //
container <- getOptionContainer()
container$x_1 <- TRUE
container$x_1
container$x_2

## Trying to change bound variable //
setAnywhereOption(id = "x_2", value = TRUE)
getAnywhereOption(id = "x_2")
## --> has no effect; warning and error behavior can be specified via `strict`

##------------------------------------------------------------------------------
## Reactive options: path-like name/ID //
##------------------------------------------------------------------------------

container <- initializeOptionContainer(overwrite = TRUE)
setAnywhereOption(id = "a/test", value = TRUE, reactive = TRUE)
setAnywhereOption(id = "b/test", 
  value = reactiveOption(!getAnywhereOption(id = "a/test"))
)

getAnywhereOption(id = "a/test")  
getAnywhereOption(id = "b/test")
setAnywhereOption(id = "a/test", value = FALSE)
getAnywhereOption(id = "a/test")
getAnywhereOption(id = "b/test")
  

## End(Not run)