# Condition Trapping with AnalysisPageServer

In R "conditions" are messages, warnings and errors. `AnalysisPageServer` contains an API, completely independent of its other components, to trap all of these and be able to examine the call stacks.

First let's make some functions so that we'll have non-trivial call stacks.

    e2 <- function(...)  stop(...)
    e1 <- function(...)  e2(...)

    w2 <- function(...)  warning(...)
    w1 <- function(...)  w2(...)

    m2 <- function(...)  message(...)
    m1 <- function(...)  m2(...)

To use this functionality wrap your code in a call to `tryKeepConditions()`, which returns an object of class class `"AnalysisPageValueWithConditions"`. Despite the name this is completely independent of the rest of `AnalysisPageServer`. We'll build two such objects, one without an error and one with

    library(AnalysisPageServer)
    vwc <- tryKeepConditions({
      m1("first message")
      m1("second message")
      w1("a warning")
      42
    })
    vwcErr <- tryKeepConditions({
      w1("a warning before the error")
      e1("this is a bad error")
      42
    })

All of the functions to access these types of objects begin with `vwc.`.

Check if your expression resulted in an error, and, if not, see what the value was (`NULL` if it did result in an error):

    vwc.is.error(vwc)

    ## [1] FALSE

    vwc.is.error(vwcErr)

    ## [1] TRUE

    vwc.value(vwc)

    ## [1] 42

    vwc.value(vwcErr)

    ## NULL

To inspect the three types of conditions there are a family of functions called `vwc.TYPE(s).condition(s)()`, `vwc.TYPE(s)()` and `vwc.TYPE(s).traceback(s)()` where `TYPE` is `message`, `warning` or `error`. The `(s)` is present in the function names for messages and warnings since there can be more than one, but absent for errors, since there can be only one.

`vwc.TYPE(s).condition(s)()` returns the condition object, or, for messages and warnings, a list of all the condition objects:

    vwc.messages.conditions(vwc)

    ## [[1]]
    ## <simpleMessage in message(...): first message
    ## >
    ##
    ## [[2]]
    ## <simpleMessage in message(...): second message
    ## >

    vwc.messages.conditions(vwcErr)

    ## list()

    vwc.warnings.conditions(vwc)

    ## [[1]]
    ## <simpleWarning in w2(...): a warning>

    vwc.warnings.conditions(vwcErr)

    ## [[1]]
    ## <simpleWarning in w2(...): a warning before the error>

    vwc.error.condition(vwc)

    ## NULL

    vwc.error.condition(vwcErr)

    ## <simpleError in e2(...): this is a bad error>

`vwc.TYPE(s)` returns the condition messages as strings or character vectors:

    vwc.messages(vwc)

    ## [1] "first message\n"  "second message\n"

    vwc.messages(vwcErr)

    ## character(0)

    vwc.warnings(vwc)

    ## [1] "a warning"

    vwc.warnings(vwcErr)

    ## [1] "a warning before the error"

    vwc.error(vwcErr)

    ## [1] "this is a bad error"

