Hyperlinks in your terminal
TTY::Link allows you to test whether a terminal supports hyperlinks and print them to the console. It is a component in TTY toolkit.
Terminal emulators such as iTerm2
or GNOME
, XFCE
that use VTE
widget
support web style hyperlinks via Ctrl+click
or Cmd+click
.
Add this line to your application's Gemfile:
gem "tty-link"
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-link
To print hyperlink in your terminal do:
puts TTY::Link.link_to("TTY toolkit", "https://ttytoolkit.org")
# =>
# TTY toolkit
In cases when the terminal cannot support hyperlinks, an alternative is printed:
# TTY toolkit -> https://ttytoolkit.org
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)"
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")
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"
})
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
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.
Bug reports and pull requests are welcome on GitHub at https:/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.
The gem is available as open source under the terms of the MIT License.
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 (c) 2019 Piotr Murach. See LICENSE.txt for further details.