# How boomer works

This vignette summarizes how the internals of boomer work.

## Overview

An important principle of {boomer} is that we don’t modify the body of the function we rig.

    rigged_file_ext <- boomer::rig(tools::file_ext)
    tools::file_ext
    #> function (x)
    #> {
    #>     pos <- regexpr("\\.([[:alnum:]]+)$", x)
    #>     ifelse(pos > -1L, substring(x, pos + 1L), "")
    #> }
    #> <bytecode: 0x11e0aac90>
    #> <environment: namespace:tools>

    rigged_file_ext
    #> function (x)
    #> {
    #>     pos <- regexpr("\\.([[:alnum:]]+)$", x)
    #>     ifelse(pos > -1L, substring(x, pos + 1L), "")
    #> }
    #> <environment: 0x11e18f6e0>

Instead we copy the original function but give it a new environment. This new environment is a child of the original environment, and is populated with shims of the functions called by the original function. We call this environment the mask.

    # the original environment
    environment(tools::file_ext)
    #> <environment: namespace:tools>

    # our new environment
    env <- environment(rigged_file_ext)
    env
    #> <environment: 0x11e18f6e0>

    # its parent
    parent.env(env)
    #> <environment: namespace:tools>

    # its content
    ls(env)
    #>  [1] "("         "+"         "-"         "::"        ":::"       "<-"
    #>  [7] "="         ">"         "ifelse"    "regexpr"   "substring" "{"

`rig_impl()` does this job and is the main function of the package. It calls `wrap()`, the other important function, whose mission is to build verbose shims of functions used in the rigged function. Both are detailed thereafter.

## Individual functions

### `boom()` and `rig()`

`boom()` is a wrapper around `rig_impl()` , it rigs the calling function and runs the call, it also has some hacky code so we can pipe to `boom()` with {magrittr} (The hack is not needed for the base pipe)

### `rig_impl()`

Here’s the diagram of dependencies of `rig_impl()`

    flow::flow_view_deps(boomer:::rig_impl, show_imports = "packages")

`rig_impl()` :

- Creates a new environment (the mask) as a child of the original environment
- Populates it with shims of `::` and `:::` so when we find `pkg::fun` or `pkg:::fun` in the original function we don’t wrap their output and not the `::` or `:::` operator
- Populates it with shims of `<-` and `=` so functions created in the original function, and thus impossible to shim at “rig time”, can be made verbose too.
- Populates it with shims of all other called functions, using `wrap()`
- Creates special variables `..FIRST_CALL..` and `..EVALED_ARGS..` in this environment, `..FIRST_CALL..` is a boolean initiated to `TRUE` and set to `FALSE` once the first wrapper call is triggered, `..EVALED_ARGS..` is a named logical vector that keeps track of which arguments have been evaled.

### `wrap()`

`wrap()` builds verbose wrapper functions.

Its main aim is to print information directly related to the wrapped function (e.g. argument values and execution time).

However it does a couple more things:

- If a wrapper function is the first called it prints information signaling that we are entering the rig function, and it sets up our rigged function so on exit it will print information that we are exiting it. This uses the `..FIRST_CALL..` special variable introduced in above section.
- It checks if the rigged function’s arguments have been evaluated (remember in R arguments are not evaluated unless their values are requested down the line) and prints them when they are. This uses the `..EVALED_ARGS..`` special variable introduced in above section.

### `rig_in_namespace()`

`rig_in_namespace()` calls `rig_impl()` on its inputs but unlike `rig()` we want the rigged functions to be bound in the namespace instead of the original functions.

To do this we unlock the namespace and assigned rigged functions there.

Since `rig_in_namespace()` accepts several functions as arguments, and that they might call each other, we also make sure we include wrapped versions of our rigged functions in all the masks.