Skip to contents

Character strings in btw_this() are used as shortcuts to many underlying methods. btw_this() detects specific formats in the input string to determine which method to call, or by default it will try to evaluate the character string as R code and return the appropriate object description.

btw_this() knows about the following special character string formats:

  • "./path"
    Any string starting with ./ is treated as a relative path. If the path is a file, we call btw_tool_files_read_text_file() and if the path is a directory we call btw_tool_files_list_files() on the path.

    • btw_this("./data") lists the files in data/.

    • btw_this("./R/load_data.R") reads the source of the R/load_data.R file.

  • "{pkgName}"
    A package name wrapped in braces. Returns the list of help topics (btw_tool_docs_package_help_topics()) and, if it exists, the introductory vignette for the package (btw_tool_docs_vignette()).

    • btw_this("{dplyr}") includes dplyr's introductory vignette.

    • btw_this("{btw}") returns only the package help index (because btw doesn't have an intro vignette, yet).

  • "?help_topic"
    When the string starts with ?, btw searches R's help topics using btw_tool_docs_help_page().

    • btw_this("?dplyr::across") includes the reference page for dplyr::across.

  • "@news {{package_name}} {{search_term}}"
    Include the release notes (NEWS) from the latest package release, e.g. "@news dplyr", or that match a search term, e.g. "@news dplyr join_by".

  • "@current_file" or "@current_selection"
    When used in RStudio or Positron, or anywhere else that the rstudioapi is supported, btw("@current_file") includes the contents of the file currently open in the editor using rstudioapi::getSourceEditorContext().

  • "@clipboard"
    Includes the contents currently stored in your clipboard.

  • "@platform_info"
    Includes information about the current platform, such as the R version, operating system, IDE or UI being used, as well as language, locale, timezone and current date.

  • "@attached_packages", "@loaded_packages", "@installed_packages"
    Includes information about the attached, loaded, or installed packages in your R session, using sessioninfo::package_info().

  • "@last_error"
    Includes the message from the last error that occurred in your session. To reliably capture the last error, you need to enable rlang::global_entrace() in your session.

  • "@last_value"
    Includes the .Last.value, i.e. the result of the last expression evaluated in your R console.

Usage

# S3 method for class 'character'
btw_this(x, ..., caller_env = parent.frame())

Arguments

x

A character string

...

Ignored.

caller_env

The caller environment.

Value

A character vector of lines describing the object.

Examples

btw_this("?btw::btw_this")
#>  [1] "## `help(package = \"btw\", \"btw_this\")`"                                                                
#>  [2] ""                                                                                                          
#>  [3] "### Describe something for use by an LLM"                                                                  
#>  [4] ""                                                                                                          
#>  [5] "#### Description"                                                                                          
#>  [6] ""                                                                                                          
#>  [7] "A generic function used to describe an object for use by LLM."                                             
#>  [8] ""                                                                                                          
#>  [9] "#### Usage"                                                                                                
#> [10] ""                                                                                                          
#> [11] "``` R"                                                                                                     
#> [12] "btw_this(x, ...)"                                                                                          
#> [13] "```"                                                                                                       
#> [14] ""                                                                                                          
#> [15] "#### Arguments"                                                                                            
#> [16] ""                                                                                                          
#> [17] "|  |  |"                                                                                                   
#> [18] "|----|----|"                                                                                               
#> [19] "| `x` | The thing to describe. |"                                                                          
#> [20] "| `...` | Additional arguments passed down to underlying methods. Unused arguments are silently ignored. |"
#> [21] ""                                                                                                          
#> [22] "#### Value"                                                                                                
#> [23] ""                                                                                                          
#> [24] "A character vector of lines describing the object."                                                        
#> [25] ""                                                                                                          
#> [26] "#### See Also"                                                                                             
#> [27] ""                                                                                                          
#> [28] "Other `btw_this()` methods: `btw_this.character()`,"                                                       
#> [29] "`btw_this.data.frame()`, `btw_this.environment()`"                                                         
#> [30] ""                                                                                                          
#> [31] "#### Examples"                                                                                             
#> [32] ""                                                                                                          
#> [33] "``` R"                                                                                                     
#> [34] "btw_this(mtcars) # describe the mtcars dataset"                                                            
#> [35] "btw_this(dplyr::mutate) # include function source"                                                         
#> [36] "## Not run: "                                                                                              
#> [37] "btw_this(\"{dplyr}\") # include dplyr's intro vignette"                                                    
#> [38] "btw_this(\"./\") # list files in the current working directory"                                            
#> [39] ""                                                                                                          
#> [40] "## End(Not run)"                                                                                           
#> [41] "```"