% 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 \{.topic 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 will 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, rlang, pkgload, or pkgdown which are explicitly allowed. } When RStudio does not run a \code{.run} hyperlink, then it shows the code and the user can copy and paste it to the console, if they consider it safe to run. Note that depending on your version of RStudio, the behavior can change. } }