R: Debug a Function

debug {base} | R Documentation

## Debug a Function

### Description

Set, unset or query the debugging flag on a function. The `text` and `condition` arguments are the same as those that can be supplied via a call to `browser`. They can be retrieved by the user once the browser has been entered, and provide a mechanism to allow users to identify which breakpoint has been activated.

### Usage

    debug(fun, text = "", condition = NULL, signature = NULL)
    debugonce(fun, text = "", condition = NULL, signature = NULL)
    undebug(fun, signature = NULL)
    isdebugged(fun, signature = NULL)
    debuggingState(on = NULL)

### Arguments

`fun` | any interpreted R function.
`text` | a text string that can be retrieved when the browser is entered.
`condition` | a condition that can be retrieved when the browser is entered.
`signature` | an optional method signature. If specified, the method is debugged, rather than its generic.
`on` | logical; a call to the support function `debuggingState` returns `TRUE` if debugging is globally turned on, `FALSE` otherwise. An argument of one or the other of those values sets the state. If the debugging state is `FALSE`, none of the debugging actions will occur (but explicit `browser` calls in functions will continue to work).

### Details

When a function flagged for debugging is entered, normal execution is suspended and the body of function is executed one statement at a time. A new browser context is initiated for each step (and the previous one destroyed).

At the debug prompt the user can enter commands or R expressions, followed by a newline. The commands are described in the `browser` help topic.

To debug a function which is defined inside another function, single-step though to the end of its definition, and then call `debug` on its name.

If you want to debug a function not starting at the very beginning, use `trace(..., at = *)` or `setBreakpoint`.

Using `debug` is persistent, and unless debugging is turned off the debugger will be entered on every invocation (note that if the function is removed and replaced the debug state is not preserved). Use `debugonce` to enter the debugger only the next time the function is invoked.

To debug an S4 method by explicit signature, use `signature`. When specified, signature indicates the method of `fun` to be debugged. Note that debugging is implemented slightly differently for this case, as it uses the trace machinery, rather than the debugging bit. As such, `text` and `condition` cannot be specified in combination with a non-null `signature`. For methods which implement the `.local` rematching mechanism, the `.local` closure itself is the one that will be ultimately debugged (see `isRematched`).

`isdebugged` returns `TRUE` if a) `signature` is `NULL` and the closure `fun` has been debugged, or b) `signature` is not `NULL`, `fun` is an S4 generic, and the method of `fun` for that signature has been debugged. In all other cases, it returns `FALSE`.

The number of lines printed for the deparsed call when a function is entered for debugging can be limited by setting `options(deparse.max.lines)`.

When debugging is enabled on a byte compiled function then the interpreted version of the function will be used until debugging is disabled.

### Value

`debug` and `undebug` invisibly return `NULL`.

`isdebugged` returns `TRUE` if the function or method is marked for debugging, and `FALSE` otherwise.

### See Also

`debugcall` for conveniently debugging methods, `browser`, `trace`; `traceback` to see the stack after an `Error: ...` message; `recover` for another debugging approach.

### Examples

    ## Not run:
    debug(library)
    library(methods)

    ## End(Not run)
    ## Not run:
    debugonce(sample)
    ## only the first call will be debugged
    sampe(10, 1)
    sample(10, 1)

    ## End(Not run)

[Package base version 3.5.1 Index]