From b47da84bc00b7dbf6bc8484b6c83600f60a3db23 Mon Sep 17 00:00:00 2001 From: mpadge Date: Fri, 23 Jun 2023 16:16:20 +0200 Subject: [PATCH] improve readme desc of trace_lists to close #19 --- README.Rmd | 12 +++++++---- README.md | 61 +++++++++++++++++++++++++++++------------------------- 2 files changed, 41 insertions(+), 32 deletions(-) diff --git a/README.Rmd b/README.Rmd index c029adc..c72f42d 100644 --- a/README.Rmd +++ b/README.Rmd @@ -181,9 +181,10 @@ 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 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`. +`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 @@ -205,7 +206,10 @@ 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`. +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`. ## Example #3 - Tracing a Package diff --git a/README.md b/README.md index ef342b5..ee7050b 100644 --- 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 ## > - ## 1 0 f nqOLeYdi x integ… nume… integer - ## 2 0 f nqOLeYdi y double nume… double - ## 3 0 f nqOLeYdi z NULL NULL NULL - ## 4 0 f nqOLeYdi ... NULL NULL NULL - ## 5 0 f nqOLeYdi a chara… char… character - ## 6 0 f nqOLeYdi b list list list - ## 7 0 f nqOLeYdi f langu… call language + ## 1 0 f uDgEbied x integ… nume… integer + ## 2 0 f uDgEbied y double nume… double + ## 3 0 f uDgEbied z NULL NULL NULL + ## 4 0 f uDgEbied ... NULL NULL NULL + ## 5 0 f uDgEbied a chara… char… character + ## 6 0 f uDgEbied b list list list + ## 7 0 f uDgEbied f langu… call language ## # ℹ 4 more variables: length , formal , uneval >, ## # eval > @@ -142,7 +142,7 @@ unevaluated and evaluated forms of parameters: ## ## $f ## a ~ b - ## + ## Unevaluated parameters are generally converted to equivalent character expressions. @@ -191,9 +191,10 @@ 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 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`. +`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 @@ -213,20 +214,24 @@ list structures: ## # A tibble: 9 × 12 ## trace_number fn_name fn_call_hash par_name class typeof mode storage_mode ## > - ## 1 0 f HlGYZtMI x integ… nume… integer - ## 2 0 f HlGYZtMI y double nume… double - ## 3 0 f HlGYZtMI z NULL NULL NULL - ## 4 0 f HlGYZtMI ... NULL NULL NULL - ## 5 0 f HlGYZtMI a chara… char… character - ## 6 0 f HlGYZtMI b list list list - ## 7 0 f HlGYZtMI f langu… call language - ## 8 0 f HlGYZtMI b$a double nume… double - ## 9 0 f HlGYZtMI b$b chara… char… character + ## 1 0 f LzZIbYvx x integ… nume… integer + ## 2 0 f LzZIbYvx y double nume… double + ## 3 0 f LzZIbYvx z NULL NULL NULL + ## 4 0 f LzZIbYvx ... NULL NULL NULL + ## 5 0 f LzZIbYvx a chara… char… character + ## 6 0 f LzZIbYvx b list list list + ## 7 0 f LzZIbYvx f langu… call language + ## 8 0 f LzZIbYvx b$a double nume… double + ## 9 0 f LzZIbYvx b$b chara… char… character ## # ℹ 4 more variables: length , formal , uneval >, ## # eval > 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`. +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`. ## Example \#3 - Tracing a Package @@ -250,14 +255,14 @@ structures.) ## # A tibble: 8 × 14 ## trace_number source_file_name fn_name fn_call_hash call_env par_name class ## - ## 1 0 man/re_match.Rd re_match hRCLGQvi pattern - ## 2 0 man/re_match.Rd re_match hRCLGQvi text - ## 3 0 man/re_match.Rd re_match hRCLGQvi perl - ## 4 0 man/re_match.Rd re_match hRCLGQvi ... - ## 5 1 man/re_match.Rd re_match eKAOXftZ pattern - ## 6 1 man/re_match.Rd re_match eKAOXftZ text - ## 7 1 man/re_match.Rd re_match eKAOXftZ perl - ## 8 1 man/re_match.Rd re_match eKAOXftZ ... + ## 1 0 man/re_match.Rd re_match UJfHAIRp pattern + ## 2 0 man/re_match.Rd re_match UJfHAIRp text + ## 3 0 man/re_match.Rd re_match UJfHAIRp perl + ## 4 0 man/re_match.Rd re_match UJfHAIRp ... + ## 5 1 man/re_match.Rd re_match Anyflkea pattern + ## 6 1 man/re_match.Rd re_match Anyflkea text + ## 7 1 man/re_match.Rd re_match Anyflkea perl + ## 8 1 man/re_match.Rd re_match Anyflkea ... ## # ℹ 7 more variables: typeof , mode , storage_mode , ## # length , formal , uneval >, eval >