update readme for #19

mpadge · Jun 23, 2023 · 613283e · 613283e
1 parent a27dcc0
commit 613283e
Show file tree

Hide file tree

Showing 4 changed files with 118 additions and 29 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: typetracer
 Title: Trace Function Parameter Types
-Version: 0.2.1.008
+Version: 0.2.1.009
 Authors@R: c(
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-2172-5265")),

diff --git a/README.Rmd b/README.Rmd
@@ -165,12 +165,50 @@ For the function, `r`, above, this simply requires,
 uninject_tracer (f)
 ```
 
+All traces can also be removed with this functions:
+
+```{r}
+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.
 
 
-## Example #2 - Tracing a Package
+## Example #2 - Recursion into lists
+
+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 lists to 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:
+
+```{r}
+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`.
+
+
+## Example #3 - Tracing a Package
 
 This section presents a more complex example tracing all function calls from
 [the `rematch` package](https://github.com/MangoTheCat/rematch), chosen because
@@ -183,6 +221,9 @@ function within the package, so there is no need to explicitly call [the
 `inject_tracer()`
 function](https://mpadge.github.io/typetracer/reference/inject_tracer).
 
+(This function also includes a `trace_lists` parameter, as demonstrated above,
+with a default of `FALSE` to not recurse into tracing list structures.)
+
 ```{r trace-rematch, message = FALSE}
 res <- trace_package ("rematch")
 res
@@ -227,7 +268,7 @@ from the ["testthat" package](https://testthat.r-lib.org). These calling
 environments are useful to discern whether, for example, a call was made with
 an expectation that it should error.
 
-### Example #2(a) - Specifying Functions to Trace
+### Example #3(a) - Specifying Functions to Trace
 
 [The `trace_package()`
 function](https://mpadge.github.io/typetracer/reference/trace_package.html)

diff --git a/README.md b/README.md
@@ -83,13 +83,13 @@ from each function call.
     ## # A tibble: 7 × 12
     ##   trace_number fn_name fn_call_hash par_name class     typeof mode  storage_mode
     ##          <int> <chr>   <chr>        <chr>    <I<list>> <chr>  <chr> <chr>       
-    ## 1            0 f       EMWxFUiu     x        <chr [1]> integ… nume… integer     
-    ## 2            0 f       EMWxFUiu     y        <chr [1]> double nume… double      
-    ## 3            0 f       EMWxFUiu     z        <chr [1]> NULL   NULL  NULL        
-    ## 4            0 f       EMWxFUiu     ...      <chr [1]> NULL   NULL  NULL        
-    ## 5            0 f       EMWxFUiu     a        <chr [1]> chara… char… character   
-    ## 6            0 f       EMWxFUiu     b        <chr [1]> list   list  list        
-    ## 7            0 f       EMWxFUiu     f        <chr [1]> langu… call  language    
+    ## 1            0 f       nqOLeYdi     x        <chr [1]> integ… nume… integer     
+    ## 2            0 f       nqOLeYdi     y        <chr [1]> double nume… double      
+    ## 3            0 f       nqOLeYdi     z        <chr [1]> NULL   NULL  NULL        
+    ## 4            0 f       nqOLeYdi     ...      <chr [1]> NULL   NULL  NULL        
+    ## 5            0 f       nqOLeYdi     a        <chr [1]> chara… char… character   
+    ## 6            0 f       nqOLeYdi     b        <chr [1]> list   list  list        
+    ## 7            0 f       nqOLeYdi     f        <chr [1]> langu… call  language    
     ## # ℹ 4 more variables: length <int>, formal <named list>, uneval <I<list>>,
     ## #   eval <I<list>>
 
@@ -142,7 +142,7 @@ unevaluated and evaluated forms of parameters:
     ## 
     ## $f
     ## a ~ b
-    ## <environment: 0x55de67704208>
+    ## <environment: 0x56302b62b6f0>
 
 Unevaluated parameters are generally converted to equivalent character
 expressions.
@@ -178,12 +178,57 @@ For the function, `r`, above, this simply requires,
 
     ## [1] TRUE
 
+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.
 
-## Example \#2 - Tracing a Package
+## Example \#2 - Recursion into lists
+
+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 lists to 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)
+
+    ## # A tibble: 9 × 12
+    ##   trace_number fn_name fn_call_hash par_name class     typeof mode  storage_mode
+    ##          <int> <chr>   <chr>        <chr>    <I<list>> <chr>  <chr> <chr>       
+    ## 1            0 f       HlGYZtMI     x        <chr [1]> integ… nume… integer     
+    ## 2            0 f       HlGYZtMI     y        <chr [1]> double nume… double      
+    ## 3            0 f       HlGYZtMI     z        <chr [1]> NULL   NULL  NULL        
+    ## 4            0 f       HlGYZtMI     ...      <chr [1]> NULL   NULL  NULL        
+    ## 5            0 f       HlGYZtMI     a        <chr [1]> chara… char… character   
+    ## 6            0 f       HlGYZtMI     b        <chr [1]> list   list  list        
+    ## 7            0 f       HlGYZtMI     f        <chr [1]> langu… call  language    
+    ## 8            0 f       HlGYZtMI     b$a      <chr [1]> double nume… double      
+    ## 9            0 f       HlGYZtMI     b$b      <chr [1]> chara… char… character   
+    ## # ℹ 4 more variables: length <int>, formal <named list>, uneval <I<list>>,
+    ## #   eval <I<list>>
+
+And that result now has 9 rows, or 2 more than the previous example,
+reflecting the two items passed as a `list` to the parameter, `b`.
+
+## Example \#3 - Tracing a Package
 
 This section presents a more complex example tracing all function calls
 from [the `rematch` package](https://github.com/MangoTheCat/rematch),
@@ -195,23 +240,26 @@ automatically injects tracing code into every function within the
 package, so there is no need to explicitly call [the `inject_tracer()`
 function](https://mpadge.github.io/typetracer/reference/inject_tracer).
 
+(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
 
-    ## # A tibble: 8 × 16
-    ##   trace_number trace_source fn_name  fn_call_hash trace_file call_env par_name
-    ##          <int> <chr>        <chr>    <chr>        <chr>      <chr>    <chr>   
-    ## 1            0 examples     re_match ULkYuvZJ     <NA>       <NA>     pattern 
-    ## 2            0 examples     re_match ULkYuvZJ     <NA>       <NA>     text    
-    ## 3            0 examples     re_match ULkYuvZJ     <NA>       <NA>     perl    
-    ## 4            0 examples     re_match ULkYuvZJ     <NA>       <NA>     ...     
-    ## 5            1 examples     re_match oyqnuZhG     <NA>       <NA>     pattern 
-    ## 6            1 examples     re_match oyqnuZhG     <NA>       <NA>     text    
-    ## 7            1 examples     re_match oyqnuZhG     <NA>       <NA>     perl    
-    ## 8            1 examples     re_match oyqnuZhG     <NA>       <NA>     ...     
-    ## # ℹ 9 more variables: class <I<list>>, typeof <chr>, mode <chr>,
-    ## #   storage_mode <chr>, length <int>, formal <named list>, uneval <I<list>>,
-    ## #   eval <I<list>>, source_file_name <chr>
+    ## # A tibble: 8 × 14
+    ##   trace_number source_file_name fn_name  fn_call_hash call_env par_name class   
+    ##          <int> <chr>            <chr>    <chr>        <chr>    <chr>    <I<list>
+    ## 1            0 man/re_match.Rd  re_match hRCLGQvi     <NA>     pattern  <chr>   
+    ## 2            0 man/re_match.Rd  re_match hRCLGQvi     <NA>     text     <chr>   
+    ## 3            0 man/re_match.Rd  re_match hRCLGQvi     <NA>     perl     <chr>   
+    ## 4            0 man/re_match.Rd  re_match hRCLGQvi     <NA>     ...      <chr>   
+    ## 5            1 man/re_match.Rd  re_match eKAOXftZ     <NA>     pattern  <chr>   
+    ## 6            1 man/re_match.Rd  re_match eKAOXftZ     <NA>     text     <chr>   
+    ## 7            1 man/re_match.Rd  re_match eKAOXftZ     <NA>     perl     <chr>   
+    ## 8            1 man/re_match.Rd  re_match eKAOXftZ     <NA>     ...      <chr>   
+    ## # ℹ 7 more variables: typeof <chr>, mode <chr>, storage_mode <chr>,
+    ## #   length <int>, formal <named list>, uneval <I<list>>, eval <I<list>>
 
 The `data.frame` returned by the `trace_package()` function includes
 three more columns than the result directly returned by `load_traces()`.
@@ -226,7 +274,7 @@ calling environment which generated each trace, while
 
     unique (res$source_file_name)
 
-    ## [1] "rd_re_match"
+    ## [1] "man/re_match.Rd"
 
 Although the “call\_env” columns contains no useful information for that
 package, it includes information on the full environment in which each
@@ -257,7 +305,7 @@ package](https://testthat.r-lib.org). These calling environments are
 useful to discern whether, for example, a call was made with an
 expectation that it should error.
 
-### Example \#2(a) - Specifying Functions to Trace
+### Example \#3(a) - Specifying Functions to Trace
 
 [The `trace_package()`
 function](https://mpadge.github.io/typetracer/reference/trace_package.html)

diff --git a/codemeta.json b/codemeta.json
@@ -11,7 +11,7 @@
   "codeRepository": "https://github.com/mpadge/typetracer",
   "issueTracker": "https://github.com/mpadge/typetracer/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.2.1.008",
+  "version": "0.2.1.009",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",