% Generated by roxygen2: do not edit by hand % Please edit documentation in R/cliapp-docs.R \name{links} \alias{links} \title{cli hyperlinks} \description{ Certain cli styles create clickable links, if your IDE or terminal supports them. } \section{Note: hyperlinks are currently experimental}{ The details of the styles that create hyperlinks will prrobably change in the near future, based on user feedback. } \section{About the links in this manual page}{ The hyperlinks that are included in this manual are demonstrative only, except for the \verb{https:} links. They look like a hyperlink, and you can click on them, but they do nothing. I.e. a \code{.run} link will not run the linked expression if you click on it. } \section{Hyperlink Support}{ As of today, the latest release of RStudio (version v2022.07.0+548) supports all hyperlink types discussed here. Certain terminals, e.g. iTerm on macOS, Linux terminals based on VTE (GNOME terminal) support \code{.href}, \code{.email} and \code{.file} links. You can use \code{\link[=ansi_has_hyperlink_support]{ansi_has_hyperlink_support()}} to check if your terminal or IDE has hyperlink support in general, and \code{\link[=ansi_hyperlink_types]{ansi_hyperlink_types()}} to check if various types of hyperlinks are supported. If your hyperlink support is not detected properly in your IDE or terminal, please open a cli issue at \url{https://github.com/r-lib/cli/issues}. } \section{Link text}{ Before we delve into the various types of hyperlinks, a general comment about link texts. Some link styles support a custom link text: \itemize{ \item \code{.href} \item \code{.help} \item \code{.topic} \item \code{.vignette} \item \code{.run} } Others, i.e. \code{.email}, \code{.file}, \code{.fun} and \code{.url} do not support custom link text. The generic syntax for link text is the same as for Markdown hyperlinks: \if{html}{\out{
    }}\preformatted{\{.style [link text](url)\}
    }\if{html}{\out{
}} \subsection{Vectorization}{ Note that it is not possible to add link text to a vector of URLs. E.g. this will create a list of three URLs, all clickable: \if{html}{\out{
    }}\preformatted{urls <- paste0("https://httpbin.org/status/", c(200, 403, 404))
    cli::cli_text("Some httpbin URLs: \{.url \{urls\}\}.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> Some httpbin URLs: <https://httpbin.org/status/200>,
    #> <https://httpbin.org/status/403>, and
    #> <https://httpbin.org/status/404>.

But it is not possible to use a different link text for them. }} } \subsection{What if hyperlinks are not available?}{ If ANSI hyperlinks are not available, then the link text for of these styles outputs both the link text and the URL in a (hopefully) helpful way. See examples below. } } \section{URLs}{ There are two cli styles to link to generic URLs. \code{.url} does not allow custom link text, but \verb{\\href} does. \if{html}{\out{
    }}\preformatted{cli_text(
      "See the cli homepage at \{.url https://cli.r-lib.org\} for details."
    )
    }\if{html}{\out{
}}\if{html}{\out{

    #> See the cli homepage at <https://cli.r-lib.org> for details.

}} \if{html}{\out{
    }}\preformatted{cli_text(
      "See the \{.href [cli homepage](https://cli.r-lib.org)\} for details."
    )
    }\if{html}{\out{
}}\if{html}{\out{

    #> See the cli homepage for details.

}} \subsection{Without hyperlink support}{ This is how these links look without hyperlink support: \if{html}{\out{
    }}\preformatted{local(\{
      withr::local_options(cli.hyperlink = FALSE)
      cli_text(
        "See the cli homepage at \{.url https://cli.r-lib.org\} for details."
      )
      cli_text(
        "See the \{.href [cli homepage](https://cli.r-lib.org)\} for details."
      )
    \})
    }\if{html}{\out{
}}\if{html}{\out{

    #> See the cli homepage at <https://cli.r-lib.org> for details.
    #> See the cli homepage (<https://cli.r-lib.org>) for details.

}} } \subsection{URL encoding}{ Note that cli does not encode the url, so you might need to call \code{utils::URLencode()} on it, especially, if it is substituted in via \code{{}}. \if{html}{\out{
    }}\preformatted{weirdurl <- utils::URLencode("https://example.com/has some spaces")
    cli_text("See more at \{.url \{weirdurl\}\}.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> See more at <https://example.com/has%20some%20spaces>.

}} } } \section{Files}{ The \code{.file} style now automatically creates a \verb{file:} hyperlink. Because \verb{file:} hyperlinks must contain an absolute path, cli tries to convert relative paths, and paths starting with \code{~} to aboslute path. \if{html}{\out{
    }}\preformatted{cli_text("... edit your \{.file ~/.Rprofile\} file.\}")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... edit your ~/.Rprofile file.\}

}} \subsection{Link text}{ \code{.file} cannot use a custom link text. If you custom link text, then you can use \code{.href} with a \verb{file:} URL. \if{html}{\out{
    }}\preformatted{prof <- path.expand("~/.Rprofile")
    cli_text("... edit your \{.href [R profile](file://\{prof\})\}.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... edit your R profile.

}} } \subsection{Line and column numbers}{ You may add a line number to a file name, separated by \code{:}. Handlers typically place the cursor at that line after opening the file. You may also add a column number, after the line number, separated by another \code{:}. \if{html}{\out{
    }}\preformatted{cli_text("... see line 5 in \{.file ~/.Rprofile:5\}.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... see line 5 in ~/.Rprofile:5.

}} } \subsection{Default handler}{ In RStudio \verb{file:} URLs open within RStudio. If you click on a file link outside of RStudio, typically the operating system is consulted for the application to open it. } \subsection{Without hyperlink support}{ One issue with using \code{.href} file files is that it does not look great if hyperlinks are not available. This will be improved in the future: \if{html}{\out{
    }}\preformatted{local(\{
      withr::local_options(cli.hyperlink = FALSE)
      prof <- path.expand("~/.Rprofile")
      cli_text("... edit your \{.href [R profile](file://\{prof\})\}.")
    \})
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... edit your R profile (<file:///Users/gaborcsardi/.Rprofile>).

}} } } \section{Links to the manual}{ \code{.fun} automatically creates links to the manual page of the function, provided the function name is in the \code{packagename::functionname} form: \if{html}{\out{
    }}\preformatted{cli::cli_text("... see \{.fun stats::lm\} to learn more.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... see `stats::lm()` to learn more.

}} \subsection{Link text}{ For a custom link text, use \code{.help} instead of \code{.fun}. \if{html}{\out{
    }}\preformatted{cli::cli_text("... see \{.help [\{.fun lm\}](stats::lm)\} to learn more.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... see `lm()` to learn more.

}} } \subsection{Without hyperlink support}{ The same message without hyperlink support looks like this: \if{html}{\out{
    }}\preformatted{local(\{
      withr::local_options(cli.hyperlink = FALSE)
      cli::cli_text("... see \{.help [\{.fun lm\}](stats::lm)\} to learn more.")
    \})
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... see `lm()` (`?stats::lm()`) to learn more.

}} } \subsection{Topics}{ To link to a help topic that is not a function, use \code{.topic}: \if{html}{\out{
    }}\preformatted{cli::cli_text("... the tibble options at \{.help tibble::tibble_options\}.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... the tibble options at tibble::tibble_options.

}} \code{.topic} support link text. } \subsection{Vignettes}{ To link to a vignette, use \code{.vignette}: \if{html}{\out{
    }}\preformatted{cli::cli_text("... see the \{.vignette tibble::types\} vignette.")
    }\if{html}{\out{
}}\if{html}{\out{

    #> ... see the tibble::types vignette.

}} } } \section{Click to run code}{ RStudio also supports a special link type that runs R code in the current R session upon clicking. You can create these links with \code{.run}: \if{html}{\out{
    }}\preformatted{cli::cli_text("Run \{.run testthat::snapshot_review()\} to review")
    }\if{html}{\out{
}}\if{html}{\out{

    #> Run testthat::snapshot_review() to review

}} \subsection{Link text}{ Sometimes you want to show a slightly different expression in the link, than the one that is evaluated. E.g. the evaluated expression probably needs to qualify packages with \code{::}, but you might not want to show this: \if{html}{\out{
    }}\preformatted{cli::cli_text(
      "Run \{.run [snapshot_review()](testthat::snapshot_review())\} to review"
    )
    }\if{html}{\out{
}}\if{html}{\out{

    #> Run snapshot_review() to review

}} } \subsection{Security considerations}{ To make \code{.run} hyperlinks more secure, RStudio with not run code \itemize{ \item that is not in the \code{pkg::fun(args)} form, \item if \code{args} contains \code{(}, \verb{)} or \verb{;}, \item if it calls a core package (base, stats, etc.), \item if it calls a package that is not loaded, and it is not one of testthat, devtools, usethis, or rlang, which are explicitly allowed. } } }