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 callbtw_tool_files_read_text_file()and if the path is a directory we callbtw_tool_files_list_files()on the path.btw_this("./data")lists the files indata/.btw_this("./R/load_data.R")reads the source of theR/load_data.Rfile.
"{pkgName}"or"@pkg pkgName"
A package name wrapped in braces, or using the@pkgcommand. 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}")orbtw_this("@pkg dplyr")includes dplyr's introductory vignette.btw_this("{btw}")returns only the package help index (becausebtwdoesn't have an intro vignette, yet).
"?help_topic"or"@help topic"
When the string starts with?or@help, btw searches R's help topics usingbtw_tool_docs_help_page(). Supports multiple formats:btw_this("?dplyr::across")orbtw_this("@help dplyr::across")btw_this("@help dplyr across")- space-separated formatbtw_this("@help across")- searches all packages
"@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"."@url {{url}}"
Include the contents of a web page at the specified URL as markdown, e.g."@url https://cran.r-project.org/doc/FAQ/R-FAQ.html". Requires the chromote package to be installed."@git status","@git diff","@git log"
Git commands for viewing repository status, diffs, and commit history. Requires gert package and a git repository.btw_this("@git status")- show working directory statusbtw_this("@git status staged")- show only staged filesbtw_this("@git diff")- show unstaged changesbtw_this("@git diff HEAD")- show staged changesbtw_this("@git log")- show recent commits (default 10)btw_this("@git log main 20")- show 20 commits from main branch
"@issue #number"or"@pr #number"
Fetch a GitHub issue or pull request. Automatically detects the current repository, or you can specifyowner/repo#numberorowner/repo number. Requires gh package and GitHub authentication.btw_this("@issue #65")- issue from current repobtw_this("@pr posit-dev/btw#64")- PR from specific repobtw_this("@issue tidyverse/dplyr 1234")- space-separated format
"@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 usingrstudioapi::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, usingsessioninfo::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 enablerlang::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())See also
Other btw_this() methods:
btw_this(),
btw_this.data.frame(),
btw_this.environment()
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] "```"
if (FALSE) { # \dontrun{
btw_this("@pkg dplyr")
btw_this("@help mutate")
btw_this("@git status")
btw_this("@issue #65")
} # }