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
- 2.1 new
- 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.