createCrudExpression.default: Create CRUD expression
In rappster/crudr: Interfaces for CRUD operations

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

Default method of createCrudExpression.

## Default S3 method:
createCrudExpression(inst, id = character(), value = NULL,
  name_obj = "inst", name_value = "value", as_name_obj = TRUE,
  as_name_value = FALSE, evaluate = FALSE, sugar = c("[[", "$"),
  in_parent = FALSE, return_conventional = TRUE, strict = 0:3,
  fail_safe = FALSE, use_tree = FALSE, allow_null = FALSE,
  affect_branch = FALSE, ...)

`inst`	`list`. TODO
`id`	`character`. TODO
`value`	`ANY` (`BasicClasses`). Optional assignment value.
`name_obj`	`character`. Name of the actual object in the expression that values are extracted from or assigned to.
`name_value`	`character`. TODO
`as_name_obj`	`logical`. TODO
`as_name_value`	`logical`. TODO
`evaluate`	`logical`. TODO
`sugar`	`character`. Syntactic sugar function to use.
`in_parent`	`logical`. TODO
`return_conventional`	`logical`. Only relevant if `!is.null(value)`. Return conventional return value of assignments via `<-` or more plausible information in typical contexts where this functions might be used. These are: updated object `inst` if `in_parent = FALSE` `NULL` if `in_parent = TRUE` in order to stress the point that an object has been altered in the parent frame
`strict`	`numeric`. Strictness levels: 0: no condition is signaled 1: message is signaled 2: warning is signaled 3: error is signaled
`fail_safe`	`logical`. Wrap with `try`.
`use_tree`	`logical`. Use expression tree as returned by `createCrudExpressionTree`.
`allow_null`	`logical`. Allows `value = NULL`. Useful for deleting values.
`affect_branch`	`logical`. Only relevant when `value = NULL` in which case a value will be deleted. Unless we use `use_tree = TRUE`, the function has no means of distinguishing the provided `id` belongs to a branch or a leaf in the hierarchy. Setting this to `TRUE` will delete the entire branch while `FALSE` will keep the branch with a value of `structure(list(), names = character())`.
`...`	Further arguments to be passed to subsequent functions/methods.

TODO

expression or evaluated CRUD expression if evaluate = TRUE. Exact value also depends on return_conventional (in interaction with value and in_parent)

Janko Thyson janko.thyson@rappster.de

http://github.com/rappster/crudr

createCrudExpression

# Example object ----------------------------------------------------------

inst <- list(a = list(b = list(c = 10)))

# Extract -----------------------------------------------------------------

createCrudExpression(inst, c("a", "b"))

createCrudExpression(inst, c("a", "b"), evaluate = TRUE)
## --> evaluated inside the function

createCrudExpression(inst, c("a", "b"), evaluate = TRUE, in_parent = TRUE)
## --> evaluated in the frame of `inst`

# Assign ------------------------------------------------------------------

createCrudExpression(inst, c("a", "b", "c"), 100)
createCrudExpression(inst, c("a", "b", "c"), 100, evaluate = TRUE)
## --> evaluated inside the function
inst
## --> `inst$a$b$c` still is `10`

createCrudExpression(inst, c("a", "b", "c"), 100, evaluate = TRUE,
  in_parent = TRUE)
## --> evaluated in the frame of `inst`
inst
## --> `inst$a$b$c` is now `100`

# Return values -----------------------------------------------------------

inst <- list(a = list(b = list(c = 10)))

createCrudExpression(inst, c("a", "b", "c"), 100, evaluate = TRUE,
  return_conventional = FALSE)
## --> evaluated inside the function and entire "updated" object `inst`returned
inst
## --> `inst$a$b$c` still is `10`

createCrudExpression(inst, c("a", "b", "c"), 1, evaluate = TRUE,
  in_parent = TRUE, return_conventional = FALSE)
## --> evaluated in the frame of `inst`. In this case, `NULL` is returned
##     in order to stress the point that the actual object being altered
##     has nothing to do with the return value
inst
## --> `inst$a$b$c` is now `1`

# Sugar = $ ---------------------------------------------------------------

## For the sake of completeness the function also allows you to use the
## syntactic sugar `$` instead of `[[`. While this might be usefull in
## certain usage scenarios, it needs to be noted that comes with additional
## computiational costs (see benchmark)

inst <- list(a = list(b = list(c = 10)))
createCrudExpression(inst, c("a", "b"), sugar = "$")
createCrudExpression(inst, c("a", "b"), value = 1, sugar = "$")

library(microbenchmark)
res <- microbenchmark(
  "extract_1" = createCrudExpression(inst, c("a", "b"), sugar = "[["),
  "extract_2" = createCrudExpression(inst, c("a", "b"), sugar = "$"),
  "assign_1" = createCrudExpression(inst, c("a", "b"), 1, sugar = "[["),
  "assign_2" = createCrudExpression(inst, c("a", "b"), 1, sugar = "$")
)
res

# Comparison to plain method ----------------------------------------------

## While `createCrudExpression` offers more features,
## `createCrudExpressionPlain` is substantially faster.

library(microbenchmark)
res <- microbenchmark(
  "extract_1" = createCrudExpression(inst, c("a", "b")),
  "extract_2" = createCrudExpressionPlain(inst, c("a", "b")),
  "assign_1" = createCrudExpression(inst, c("a", "b"), 1),
  "assign_2" = createCrudExpressionPlain(inst, c("a", "b"), 1)
)
res


# Bridging ----------------------------------------------------------------

inst <- list(a = list(b = 1))
createCrudExpression(inst, c("a", "b", "c", "d"), value = 1, evaluate = TRUE,
  return_conventional = FALSE)
createCrudExpression(inst, c("a", "b", "c", "d"), value = 1, evaluate = TRUE,
  return_conventional = FALSE, strict = 1)
try(
  createCrudExpression(inst, c("a", "b", "c", "d"), value = 1, evaluate = TRUE,
  return_conventional = FALSE, strict = 2)
)
try(
  createCrudExpression(inst, c("a", "b", "c", "d"), value = 1, evaluate = TRUE,
  return_conventional = FALSE, strict = 3)
)