TTY::Link

Terminal hyperlinks support detection and generation.

TTY::Link detects whether the terminal supports hyperlinks and creates them ready for display in the console. It is a component of the TTY toolkit.

Installation

Add this line to your application's Gemfile:

gem "tty-link"

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-link

Contents

• 1. Usage
• 2. API
  • 2.1 new
    • 2.1.1 :env
    • 2.1.2 :output
    • 2.1.3 :hyperlink
    • 2.1.4 :plain
  • 2.2 link?
  • 2.3 link_to
    • 2.3.1 :attrs
• 3. Supported Terminals

1. Usage

Create a TTY::Link instance:

link = TTY::Link.new

Then use the link_to method to print a hyperlink in the terminal:

puts link.link_to("TTY Toolkit", "https://ttytoolkit.org")

This will output a clickable link in the terminal supporting hyperlinks:

TTY Toolkit

Or it will print a plain text version with a URL in unsupported terminals:

TTY Toolkit -> https://ttytoolkit.org

By default, TTY::Link uses the link? method to detect whether the terminal supports hyperlinks:

link.link?

Overwrite this automatic detection with the :hyperlink keyword.

For example, to always create hyperlinks in the terminal:

link = TTY::Link.new(hyperlink: :always)

Alternatively, use the TTY_LINK_HYPERLINK environment variable to control hyperlink support detection. The variable takes precedence over the :hyperlink keyword.

Use the :env keyword to overwrite any environment variables set in the terminal:

link = TTY::Link.new(env: {"TTY_LINK_HYPERLINK" => "always"})

As a convenience, the link? and link_to methods are also available on the TTY::Link class. The methods accept all the configuration keywords.

For example, to always output hyperlinks in the terminal:

puts TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org", hyperlink: :always)

2. API

2.1 new

2.1.1 :env

The new method accepts the :env keyword to define environment variables. The keyword defaults to the ENV object that holds the current environment variables.

For example, to define only an environment variable TTY_LINK_HYPERLINK with always value:

link = TTY::Link.new(env: {"TTY_LINK_HYPERLINK" => "always"})

2.1.2 :output

The new method accepts the :output keyword to define the output stream. The keyword defaults to the standard output.

For example, to use the standard error stream:

link = TTY::Link.new(output: $stderr)

2.1.3 :hyperlink

The new method accepts the :hyperlink keyword to control terminal hyperlink support detection. The available values are :always, :auto and :never. The keyword defaults to the :auto value to allow the link? method to check whether the given terminal supports hyperlinks.

For example, use the :always value to force the link_to method to create hyperlinks without checking terminal support:

link = TTY::Link.new(hyperlink: :always)

Or, use the :never value to force the link_to to create text-only links:

link = TTY::Link.new(hyperlink: :never)

Alternatively, set the TTY_LINK_HYPERLINK environment variable to configure the :hyperlink value:

TTY_LINK_HYPERLINK=always

2.1.4 :plain

The new method accepts the :plain keyword to define a text-only hyperlink replacement template. The link_to method uses the template to create a plain URL alternative on terminals without hyperlink support.

The template can contain two tokens, the :name and the :url. The tokens are optional. The :name -> :url is the default template. The link_to method replaces the present token with the given argument.

For example, given a link to https://ttytoolkit.org named TTY Toolkit:

link.link_to("TTY Toolkit", "https://ttytoolkit.org")

This will create the following string from the default template:

"TTY toolkit -> https://ttytoolkit.org"

To change the default template and display links, for example, with the name and the URL surrounded by brackets:

link = TTY::Link.new(plain: ":name (:url)")

Then passing the same arguments to the link_to method:

link.link_to("TTY Toolkit", "https://ttytoolkit.org")

This will create the following string from the custom template:

"TTY toolkit (https://ttytoolkit.org)"

2.2 link?

The link? method detects whether the terminal supports hyperlinks against supported terminals. The link_to method uses this detection to decide whether to create a hyperlink or plain text alternative.

For example, to check the current terminal hyperlink support:

link.link?

2.3 link_to

The link_to method accepts two arguments, the name and the URL. The second URL argument is optional.

For example, to create a hyperlink to https://ttytoolkit.org named TTY Toolkit:

link.link_to("TTY Toolkit", "https://ttytoolkit.org")

To create a hyperlink where the name is the same as the URL:

link.link_to("https://ttytoolkit.org")

2.3.1 :attrs

The link_to method accepts the :attrs keyword to define attributes for a hyperlink. Note that currently, hyperlink-capable terminals support only the id attribute. However, there is no limitation on the attribute names to allow future support.

For example, to define the id attribute:

link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {id: "tty-toolkit"})

To define many attributes such as id, lang and title:

link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {
  id: "tty-toolkit", lang: "en", title: "Terminal Apps The Easy Way"
})

3. Supported Terminals

The TTY::Link supports hyperlink generation in the following terminals:

• Alacritty
• Contour
• DomTerm
• foot
• Hyper
• iTerm2
• JediTerm
• kitty
• Konsole
• mintty
• Rio
• Tabby
• Terminology
• VSCode
• VTE (GNOME, Xfce, ROXTerm, Guake, sakura, Terminator)
• WezTerm
• Windows Terminal

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-link. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the TTY::Link project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright

Copyright (c) 2019 Piotr Murach. See LICENSE.txt for further details.