cli
cli copied to clipboard
Specific helper for RStudio code execution links
e.g.:
link <- function(code) {
cli::style_hyperlink(code, paste0("rstudio:run:testthat::", code))
}
Main difference with style_hyperlink()
is that it's only activated if in RStudio.
Paired with inline formatter like .run
. I'm pretty sure this this should be different to .code
since that often contains unrunnable snippets.
It may need to be like .href
because while we want to match the code clicked and run, we made want to vary the details, e.g. we show snapshot_accpet("foo.R")
but we run testthat::snapshot_accept("~/documents/testthat/tests/_snaps/foo.R")
.
Yeah, unfortunately, we are creating a (sub)DSL for this, but there isn't really another way. I'll write some DSL ideas in this issue later...
Another case where this will be important is for pkgdown — we'd want to render links to websites, but not to local files or to run code.
See complete list in https://github.com/rstudio/rstudio/issues/11273#issuecomment-1153627945
For IDE agnosticity, I think this is now ide:run:
and should be guarded by nzchar(Sys.getenv("R_CLI_HAS_HYPERLINK_RUN"))
(see #499). But @romainfrancois should confirm this.
Final list of link types: https://github.com/rstudio/rstudio/issues/11273#issuecomment-1156193252
Here is the plan.
Update current styles
- [x]
{.email email}
createsmailto:
links - [x]
{.file file}
and{.path file}
createfile:///
links - [ ]
{.file file:line:col}
for line and column number - [ ]
{.fun pkg::fun}
creates links to help, and formatspkg::fun
as a function. - [x]
{.url url}
creates a hyperlink - [ ] TODO: Should they use link text for names? Probably not.
Links to help (new)
- [ ]
{.help pkg::fun}
- [ ]
{.help pkg::fun link text}
- [ ] TODO: topics vs functions?
- [ ] TODO: how to format the link text?
Hyperlinks, possibly with link text (new)
- [ ]
{.href url}
is equivalent to{.url url}
. - [ ]
{.href url link text}
create a hyperlink with link text,url
cannot contain a space character. Ifurl
is not a literal, it is best to useas_href()
on it, to make sure that it does not contain a space. - [ ]
{.href {url}}
uses the name(s) ofurl
as link text
Running code (new)
- [ ]
{.run expr}
- [ ]
{.run expr code}
showcode
(typeset as{.code}
) and link to runningexpr
.
Links to vignettes (new)
- [ ]
{.vignette pkg::name}
- [ ]
{.vignette pkg::name text}
- [ ] TODO: what is the default link text? How to format it?
Notes
If links are not supported, then cli just prints the url
, path
, etc.
If there is also link text, then it prints the link text and in parens the URL, file name, etc.
I considered having {.url url link text}
instead of a new {.href}
style, but URLs are now styled by adding <...>
currently, and that does not look good if there is link text, so it is better to have a new
{.href}` style.
Auto-linking existing styles
They keep formatting. It is not possible to use a different link text with them. We could add link text support, but theming is applied to the result of these tags, and it would look weird for link text. (I.e. if there is link text you don't want to append ()
to the function name, etc.)
N | Goal | Input | Links to (link text is always the verbatim content, styled) |
---|---|---|---|
1 | auto-link emails | {.email [email protected]} |
mailto:[email protected] |
2 | auto-link file | {.file path/file} |
file:///abs/path/dile |
3 | auto-link file with line and column numbers | {.file /abs/path:line:col} |
file:///abs/path:line:col , params = list(line = line, col = col) |
4 | auto-link function | {.fun pkg::fun} |
x-r-help:pkg::fun |
5 | mention function w/o package | {.fun fun} |
no link is created for this form |
6 | auto-link url | {.url url} |
url |
New styles to create links
These all have link text support, via the [text](link)
markdown syntax.
N | Goal | Input | Link text | Links to | Non-link form |
---|---|---|---|---|---|
7 | link qualified function name to help | {.help pkg::fun} |
{.fun pkg::fun} |
x-r-help:pkg::fun |
{.fun ?pkg::fun} |
8 | link to function with link text | {.help [text](pkg::fun)} |
text |
x-r-help:pkg::fun |
text ({.fun ?pkg::fun}) |
9 | link to topic | {.topic pkg::topic} |
pkg::topic |
x-r-help:pkg::topic |
{.code ?pkg::topic} |
10 | link to topic with link text | {.topic [text](pkg::topic)} |
text |
x-r-help:pkg::topic |
text ({.code pkg::topic}) |
11 | link url | {.href url} |
{.url url} |
url |
{.url url} |
12 | link url with link text | {.href [text](url)} |
text |
url |
text ({.url url}) |
13 | link running expr | {.run expr} |
{.code expr} |
x-r-run:expr |
{.code expr} |
14 | link running expr, show code | {.run [code](expr)} |
{.code code} |
x-r-run:expr |
{.code expr} |
15 | link to vignette | {.vignette pkg::name} |
pkg::name |
x-r-vignette:pkg::name |
{.code vignette(pkg::name)} |
16 | link to vignette with link text | {.vignette [text](pkg::name)} |
text |
x-r-vignette:pkg::name |
text ({.code vignette(pkg::name)}) |
Suggestions for non-link forms:
- For documentation link, add
?
in front of the proposed text? - For urls, surround in
<>
(I think maybe only "link url" is missing that?) - For vignette, make it
vignette(name, pkg)
?
Sounds good. URLs are already in <>
, that's part of the default theme.
I updated the table above.