From 5ad1ee2c7c6230c51c725960f566c4a88223b18d Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 25 Oct 2024 15:54:29 -0700 Subject: [PATCH 01/15] Make `.run` hyperlinks configurable --- R/ansi-hyperlink.R | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/R/ansi-hyperlink.R b/R/ansi-hyperlink.R index 20969172..28fda6b4 100644 --- a/R/ansi-hyperlink.R +++ b/R/ansi-hyperlink.R @@ -193,20 +193,32 @@ make_link_href <- function(txt) { make_link_run <- function(txt) { mch <- re_match(txt, "^\\[(?.*)\\]\\((?.*)\\)$") text <- ifelse(is.na(mch$text), txt, mch$text) - url <- ifelse(is.na(mch$url), txt, mch$url) + code <- ifelse(is.na(mch$url), txt, mch$url) + #browser() sprt <- ansi_hyperlink_types()$run - if (sprt) { - scheme <- if (identical(attr(sprt, "type"), "rstudio")) { - "ide:run" + if (!sprt) { + return(vcapply(text, function(code1) format_inline("{.code {code1}}"))) + } + + custom_fmt <- get_config_chr("hyperlink_run_url_format") + if (is.null(custom_fmt)) { + if (identical(attr(sprt, "type"), "rstudio")) { + fmt_type <- "rstudio" } else { - "x-r-run" + fmt_type <- "standard" } - style_hyperlink(text = text, url = paste0(scheme, ":", url)) - } else { - vcapply(text, function(url1) format_inline("{.code {url1}}")) + fmt_type <- "custom" } + + fmt <- switch( + fmt_type, + custom = custom_fmt, + rstudio = "ide:run:{code}", + standard = "x-r-run:{code}" + ) + style_hyperlink(text = text, url = glue(fmt)) } # -- {.topic} ------------------------------------------------------------- @@ -426,3 +438,16 @@ ansi_hyperlink_types <- function() { ) } } + +get_config_chr <- function(x, default = NULL) { + opt <- getOption(paste0("cli.", tolower(x))) + if (!is.null(opt)) { + stopifnot(is_string(opt)) + return(opt) + } + + env <- Sys.getenv(paste0("R_CLI_", toupper(x)), NA_character_) + if (!is.na(env)) return(env) + + default +} From 69180b8e0753366758b55f1a526cb62f24b776cc Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 31 Oct 2024 19:23:20 -0700 Subject: [PATCH 02/15] Get rid of browser call --- R/ansi-hyperlink.R | 1 - 1 file changed, 1 deletion(-) diff --git a/R/ansi-hyperlink.R b/R/ansi-hyperlink.R index 28fda6b4..078b7daa 100644 --- a/R/ansi-hyperlink.R +++ b/R/ansi-hyperlink.R @@ -195,7 +195,6 @@ make_link_run <- function(txt) { text <- ifelse(is.na(mch$text), txt, mch$text) code <- ifelse(is.na(mch$url), txt, mch$url) - #browser() sprt <- ansi_hyperlink_types()$run if (!sprt) { return(vcapply(text, function(code1) format_inline("{.code {code1}}"))) From 85578b1705a2faa616f46ee2949f4d4e6e1be3af Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 31 Oct 2024 19:24:56 -0700 Subject: [PATCH 03/15] Handle all the x-r-whatever links --- R/ansi-hyperlink.R | 85 ++++++++++++++++------------ R/test.R | 21 +++++++ tests/testthat/test-ansi-hyperlink.R | 2 + 3 files changed, 73 insertions(+), 35 deletions(-) diff --git a/R/ansi-hyperlink.R b/R/ansi-hyperlink.R index 078b7daa..336e56cc 100644 --- a/R/ansi-hyperlink.R +++ b/R/ansi-hyperlink.R @@ -130,19 +130,17 @@ make_link_fun <- function(txt) { if (!any(todo)) return(txt) sprt <- ansi_hyperlink_types()$help - if (sprt) { - scheme <- if (identical(attr(sprt, "type"), "rstudio")) { - "ide:help" - } else { - "x-r-help" - } - - txt[todo] <- style_hyperlink( - text = txt[todo], - url = paste0(scheme, ":", txt[todo]) - ) + if (!sprt) { + return(txt) } + fmt <- get_hyperlink_format("help") + # the format has a placeholder for 'topic' + topic <- txt[todo] + done <- style_hyperlink(text = topic, url = glue(fmt)) + + txt[todo] <- done + txt } @@ -151,21 +149,16 @@ make_link_fun <- function(txt) { make_link_help <- function(txt) { mch <- re_match(txt, "^\\[(?.*)\\]\\((?.*)\\)$") text <- ifelse(is.na(mch$text), txt, mch$text) - url <- ifelse(is.na(mch$url), txt, mch$url) + topic <- ifelse(is.na(mch$url), txt, mch$url) sprt <- ansi_hyperlink_types()$help - if (sprt) { - scheme <- if (identical(attr(sprt, "type"), "rstudio")) { - "ide:help" - } else { - "x-r-help" - } - style_hyperlink(text = text, url = paste0(scheme, ":", url)) - - } else { - url2 <- vcapply(url, function(url1) format_inline("{.fun ?{url1}}")) - ifelse(text == url, url2, paste0(text, " (", url2, ")")) + if (!sprt) { + topic2 <- vcapply(topic, function(x) format_inline("{.fun ?{x}}")) + return(ifelse(text == topic, topic2, paste0(text, " (", topic2, ")"))) } + + fmt <- get_hyperlink_format("help") + style_hyperlink(text = text, url = glue(fmt)) } # -- {.href} -------------------------------------------------------------- @@ -225,21 +218,16 @@ make_link_run <- function(txt) { make_link_topic <- function(txt) { mch <- re_match(txt, "^\\[(?.*)\\]\\((?.*)\\)$") text <- ifelse(is.na(mch$text), txt, mch$text) - url <- ifelse(is.na(mch$url), txt, mch$url) + topic <- ifelse(is.na(mch$url), txt, mch$url) sprt <- ansi_hyperlink_types()$help - if (sprt) { - scheme <- if (identical(attr(sprt, "type"), "rstudio")) { - "ide:help" - } else { - "x-r-help" - } - style_hyperlink(text = text, url = paste0(scheme, ":", url)) - - } else { - url2 <- vcapply(url, function(url1) format_inline("{.code ?{url1}}")) - ifelse(text == url, url2, paste0(text, " (", url2, ")")) + if (!sprt) { + topic2 <- vcapply(topic, function(x) format_inline("{.code ?{x}}")) + return(ifelse(text == topic, topic2, paste0(text, " (", topic2, ")"))) } + + fmt <- get_hyperlink_format("help") + style_hyperlink(text = text, url = glue(fmt)) } # -- {.url} --------------------------------------------------------------- @@ -438,6 +426,33 @@ ansi_hyperlink_types <- function() { } } +get_hyperlink_format <- function(type = c("run", "help", "vignette")) { + type <- match.arg(type) + + key <- glue("hyperlink_{type}_url_format") + sprt <- ansi_hyperlink_types()[[type]] + + custom_fmt <- get_config_chr(key) + if (is.null(custom_fmt)) { + if (identical(attr(sprt, "type"), "rstudio")) { + fmt_type <- "rstudio" + } else { + fmt_type <- "standard" + } + } else { + fmt_type <- "custom" + } + + variable <- c(run = "code", help = "topic", vignette = "vignette") + fmt <- switch( + fmt_type, + custom = custom_fmt, + rstudio = glue("ide:{type}:{{{variable[type]}}}"), + standard = glue("x-r-{type}:{{{variable[type]}}}") + ) + fmt +} + get_config_chr <- function(x, default = NULL) { opt <- getOption(paste0("cli.", tolower(x))) if (!is.null(opt)) { diff --git a/R/test.R b/R/test.R index 3d7c3167..b6c96277 100644 --- a/R/test.R +++ b/R/test.R @@ -112,6 +112,18 @@ test_that_cli <- function(desc, code, cli.hyperlink_help = links, cli.hyperlink_run = links, cli.hyperlink_vignette = links, + cli.hyperlink_run_url_format = NULL, + cli.hyperlink_help_url_format = NULL, + cli.hyperlink_vignette_url_format = NULL, + ) + withr::local_envvar( + R_CLI_HYPERLINKS = NA_character_, + R_CLI_HYPERLINK_RUN = NA_character_, + R_CLI_HYPERLINK_HELP = NA_character_, + R_CLI_HYPERLINK_VIGNETTE = NA_character_, + R_CLI_HYPERLINK_RUN_URL_FORMAT = NA_character_, + R_CLI_HYPERLINK_HELP_URL_FORMAT = NA_character_, + R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT = NA_character_, ) code_ }, c(conf, list(code_ = code))) @@ -131,6 +143,9 @@ local_clean_cli_context <- function(.local_envir = parent.frame()) { cli.hyperlink_run = NULL, cli.hyperlink_help = NULL, cli.hyperlink_vignette = NULL, + cli.hyperlink_run_url_format = NULL, + cli.hyperlink_help_url_format = NULL, + cli.hyperlink_vignette_url_format = NULL, cli.num_colors = NULL, cli.palette = NULL, crayon.enabled = NULL @@ -138,6 +153,12 @@ local_clean_cli_context <- function(.local_envir = parent.frame()) { withr::local_envvar( .local_envir = .local_envir, R_CLI_HYPERLINKS = NA_character_, + R_CLI_HYPERLINK_RUN = NA_character_, + R_CLI_HYPERLINK_HELP = NA_character_, + R_CLI_HYPERLINK_VIGNETTE = NA_character_, + R_CLI_HYPERLINK_RUN_URL_FORMAT = NA_character_, + R_CLI_HYPERLINK_HELP_URL_FORMAT = NA_character_, + R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT = NA_character_, RSTUDIO_CLI_HYPERLINKS = NA_character_, R_CLI_NUM_COLORS = NA_character_, NO_COLOR = NA_character_, diff --git a/tests/testthat/test-ansi-hyperlink.R b/tests/testthat/test-ansi-hyperlink.R index 8b4de70f..b22e809c 100644 --- a/tests/testthat/test-ansi-hyperlink.R +++ b/tests/testthat/test-ansi-hyperlink.R @@ -240,6 +240,7 @@ test_that("iterm file links", { }) test_that("rstudio links", { + local_clean_cli_context() withr::local_envvar( RSTUDIO = "1", RSTUDIO_SESSION_PID = Sys.getpid(), @@ -252,6 +253,7 @@ test_that("rstudio links", { cli.hyperlink_run = TRUE, cli.hyperlink_vignette = TRUE ) + expect_snapshot( cli::cli_text("{.fun pkg::fun}") ) From 4fe8bd629a32aa2115686d0963849763f3ad39c9 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 1 Nov 2024 17:21:39 -0700 Subject: [PATCH 04/15] Whitespace --- tests/testthat/test-ansi-hyperlink.R | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/testthat/test-ansi-hyperlink.R b/tests/testthat/test-ansi-hyperlink.R index b22e809c..c7570204 100644 --- a/tests/testthat/test-ansi-hyperlink.R +++ b/tests/testthat/test-ansi-hyperlink.R @@ -253,7 +253,6 @@ test_that("rstudio links", { cli.hyperlink_run = TRUE, cli.hyperlink_vignette = TRUE ) - expect_snapshot( cli::cli_text("{.fun pkg::fun}") ) From 5ecf351de2eaf6d5f7802e4273e89e02d333dee1 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 1 Nov 2024 17:51:30 -0700 Subject: [PATCH 05/15] Fortify another snapshot test where width can bite you --- tests/testthat/test-progress-types.R | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/testthat/test-progress-types.R b/tests/testthat/test-progress-types.R index 58f2b10c..2df65481 100644 --- a/tests/testthat/test-progress-types.R +++ b/tests/testthat/test-progress-types.R @@ -9,7 +9,8 @@ test_that("iterator", { cli.spinner = NULL, cli.spinner_unicode = NULL, cli.progress_format_iterator = NULL, - cli.progress_format_iterator_nototal= NULL + cli.progress_format_iterator_nototal= NULL, + cli.width = Inf ) fun <- function() { From 74f869a826f37642346658d965d018beb22f740e Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 1 Nov 2024 18:10:07 -0700 Subject: [PATCH 06/15] Oops, level up the `.run` treatment --- R/ansi-hyperlink.R | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/R/ansi-hyperlink.R b/R/ansi-hyperlink.R index 336e56cc..c3610125 100644 --- a/R/ansi-hyperlink.R +++ b/R/ansi-hyperlink.R @@ -193,23 +193,7 @@ make_link_run <- function(txt) { return(vcapply(text, function(code1) format_inline("{.code {code1}}"))) } - custom_fmt <- get_config_chr("hyperlink_run_url_format") - if (is.null(custom_fmt)) { - if (identical(attr(sprt, "type"), "rstudio")) { - fmt_type <- "rstudio" - } else { - fmt_type <- "standard" - } - } else { - fmt_type <- "custom" - } - - fmt <- switch( - fmt_type, - custom = custom_fmt, - rstudio = "ide:run:{code}", - standard = "x-r-run:{code}" - ) + fmt <- get_hyperlink_format("run") style_hyperlink(text = text, url = glue(fmt)) } From 74abfb7db479d60737b55a608a2fd616f14733e7 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 1 Nov 2024 19:18:08 -0700 Subject: [PATCH 07/15] Test get_config_chr() --- tests/testthat/test-ansi-hyperlink.R | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/testthat/test-ansi-hyperlink.R b/tests/testthat/test-ansi-hyperlink.R index c7570204..78c82356 100644 --- a/tests/testthat/test-ansi-hyperlink.R +++ b/tests/testthat/test-ansi-hyperlink.R @@ -371,3 +371,23 @@ test_that("ansi_hyperlink_types", { ) expect_true(ansi_hyperlink_types()[["run"]]) }) + +test_that("get_config_chr() consults option, env var, then its default", { + local_clean_cli_context() + + key <- "hyperlink_TYPE_url_format" + + expect_null(get_config_chr(key)) + + withr::local_envvar(R_CLI_HYPERLINK_TYPE_URL_FORMAT = "envvar") + expect_equal(get_config_chr(key), "envvar") + + withr::local_options(cli.hyperlink_type_url_format = "option") + expect_equal(get_config_chr(key), "option") +}) + +test_that("get_config_chr() errors if option is not NULL or string", { + withr::local_options(cli.something = FALSE) + + expect_error(get_config_chr("something"), "is_string") +}) From 1c2a4ffae8fa1968e34fb190ed08fd01e23152e9 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Mon, 4 Nov 2024 16:16:51 -0800 Subject: [PATCH 08/15] Switch vignette links over --- R/ansi-hyperlink.R | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/R/ansi-hyperlink.R b/R/ansi-hyperlink.R index c3610125..09310de6 100644 --- a/R/ansi-hyperlink.R +++ b/R/ansi-hyperlink.R @@ -228,21 +228,16 @@ make_link_url <- function(txt) { make_link_vignette <- function(txt) { mch <- re_match(txt, "^\\[(?.*)\\]\\((?.*)\\)$") text <- ifelse(is.na(mch$text), txt, mch$text) - url <- ifelse(is.na(mch$url), txt, mch$url) + vignette <- ifelse(is.na(mch$url), txt, mch$url) sprt <- ansi_hyperlink_types()$vignette - if (sprt) { - scheme <- if (identical(attr(sprt, "type"), "rstudio")) { - "ide:vignette" - } else { - "x-r-vignette" - } - style_hyperlink(text = text, url = paste0(scheme, ":", url)) - - } else { - url2 <- vcapply(url, function(url1) format_inline("{.code vignette({url1})}")) - ifelse(text == url, url2, paste0(text, " (", url2, ")")) + if (!sprt) { + vignette2 <- vcapply(vignette, function(x) format_inline("{.code vignette({x})}")) + return(ifelse(text == vignette, vignette2, paste0(text, " (", vignette2, ")"))) } + + fmt <- get_hyperlink_format("vignette") + style_hyperlink(text = text, url = glue(fmt)) } #' Terminal Hyperlinks From 5d1f44c2a526a6d9fd8ca8bbb200e30c4f18ba14 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Mon, 4 Nov 2024 16:17:07 -0800 Subject: [PATCH 09/15] Test that custom formats come through --- tests/testthat/test-ansi-hyperlink.R | 31 ++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/tests/testthat/test-ansi-hyperlink.R b/tests/testthat/test-ansi-hyperlink.R index 78c82356..7569bbb9 100644 --- a/tests/testthat/test-ansi-hyperlink.R +++ b/tests/testthat/test-ansi-hyperlink.R @@ -391,3 +391,34 @@ test_that("get_config_chr() errors if option is not NULL or string", { expect_error(get_config_chr("something"), "is_string") }) + +test_that("get_hyperlink_format() delivers custom format", { + local_clean_cli_context() + + withr::local_options( + cli.hyperlink_run = TRUE, + cli.hyperlink_help = TRUE, + cli.hyperlink_vignette = TRUE + ) + + # env var is consulted after option, so start with env var + withr::local_envvar( + R_CLI_HYPERLINK_RUN_URL_FORMAT = "envvar{code}", + R_CLI_HYPERLINK_HELP_URL_FORMAT = "envvar{topic}", + R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT = "envvar{vignette}" + ) + + expect_equal(get_hyperlink_format("run"), "envvar{code}") + expect_equal(get_hyperlink_format("help"), "envvar{topic}") + expect_equal(get_hyperlink_format("vignette"), "envvar{vignette}") + + withr::local_options( + cli.hyperlink_run_url_format = "option{code}", + cli.hyperlink_help_url_format = "option{topic}", + cli.hyperlink_vignette_url_format = "option{vignette}" + ) + + expect_equal(get_hyperlink_format("run"), "option{code}") + expect_equal(get_hyperlink_format("help"), "option{topic}") + expect_equal(get_hyperlink_format("vignette"), "option{vignette}") +}) From 3818ada888c848a5dc9971170547b3354f4cc0a8 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Wed, 6 Nov 2024 16:13:29 -0800 Subject: [PATCH 10/15] Test custom formats are used --- tests/testthat/_snaps/links.md | 35 ++++++++++++++++++++++++++++++++++ tests/testthat/test-links.R | 35 ++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/tests/testthat/_snaps/links.md b/tests/testthat/_snaps/links.md index 65d8d842..e42524e3 100644 --- a/tests/testthat/_snaps/links.md +++ b/tests/testthat/_snaps/links.md @@ -819,6 +819,13 @@ Message `pkg::func()` +# .fun with custom format [plain-all] + + Code + cli_text("{.fun pkg::func}") + Message + `]8;;aaa-pkg::func-zzzpkg::func]8;;()` + # {.help} [plain-none] Code @@ -857,6 +864,13 @@ Message ]8;;x-r-help:pkg::fun1pkg::fun1]8;;, ]8;;x-r-help:pkg::fun2pkg::fun2]8;;, and ]8;;x-r-help:pkg::fun3pkg::fun3]8;; +# .help with custom format [plain-all] + + Code + cli_text("{.help pkg::fun}") + Message + ]8;;aaa-pkg::fun-zzzpkg::fun]8;; + # {.href} [plain-none] Code @@ -943,6 +957,13 @@ Message ]8;;x-r-run:pkg::fun1()pkg::fun1()]8;;, ]8;;x-r-run:pkg::fun2()pkg::fun2()]8;;, and ]8;;x-r-run:pkg::fun3()pkg::fun3()]8;; +# .run with custom format [plain-all] + + Code + cli_text("{.run devtools::document()}") + Message + ]8;;aaa-devtools::document()-zzzdevtools::document()]8;; + # {.topic} [plain-none] Code @@ -981,6 +1002,13 @@ Message ]8;;x-r-help:pkg::topic1pkg::topic1]8;;, ]8;;x-r-help:pkg::topic2pkg::topic2]8;;, and ]8;;x-r-help:pkg::topic3pkg::topic3]8;; +# .topic with custom format [plain-all] + + Code + cli_text("{.topic pkg::fun}") + Message + ]8;;aaa-pkg::fun-zzzpkg::fun]8;; + # {.url} [plain-none] Code @@ -1092,3 +1120,10 @@ Message ]8;;x-r-vignette:pkg::topic1pkg::topic1]8;;, ]8;;x-r-vignette:pkg::topic2pkg::topic2]8;;, and ]8;;x-r-vignette:pkg::topic3pkg::topic3]8;; +# .vignette with custom format [plain-all] + + Code + cli_text("{.vignette pkgdown::accessibility}") + Message + ]8;;aaa-pkgdown::accessibility-zzzpkgdown::accessibility]8;; + diff --git a/tests/testthat/test-links.R b/tests/testthat/test-links.R index 3b52fb26..aec64cac 100644 --- a/tests/testthat/test-links.R +++ b/tests/testthat/test-links.R @@ -135,6 +135,13 @@ test_that_cli(configs = "plain", links = "all", "turning off help", { }) }) +test_that_cli(configs = "plain", links = "all", ".fun with custom format", { + withr::local_options(cli.hyperlink_help_url_format = "aaa-{topic}-zzz") + expect_snapshot({ + cli_text("{.fun pkg::func}") + }) +}) + # -- {.help} -------------------------------------------------------------- test_that_cli(configs = "plain", links = c("all", "none"), @@ -151,6 +158,13 @@ test_that_cli(configs = "plain", links = c("all", "none"), }) }) +test_that_cli(configs = "plain", links = "all", ".help with custom format", { + withr::local_options(cli.hyperlink_help_url_format = "aaa-{topic}-zzz") + expect_snapshot({ + cli_text("{.help pkg::fun}") + }) +}) + # -- {.href} -------------------------------------------------------------- test_that_cli(configs = "plain", links = c("all", "none"), @@ -188,6 +202,13 @@ test_that_cli(configs = "plain", links = c("all", "none"), }) }) +test_that_cli(configs = "plain", links = "all", ".run with custom format", { + withr::local_options(cli.hyperlink_run_url_format = "aaa-{code}-zzz") + expect_snapshot({ + cli_text("{.run devtools::document()}") + }) +}) + # -- {.topic} ------------------------------------------------------------- test_that_cli(configs = "plain", links = c("all", "none"), @@ -204,6 +225,13 @@ test_that_cli(configs = "plain", links = c("all", "none"), }) }) +test_that_cli(configs = "plain", links = "all", ".topic with custom format", { + withr::local_options(cli.hyperlink_help_url_format = "aaa-{topic}-zzz") + expect_snapshot({ + cli_text("{.topic pkg::fun}") + }) +}) + # -- {.url} --------------------------------------------------------------- test_that_cli(configs = c("plain", "fancy"), links = c("all", "none"), @@ -252,3 +280,10 @@ test_that_cli(configs = "plain", links = c("all", "none"), cli_text("{.vignette {vignettes}}") }) }) + +test_that_cli(configs = "plain", links = "all", ".vignette with custom format", { + withr::local_options(cli.hyperlink_vignette_url_format = "aaa-{vignette}-zzz") + expect_snapshot({ + cli_text("{.vignette pkgdown::accessibility}") + }) +}) From 7646e238a4aba059bec38b58983aa987e32faa2c Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 7 Nov 2024 12:08:53 -0800 Subject: [PATCH 11/15] Document the env vars --- vignettes/cli-config-internal.Rmd | 2 +- vignettes/cli-config-user.Rmd | 52 ++++++++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 2 deletions(-) diff --git a/vignettes/cli-config-internal.Rmd b/vignettes/cli-config-internal.Rmd index ae946001..0b662de3 100644 --- a/vignettes/cli-config-internal.Rmd +++ b/vignettes/cli-config-internal.Rmd @@ -9,7 +9,7 @@ editor_options: wrap: sentence --- -These are environment variables and options are for cli developers, users +These environment variables and options are for cli developers. Users should not rely on them as they may change between cli releases. ## Internal environment variables diff --git a/vignettes/cli-config-user.Rmd b/vignettes/cli-config-user.Rmd index 6dfe66c3..68764d4f 100644 --- a/vignettes/cli-config-user.Rmd +++ b/vignettes/cli-config-user.Rmd @@ -9,7 +9,7 @@ editor_options: wrap: sentence --- -These are environment variables and options that uses may set, to modify +These are environment variables and options that users may set, to modify the behavior of cli. ## User facing environment variables @@ -45,10 +45,60 @@ See [num_ansi_colors()]. ### `R_CLI_HYPERLINKS` +THE "S" AT THE END HERE IS REGRETTABLE, IN TERMS OF CONSISTENCY WITH RELATED CONFIG. + Set to `true`, `TRUE` or `True` to tell cli that the terminal supports ANSI hyperlinks. Set to anything else to assume no hyperlink support. See [style_hyperlink()]. +If the option `cli.hyperlink` is defined, it takes priority over this env var. + +### `R_CLI_HYPERLINK_RUN`, `R_CLI_HYPERLINK_HELP`, `R_CLI_HYPERLINK_VIGNETTE` + +Set to `true`, `TRUE` or `True` to tell cli that the terminal supports +that specific type of specialized hyperlink. +Set to anything else to signal a lack of support. +The `R_CLI_HYPERLINKS` env var indicates that the terminal supports a certain type of hyperlink syntax, whereas these env vars signal that the environment also knows how to execute R code or open documentation. + +Here is the relationship between these env vars and the classes applied via inline markup: + +* `R_CLI_HYPERLINK_RUN` enables links such as: + - `{.run testthat::snapshot_review()}` +* `R_CLI_HYPERLINK_HELP` enables links such as: + - `{.fun stats::lm}` + - `{.topic tibble::tibble_options}` + - `{.help [{.fun lm}](stats::lm)}` +* `R_CLI_HYPERLINK_VIGNETTE` enables links such as: + - `{.vignette tibble::types}` + +If defined, the options `cli.hyperlink_run`, `cli.hyperlink_help` and `cli.hyperlink_vignette` take priority over these env var counterparts. + +### `R_CLI_HYPERLINK_RUN_URL_FORMAT`, `R_CLI_HYPERLINK_HELP_URL_FORMAT`, `R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT` + +cli uses [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that have this syntax: + +``` +OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST +``` + +These env vars relate to the form of the `URI` for these specialized hyperlinks. +These are the current default formats: + +* `x-r-run:{code}` +* `x-r-help:{topic}` +* `x-r-vignette:{vignette}` + +(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. `ide:run:{code}`.) + +These `R_CLI_HYPERLINK_*_URL_FORMAT` env vars allow an environment to provide a custom format to cli. +A format must be a glue-like template with the relevant placeholder in curly braces (`code`, `topic` or `vignette`). +Example of a custom URI format for runnable code in an integrated Positron terminal: + +``` +positron://positron.positron-r/cli?command=x-r-run:{code} +``` + +If defined, the options `cli.hyperlink_run_url_format`, `cli.hyperlink_help_url_format` and `cli.hyperlink_vignette_url_format` take priority over these env var counterparts. ## User facing options From f6eec6afe50bd3759851605d2a5655e419298908 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 7 Nov 2024 12:21:49 -0800 Subject: [PATCH 12/15] Document the options --- vignettes/cli-config-user.Rmd | 48 +++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/vignettes/cli-config-user.Rmd b/vignettes/cli-config-user.Rmd index 68764d4f..9603e727 100644 --- a/vignettes/cli-config-user.Rmd +++ b/vignettes/cli-config-user.Rmd @@ -163,6 +163,54 @@ Set to `true`, `TRUE` or `True` to tell cli that the terminal supports ANSI hyperlinks. Set to anything else to assume no hyperlink support. See [style_hyperlink()]. +The same result can be achieved with the `R_CLI_HYPERLINKS` env var, however this option takes precedence. + +### `cli.hyperlink_run`, `cli.hyperlink_help`, `cli.hyperlink_vignette` + +Set to `true`, `TRUE` or `True` to tell cli that the terminal supports +that specific type of specialized hyperlink. +Set to anything else to signal a lack of support. +The `cli.hyperlink` option indicates that the terminal supports a certain type of hyperlink syntax, whereas these options signal that the environment also knows how to execute R code or open documentation. + +Here is the relationship between these options and the classes applied via inline markup: + +* `cli.hyperlink_run` enables links such as: + - `{.run testthat::snapshot_review()}` +* `cli.hyperlink_help` enables links such as: + - `{.fun stats::lm}` + - `{.topic tibble::tibble_options}` + - `{.help [{.fun lm}](stats::lm)}` +* `cli.hyperlink_vignette` enables links such as: + - `{.vignette tibble::types}` + +The same result can be achieved with the env vars `R_CLI_HYPERLINK_RUN`, `R_CLI_HYPERLINK_HELP`, and `R_CLI_HYPERLINK_VIGNETTE`, however these options take precedence. + +### `cli.hyperlink_run_url_format`, `cli.hyperlink_help_url_format`, `cli.hyperlink_vignette_url_format` + +cli uses [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that have this syntax: + +``` +OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST +``` + +These options relate to the form of the `URI` for these specialized hyperlinks. +These are the current default formats: + +* `x-r-run:{code}` +* `x-r-help:{topic}` +* `x-r-vignette:{vignette}` + +(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. `ide:run:{code}`.) + +These `cli.hyperlink_*_url_format` options allow an environment to provide a custom format to cli. +A format must be a glue-like template with the relevant placeholder in curly braces (`code`, `topic` or `vignette`). +Example of a custom URI format for runnable code in an integrated Positron terminal: + +``` +positron://positron.positron-r/cli?command=x-r-run:{code} +``` + +This configuration can also be communicated via the env vars `R_CLI_HYPERLINK_RUN_URL_FORMAT`, `R_CLI_HYPERLINK_HELP_URL_FORMAT`, and `R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT`, however these options take precedence. ### `cli.ignore_unknown_rstudio_theme` From ef04608e7cdc996b47d738f2886fcac62cb89c95 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Thu, 7 Nov 2024 15:51:41 -0800 Subject: [PATCH 13/15] Create a section for hyperlinks that covers options and env vars --- vignettes/cli-config-user.Rmd | 173 +++++++++++++--------------------- 1 file changed, 63 insertions(+), 110 deletions(-) diff --git a/vignettes/cli-config-user.Rmd b/vignettes/cli-config-user.Rmd index 9603e727..9c52eac5 100644 --- a/vignettes/cli-config-user.Rmd +++ b/vignettes/cli-config-user.Rmd @@ -12,93 +12,101 @@ editor_options: These are environment variables and options that users may set, to modify the behavior of cli. -## User facing environment variables +## Hyperlinks + +cli uses ANSI escape sequences to create hyperlinks. +Specifically, cli creates [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that have this syntax: + +``` +OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST +``` + +Under the hood, [style_hyperlink()] is the helper that forms these links, but it is more common to request them indirectly via inline markup (documented in `help("links")`). ### `R_CLI_HYPERLINK_MODE` Set to `posix` to force generating POSIX compatible ANSI hyperlinks. +This is about the specific operating system command (OSC) and string terminator (ST) used in hyperlinks. + If not set, then RStudio compatible links are generated. This is a temporary crutch until RStudio handles POSIX hyperlinks correctly, and after that it will be removed. -### `NO_COLOR` - -Set to a nonempty value to turn off ANSI colors. -See [num_ansi_colors()]. +### `cli.hyperlink` option and `R_CLI_HYPERLINKS` env var -### `ESS_BACKGROUND_MODE` - -Set this environment variable to `light` or `dark` to indicate dark mode -in Emacs. Once https://github.com/emacs-ess/ESS/pull/1178 is merged, ESS -will set this automatically. +SIDE NOTE: THE "S" AT THE END R_CLI_HYPERLINKS IS REGRETTABLE, IN TERMS OF CONSISTENCY WITH RELATED CONFIG. -### `R_CLI_DYNAMIC` +Set this option or env var to `true`, `TRUE` or `True` to tell cli that the terminal supports ANSI hyperlinks. +Leave this configuration unset (or set to anything else) when there is no hyperlink support. -Set to `true`, `TRUE` or `True` to assume a dynamic terminal, that supports `\r`. -Set to anything else to assume a non-dynamic terminal. -See [is_dynamic_tty()]. +The option `cli.hyperlink` takes precedence over the `R_CLI_HYPERLINKS` env var. -### `R_CLI_NUM_COLORS` +### `cli.hyperlink_*` options and `R_CLI_HYPERLINK_*` env vars -Set to a positive integer to assume a given number of colors. -See [num_ansi_colors()]. +cli supports a few special types of hyperlink that don't just point to, e.g., a webpage or a file. +These specialized hyperlinks cause R-specific actions to happen, such executing a bit of R code or opening specific documentation. -### `R_CLI_HYPERLINKS` +Set the relevant option or env var to `true`, `TRUE`, or `True` to tell cli that the terminal is capable of implementing these specialized behaviours. +Leave this configuration unset (or set to anything else) when there is no support for a specific type of hyperlink. -THE "S" AT THE END HERE IS REGRETTABLE, IN TERMS OF CONSISTENCY WITH RELATED CONFIG. +| Action | Example inline markup | Option | Env var | +|-------------------|---------------------------------------------------------------------------------------|--------------------------|----------------------------| +| Run R code | `{.run testthat::snapshot_review()}` | `cli.hyperlink_run` | `R_CLI_HYPERLINK_RUN` | +| Open a help topic | `{.fun stats::lm}` `{.topic tibble::tibble_options}` `{.help [{.fun lm}](stats::lm)}` | `cli.hyperlink_help` | `R_CLI_HYPERLINK_HELP` | +| Open a vignette | `{.vignette tibble::types}` | `cli.hyperlink_vignette` | `R_CLI_HYPERLINK_VIGNETTE` | -Set to `true`, `TRUE` or `True` to tell cli that the terminal supports -ANSI hyperlinks. -Set to anything else to assume no hyperlink support. -See [style_hyperlink()]. -If the option `cli.hyperlink` is defined, it takes priority over this env var. +In all cases, the option takes priority over the corresponding env var. -### `R_CLI_HYPERLINK_RUN`, `R_CLI_HYPERLINK_HELP`, `R_CLI_HYPERLINK_VIGNETTE` +### `cli.hyperlink_*_url_format` options and `R_CLI_HYPERLINK_*_URL_FORMAT` env vars -Set to `true`, `TRUE` or `True` to tell cli that the terminal supports -that specific type of specialized hyperlink. -Set to anything else to signal a lack of support. -The `R_CLI_HYPERLINKS` env var indicates that the terminal supports a certain type of hyperlink syntax, whereas these env vars signal that the environment also knows how to execute R code or open documentation. +Recall the overall structure of cli's hyperlinks: -Here is the relationship between these env vars and the classes applied via inline markup: +``` +OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST +``` -* `R_CLI_HYPERLINK_RUN` enables links such as: - - `{.run testthat::snapshot_review()}` -* `R_CLI_HYPERLINK_HELP` enables links such as: - - `{.fun stats::lm}` - - `{.topic tibble::tibble_options}` - - `{.help [{.fun lm}](stats::lm)}` -* `R_CLI_HYPERLINK_VIGNETTE` enables links such as: - - `{.vignette tibble::types}` +The `URI` part has a default format for each type of hyperlink, but it is possible to provide a custom format via an option or an env var. +If defined, the option takes priority over the env var. -If defined, the options `cli.hyperlink_run`, `cli.hyperlink_help` and `cli.hyperlink_vignette` take priority over these env var counterparts. +| Action | Default URI format | Customize via option | Customize via env var | +|-------------------|---------------------------|-------------------------------------|---------------------------------------| +| Run R code | `x-r-run:{code}` | `cli.hyperlink_run_url_format` | `R_CLI_HYPERLINK_RUN_URL_FORMAT` | +| Open a help topic | `x-r-help:{topic}` | `cli.hyperlink_help_url_format` | `R_CLI_HYPERLINK_HELP_URL_FORMAT` | +| Open a vignette | `x-r-vignette:{vignette}` | `cli.hyperlink_vignette_url_format` | `R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT` | -### `R_CLI_HYPERLINK_RUN_URL_FORMAT`, `R_CLI_HYPERLINK_HELP_URL_FORMAT`, `R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT` +A format must be a glue-like template with the relevant placeholder in curly braces (`code`, `topic` or `vignette`). -cli uses [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that have this syntax: +Here's an example of a custom URI format for runnable code, which is useful in an integrated Positron terminal: ``` -OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST +positron://positron.positron-r/cli?command=x-r-run:{code} ``` -These env vars relate to the form of the `URI` for these specialized hyperlinks. -These are the current default formats: +(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. `ide:run:{code}`.) -* `x-r-run:{code}` -* `x-r-help:{topic}` -* `x-r-vignette:{vignette}` +## User facing environment variables -(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. `ide:run:{code}`.) +### `NO_COLOR` -These `R_CLI_HYPERLINK_*_URL_FORMAT` env vars allow an environment to provide a custom format to cli. -A format must be a glue-like template with the relevant placeholder in curly braces (`code`, `topic` or `vignette`). -Example of a custom URI format for runnable code in an integrated Positron terminal: +Set to a nonempty value to turn off ANSI colors. +See [num_ansi_colors()]. -``` -positron://positron.positron-r/cli?command=x-r-run:{code} -``` +### `ESS_BACKGROUND_MODE` + +Set this environment variable to `light` or `dark` to indicate dark mode +in Emacs. Once https://github.com/emacs-ess/ESS/pull/1178 is merged, ESS +will set this automatically. + +### `R_CLI_DYNAMIC` + +Set to `true`, `TRUE` or `True` to assume a dynamic terminal, that supports `\r`. +Set to anything else to assume a non-dynamic terminal. +See [is_dynamic_tty()]. + +### `R_CLI_NUM_COLORS` -If defined, the options `cli.hyperlink_run_url_format`, `cli.hyperlink_help_url_format` and `cli.hyperlink_vignette_url_format` take priority over these env var counterparts. +Set to a positive integer to assume a given number of colors. +See [num_ansi_colors()]. ## User facing options @@ -157,61 +165,6 @@ See [is_dynamic_tty()]. Whether the cli status bar should try to hide the cursor on terminals. Set the `FALSE` if the hidden cursor causes issues. -### `cli.hyperlink` - -Set to `true`, `TRUE` or `True` to tell cli that the terminal supports -ANSI hyperlinks. -Set to anything else to assume no hyperlink support. -See [style_hyperlink()]. -The same result can be achieved with the `R_CLI_HYPERLINKS` env var, however this option takes precedence. - -### `cli.hyperlink_run`, `cli.hyperlink_help`, `cli.hyperlink_vignette` - -Set to `true`, `TRUE` or `True` to tell cli that the terminal supports -that specific type of specialized hyperlink. -Set to anything else to signal a lack of support. -The `cli.hyperlink` option indicates that the terminal supports a certain type of hyperlink syntax, whereas these options signal that the environment also knows how to execute R code or open documentation. - -Here is the relationship between these options and the classes applied via inline markup: - -* `cli.hyperlink_run` enables links such as: - - `{.run testthat::snapshot_review()}` -* `cli.hyperlink_help` enables links such as: - - `{.fun stats::lm}` - - `{.topic tibble::tibble_options}` - - `{.help [{.fun lm}](stats::lm)}` -* `cli.hyperlink_vignette` enables links such as: - - `{.vignette tibble::types}` - -The same result can be achieved with the env vars `R_CLI_HYPERLINK_RUN`, `R_CLI_HYPERLINK_HELP`, and `R_CLI_HYPERLINK_VIGNETTE`, however these options take precedence. - -### `cli.hyperlink_run_url_format`, `cli.hyperlink_help_url_format`, `cli.hyperlink_vignette_url_format` - -cli uses [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that have this syntax: - -``` -OSC 8 ; {OPTIONAL PARAMS } ; {URI} ST {LINK TEXT} OSC 8 ; ; ST -``` - -These options relate to the form of the `URI` for these specialized hyperlinks. -These are the current default formats: - -* `x-r-run:{code}` -* `x-r-help:{topic}` -* `x-r-vignette:{vignette}` - -(For backwards compatibility with older versions of RStudio, in some contexts, a legacy format is used, e.g. `ide:run:{code}`.) - -These `cli.hyperlink_*_url_format` options allow an environment to provide a custom format to cli. -A format must be a glue-like template with the relevant placeholder in curly braces (`code`, `topic` or `vignette`). -Example of a custom URI format for runnable code in an integrated Positron terminal: - -``` -positron://positron.positron-r/cli?command=x-r-run:{code} -``` - -This configuration can also be communicated via the env vars `R_CLI_HYPERLINK_RUN_URL_FORMAT`, `R_CLI_HYPERLINK_HELP_URL_FORMAT`, and `R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT`, however these options take precedence. - ### `cli.ignore_unknown_rstudio_theme` Set to `TRUE` to omit a warning for an unknown RStudio theme in From 9909597ee3981b8affc95f8b0071c58bd960b956 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 8 Nov 2024 10:07:41 -0800 Subject: [PATCH 14/15] Remove sidebar to remind me to discuss the "S" --- vignettes/cli-config-user.Rmd | 2 -- 1 file changed, 2 deletions(-) diff --git a/vignettes/cli-config-user.Rmd b/vignettes/cli-config-user.Rmd index 9c52eac5..da65b1e4 100644 --- a/vignettes/cli-config-user.Rmd +++ b/vignettes/cli-config-user.Rmd @@ -34,8 +34,6 @@ after that it will be removed. ### `cli.hyperlink` option and `R_CLI_HYPERLINKS` env var -SIDE NOTE: THE "S" AT THE END R_CLI_HYPERLINKS IS REGRETTABLE, IN TERMS OF CONSISTENCY WITH RELATED CONFIG. - Set this option or env var to `true`, `TRUE` or `True` to tell cli that the terminal supports ANSI hyperlinks. Leave this configuration unset (or set to anything else) when there is no hyperlink support. From 8ef3a37072b4ac3d8393a2ca7b73a20f7d35f969 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Fri, 8 Nov 2024 16:35:40 -0800 Subject: [PATCH 15/15] The options control whether hyperlinks are enabled are not --- R/test.R | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/R/test.R b/R/test.R index b6c96277..9430c04b 100644 --- a/R/test.R +++ b/R/test.R @@ -114,16 +114,12 @@ test_that_cli <- function(desc, code, cli.hyperlink_vignette = links, cli.hyperlink_run_url_format = NULL, cli.hyperlink_help_url_format = NULL, - cli.hyperlink_vignette_url_format = NULL, + cli.hyperlink_vignette_url_format = NULL ) withr::local_envvar( - R_CLI_HYPERLINKS = NA_character_, - R_CLI_HYPERLINK_RUN = NA_character_, - R_CLI_HYPERLINK_HELP = NA_character_, - R_CLI_HYPERLINK_VIGNETTE = NA_character_, R_CLI_HYPERLINK_RUN_URL_FORMAT = NA_character_, R_CLI_HYPERLINK_HELP_URL_FORMAT = NA_character_, - R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT = NA_character_, + R_CLI_HYPERLINK_VIGNETTE_URL_FORMAT = NA_character_ ) code_ }, c(conf, list(code_ = code)))