(`vwc.error(vwc)` would throw a (new) error if the expression did not result in an error, so we don't call it here.)

Finally, `vwc.TYPE(s).traceback(s)()` return tracebacks as character vectors. Note that the "real" tracebacks can be extracted from the condition objects as returned by `vwc.TYPE(s).conditions(s)()`, but these functions return something suitable for showing to an end user.

(Since this vignette was rendered with `knitr` the call stacks are fairly complicated, but if you run it in an R session you would just see the top few levels.)

    vwc.messages.tracebacks(vwc)

    ## [[1]]
    ##  [1] "19: message(...) at <text>#7"
    ##  [2] "18: m2(...) at <text>#8"
    ##  [3] "17: m1(\"first message\") at <text>#3"
    ##  [4] "16: eval(expr, envir, enclos)"
    ##  [5] "15: eval(expr, envir, enclos)"
    ##  [6] "14: withVisible(eval(expr, envir, enclos))"
    ##  [7] "13: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, "
    ##  [8] "12: evaluate(code, envir = env, new_device = FALSE, keep_warning = !isFALSE(options$warning), "
    ##  [9] "11: in_dir(input_dir(), evaluate(code, envir = env, new_device = FALSE, "
    ## [10] "10: block_exec(params)"
    ## [11] "9: call_block(x)"
    ## [12] "8: process_group.block(group)"
    ## [13] "7: process_group(group)"
    ## [14] "6: process_file(text, output)"
    ## [15] "5: knit(input, text = text, envir = envir, encoding = encoding, "
    ## [16] "4: knit2html(..., force_v1 = TRUE)"
    ## [17] "3: (if (grepl(\"\\\\.[Rr]md$\", file)) knit2html_v1 else if (grepl(\"\\\\.[Rr]rst$\", "
    ## [18] "2: engine$weave(file, quiet = quiet, encoding = enc)"
    ## [19] "1: tools::buildVignettes(dir = \".\", tangle = TRUE)"
    ##
    ## [[2]]
    ##  [1] "19: message(...) at <text>#7"
    ##  [2] "18: m2(...) at <text>#8"
    ##  [3] "17: m1(\"second message\") at <text>#4"
    ##  [4] "16: eval(expr, envir, enclos)"
    ##  [5] "15: eval(expr, envir, enclos)"
    ##  [6] "14: withVisible(eval(expr, envir, enclos))"
    ##  [7] "13: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, "
    ##  [8] "12: evaluate(code, envir = env, new_device = FALSE, keep_warning = !isFALSE(options$warning), "
    ##  [9] "11: in_dir(input_dir(), evaluate(code, envir = env, new_device = FALSE, "
    ## [10] "10: block_exec(params)"
    ## [11] "9: call_block(x)"
    ## [12] "8: process_group.block(group)"
    ## [13] "7: process_group(group)"
    ## [14] "6: process_file(text, output)"
    ## [15] "5: knit(input, text = text, envir = envir, encoding = encoding, "
    ## [16] "4: knit2html(..., force_v1 = TRUE)"
    ## [17] "3: (if (grepl(\"\\\\.[Rr]md$\", file)) knit2html_v1 else if (grepl(\"\\\\.[Rr]rst$\", "
    ## [18] "2: engine$weave(file, quiet = quiet, encoding = enc)"
    ## [19] "1: tools::buildVignettes(dir = \".\", tangle = TRUE)"

    vwc.messages.tracebacks(vwcErr)

    ## list()

    vwc.warnings.tracebacks(vwc)

    ## [[1]]
    ##  [1] "19: warning(...) at <text>#4"
    ##  [2] "18: w2(...) at <text>#5"
    ##  [3] "17: w1(\"a warning\") at <text>#5"
    ##  [4] "16: eval(expr, envir, enclos)"
    ##  [5] "15: eval(expr, envir, enclos)"
    ##  [6] "14: withVisible(eval(expr, envir, enclos))"
    ##  [7] "13: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, "
    ##  [8] "12: evaluate(code, envir = env, new_device = FALSE, keep_warning = !isFALSE(options$warning), "
    ##  [9] "11: in_dir(input_dir(), evaluate(code, envir = env, new_device = FALSE, "
    ## [10] "10: block_exec(params)"
    ## [11] "9: call_block(x)"
    ## [12] "8: process_group.block(group)"
    ## [13] "7: process_group(group)"
    ## [14] "6: process_file(text, output)"
    ## [15] "5: knit(input, text = text, envir = envir, encoding = encoding, "
    ## [16] "4: knit2html(..., force_v1 = TRUE)"
    ## [17] "3: (if (grepl(\"\\\\.[Rr]md$\", file)) knit2html_v1 else if (grepl(\"\\\\.[Rr]rst$\", "
    ## [18] "2: engine$weave(file, quiet = quiet, encoding = enc)"
    ## [19] "1: tools::buildVignettes(dir = \".\", tangle = TRUE)"

    vwc.warnings.tracebacks(vwcErr)

    ## [[1]]
    ##  [1] "19: warning(...) at <text>#4"
    ##  [2] "18: w2(...) at <text>#5"
    ##  [3] "17: w1(\"a warning before the error\") at <text>#9"
    ##  [4] "16: eval(expr, envir, enclos)"
    ##  [5] "15: eval(expr, envir, enclos)"
    ##  [6] "14: withVisible(eval(expr, envir, enclos))"
    ##  [7] "13: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, "
    ##  [8] "12: evaluate(code, envir = env, new_device = FALSE, keep_warning = !isFALSE(options$warning), "
    ##  [9] "11: in_dir(input_dir(), evaluate(code, envir = env, new_device = FALSE, "
    ## [10] "10: block_exec(params)"
    ## [11] "9: call_block(x)"
    ## [12] "8: process_group.block(group)"
    ## [13] "7: process_group(group)"
    ## [14] "6: process_file(text, output)"
    ## [15] "5: knit(input, text = text, envir = envir, encoding = encoding, "
    ## [16] "4: knit2html(..., force_v1 = TRUE)"
    ## [17] "3: (if (grepl(\"\\\\.[Rr]md$\", file)) knit2html_v1 else if (grepl(\"\\\\.[Rr]rst$\", "
    ## [18] "2: engine$weave(file, quiet = quiet, encoding = enc)"
    ## [19] "1: tools::buildVignettes(dir = \".\", tangle = TRUE)"

    vwc.error.traceback(vwc)

    ## NULL

    vwc.error.traceback(vwcErr)

    ##  [1] "19: stop(...) at <text>#1"
    ##  [2] "18: e2(...) at <text>#2"
    ##  [3] "17: e1(\"this is a bad error\") at <text>#10"
    ##  [4] "16: eval(expr, envir, enclos)"
    ##  [5] "15: eval(expr, envir, enclos)"
    ##  [6] "14: withVisible(eval(expr, envir, enclos))"
    ##  [7] "13: evaluate_call(expr, parsed$src[[i]], envir = envir, enclos = enclos, "
    ##  [8] "12: evaluate(code, envir = env, new_device = FALSE, keep_warning = !isFALSE(options$warning), "
    ##  [9] "11: in_dir(input_dir(), evaluate(code, envir = env, new_device = FALSE, "
    ## [10] "10: block_exec(params)"
    ## [11] "9: call_block(x)"
    ## [12] "8: process_group.block(group)"
    ## [13] "7: process_group(group)"
    ## [14] "6: process_file(text, output)"
    ## [15] "5: knit(input, text = text, envir = envir, encoding = encoding, "
    ## [16] "4: knit2html(..., force_v1 = TRUE)"
    ## [17] "3: (if (grepl(\"\\\\.[Rr]md$\", file)) knit2html_v1 else if (grepl(\"\\\\.[Rr]rst$\", "
    ## [18] "2: engine$weave(file, quiet = quiet, encoding = enc)"
    ## [19] "1: tools::buildVignettes(dir = \".\", tangle = TRUE)"

# SessionInfo

    sessionInfo()

    ## R version 3.3.2 (2016-10-31)
    ## Platform: x86_64-w64-mingw32/x64 (64-bit)
    ## Running under: Windows Server 2012 R2 x64 (build 9600)
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.1252
    ## [3] LC_MONETARY=English_United States.1252
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.1252
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] ggplot2_2.2.0            knitr_1.15.1
    ## [3] AnalysisPageServer_1.8.1
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] graph_1.52.0        Rcpp_0.12.8         magrittr_1.5
    ##  [4] BiocGenerics_0.20.0 munsell_0.4.3       colorspace_1.3-1
    ##  [7] rjson_0.2.15        stringr_1.1.0       highr_0.6
    ## [10] plyr_1.8.4          tools_3.3.2         parallel_3.3.2
    ## [13] grid_3.3.2          Biobase_2.34.0      gtable_0.2.0
    ## [16] log4r_0.2           lazyeval_0.2.0      assertthat_0.1
    ## [19] tibble_1.2          reshape2_1.4.2      evaluate_0.10
    ## [22] labeling_0.3        stringi_1.1.2       scales_0.4.1
    ## [25] stats4_3.3.2        markdown_0.7.7