knitr::opts_chunk$set (echo = TRUE)
typetracer
is an R package to trace function parameter types. The R language
includes a set of defined
types,
but the language itself is "absurdly
dynamic"[^1], and lacks
any way to specify which types are expected by any expression. The typetracer
package enables code to be traced to extract detailed information on the
properties of parameters passed to R functions. typetracer
can trace
individual functions or entire packages, as demonstrated below.
[^1]: Alexi Turcotte & Jan Vitek (2019), Towards a Type System for R, ICOOOLPS '19: Proceedings of the 14th Workshop on Implementation, Compilation, Optimization of Object-Oriented Languages, Programs and Systems. Article No. 4, Pages 1–5, https://doi.org/10.1145/3340670.3342426
The stable version of the package can be installed with one of the following commands:
# Stable version from CRAN:
install.packages ("typetracer")
# Current development version from r-universe:
install.packages (
"typetracer",
repos = c ("https://mpadge.r-universe.dev", "https://cloud.r-project.org")
)
Alternatively, for those who prefer to use other source code platforms, the package can also be installed by running any one of the following lines:
remotes::install_git ("https://git.sr.ht/~mpadge/dodgr")
remotes::install_git ("https://codeberg.org/UrbanAnalyst/dodgr")
remotes::install_bitbucket ("UrbanAnalyst/dodgr")
remotes::install_gitlab ("UrbanAnalyst/dodgr")
The package can then loaded for use by calling library
:
library (typetracer)
typetracer
works by "injecting" tracing code into the body of a function
using the inject_tracer()
function.
Locally-defined functions can be traced by simply passing the functions
directly to inject_tracer()
. The following example includes four parameters,
including ...
to allow passing of additional and entirely arbitrary parameter
types and values.
f <- function (x, y, z, ...) {
x * x + y * y
}
inject_tracer (f)
After injecting the typetracer
code, calls to the function, f
, will "trace"
each parameter of the function, by capturing both unevaluated and evaluated
representations at the point at which the function is first called. These
values can be accessed with the load_traces
function,
which returns a data.frame
object (in tibble
format) with one row for each parameter from
each function call.
val <- f (
x = 1:2,
y = 3:4 + 0.,
a = "blah",
b = list (a = 1, b = "b"),
f = a ~ b
)
x <- load_traces ()
x
Each row of the result returned by load_traces()
represents one parameter
passed to one function call. Each function call itself represents a single
"trace" as enumerated by the trace_number
column, and also uniquely
identified by an arbitrary function call hash (fn_call_hash
). The remaining
columns of the trace data define the properties of each parameter, p
, as:
par_name
: Name of parameter.class
: List of classes of parameter.typeof
: Result of typeof(p)
.mode
: Result of mode(p)
.storage_mode
: Result of storage.mode(p)
.length
: Result of length(p)
.formal
: Result of formals(f)[["p"]]
, as named list item with defaultuneval
: Parameters as passed to the function call prior to evaluationeval
: Evaluated version of parameter.The results above show that all parameters of the function, f()
, were
successfully traced, including the additional parameters, a
, b
, and f
,
passed as part of the ...
argument. Such additional parameters can be
identified through having a "formal"
entry of NULL
, indicating that they
are not part of the formal arguments to the function.
That result can also be used to demonstrate the difference between the unevaluated and evaluated forms of parameters:
x$uneval [x$par_name %in% c ("b", "f")]
x$eval [x$par_name %in% c ("b", "f")]
Unevaluated parameters are generally converted to equivalent character expressions.
The typeof
, mode
, and storage_mode
columns are similar, yet may hold
distinct information for certain types of parameters. The conditions under
which these values differ are complex, and depend among other things on the
version of R itself. typeof
alone should generally provide sufficient
information, although this list of
differences may provide further insight
into whether the other columns may provide useful additional information.
Traces themselves are saved in the temporary directory of the current R
session, and the load_traces()
function
simply loads all traces created in that session. The function
clear_traces()
removes all traces, so that
load_traces()
will only load new traces produced after that time.
It is important after applying the inject_tracer()
function to
restore the functions back to their original form through calling the obverse
uninject_tracer()
function.
For the function, r
, above, this simply requires,
uninject_tracer (f)
All traces can also be removed with this functions:
clear_traces ()
Because typetracer
modifies the internal code of functions as defined within
a current R session, we strongly recommend restarting your R session after
using typetracer
, to ensure expected function behaviour is restored.
R has extensive support for list structures, notably including all
data.frame
-like objects in which each column is actually a list item.
typetracer
also offers the ability to recurse into the list structures of
individual parameters, to recursively trace the properties of each list item.
To do this, the traces themselves have to be injected with the additional
parameter, trace_lists = TRUE
.
The final call above included an additional parameter passed as a list. The following code re-injects a tracer with the ability to traverse into list structures:
inject_tracer (f, trace_lists = TRUE)
val <- f (
x = 1:2,
y = 3:4 + 0.,
a = "blah",
b = list (a = 1, b = "b"),
f = a ~ b
)
x_lists <- load_traces ()
print (x_lists)
And that result now has r nrow(x_lists)
rows, or
r nrow(x_lists) - nrow(x)
more than the previous example, reflecting the two
items passed as a list
to the parameter, b
. List-parameter items are
identifiable in typetracer output through the "dollar-notation" in the
par_name
field. The final two values in the above table are b$a
and b$b
,
representing the two elements of the list passed as the parameter, b
.
This section presents a more complex example tracing all function calls from
the rematch
package, chosen because
it has less code than almost any other package on CRAN. The following single
line traces function calls in all examples for the nominated package. The
trace_package()
function
automatically injects tracing code into every
function within the package, so there is no need to explicitly call the
inject_tracer()
function.
(This function also includes a trace_lists
parameter, as demonstrated above,
with a default of FALSE
to not recurse into tracing list structures.)
res <- trace_package ("rematch")
res
The data.frame
returned by the trace_package()
function includes three
more columns than the result directly returned by load_traces()
. These
columns identify the sources and calling environments of each function call
being traces. The "call_env" column identifies the calling environment which
generated each trace, while "source_file_name" identifies the file.
unique (res$call_env)
unique (res$source_file_name)
Although the "call_env" columns contains no useful information for that
package, it includes information on the full environment in which each function
was called. These "environments" include such things as tryCatch
calls
expected to generate errors, or the various expect_
functions of the
"testthat" package. The above case of racing an
installed package generally only extracts traces from example code, as
documented in help, or .Rd
, files. These are identified by the "rd_" prefix
on the "source_file_name", with the rematch
package including only one .Rd
file.
The trace_package()
function
also includes an additional parameter, types
, which defaults to c ("examples", "tests")
, so that traces are also by default generated for all
tests included with local source packages (or for packages installed to include
test files). The "source" column for test files identifies the names of each
test, prefixed with "test_".
The other two additional columns of "trace_file" and "call_env" respectively specify the source file and calling environment of each trace. These will generally only retain information from test files, in which case the source file will generally be the file name identified in the "source" column, and "call_env" will specify the environment from which that function call originated. Environments may, for example, include various types of expectation from the "testthat" package. These calling environments are useful to discern whether, for example, a call was made with an expectation that it should error.
The trace_package()
function
also accepts an argument, functions
, specifying which functions from a
package should be traced. For example,
x <- trace_package ("stats", functions = "sd")
# Create an empty list for formal params. "empty" means an empty name or symbol
# object, which can be conveniently constructed with 'substitute()':
formal <- pairlist (
x = substitute (),
na.rm = FALSE
)
types <- c ("integer", "logical")
x <- tibble::tibble (
trace_number = 0L,
trace_source = "examples",
fn_name = "sd",
fn_call_hash = "EzasZOKV",
trace_file = NA_character_,
call_env = NA_character_,
par_name = c ("x", "na.rm"),
class = I (as.list (types)),
typeof = types,
mode = c ("numeric", "logical"),
storage_mode = types,
length = 2:1,
formal = I (as.list (formal)),
uneval = I (list (x = 1:2, na.rm = "NULL")),
eval = I (list (x = 1:2, na.rm = FALSE)),
source = "rd_sd"
)
x
This package extends on concepts previously developed in other R packages, notably including:
typed
package bycontractr
package byPlus work explained in detail in this footnote: