<div align="center">
  <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
</div>

# TTY::Link

[![Gem Version](https://badge.fury.io/rb/tty-link.svg)][gem]
[![Actions CI](https://github.com/piotrmurach/tty-link/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]
[![Build status](https://ci.appveyor.com/api/projects/status/4vb3w6wmr9w9vfp7?svg=true)][appveyor]
[![Maintainability](https://api.codeclimate.com/v1/badges/3f8c368617c464238bf9/maintainability)][codeclimate]
[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-link/badge.svg)][coverage]

[gem]: https://badge.fury.io/rb/tty-link
[gh_actions_ci]: https://github.com/piotrmurach/tty-link/actions/workflows/ci.yml
[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-link
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-link/maintainability
[coverage]: https://coveralls.io/github/piotrmurach/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](https://github.com/piotrmurach/tty).

## Installation

Add this line to your application's Gemfile:

```ruby
gem "tty-link"
```

And then execute:

```shell
$ bundle
```

Or install it yourself as:

```shell
$ gem install tty-link
```

## Contents

* [1. Usage](#1-usage)
* [2. API](#2-api)
  * [2.1 new](#21-new)
    * [2.1.1 :env](#211-env)
    * [2.1.2 :output](#212-output)
    * [2.1.3 :hyperlink](#213-hyperlink)
    * [2.1.4 :plain](#214-plain)
  * [2.2 link?](#22-link)
  * [2.3 link_to](#23-link_to)
    * [2.3.1 :attrs](#231-attrs)
* [3. Supported Terminals](#3-supported-terminals)

## 1. Usage

Create a **TTY::Link** instance:

```ruby
link = TTY::Link.new
```

Then use the [link_to](#23-link_to) method to print a hyperlink in the terminal:

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

This will output a clickable link in the
[terminal supporting](#3-supported-terminals) hyperlinks:

```shell
TTY Toolkit
```

Or it will print a [plain](#214-plain) text version with a URL in unsupported
terminals:

```shell
TTY Toolkit -> https://ttytoolkit.org
```

By default, **TTY::Link** uses the [link?](#22-link) method to detect whether
the terminal supports hyperlinks:

```ruby
link.link?
```

Overwrite this automatic detection with the [:hyperlink](#213-hyperlink)
keyword.

For example, to always create hyperlinks in the terminal:

```ruby
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](#213-hyperlink) keyword.

Use the [:env](#211-env) keyword to overwrite any environment variables set
in the terminal:

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

As a convenience, the [link?](#22-link) and [link_to](#23-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:

```ruby
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:

```ruby
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:

```ruby
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?](#22-link) method
to check whether the given terminal supports hyperlinks.

For example, use the `:always` value to force the [link_to](#23-link_to) method
to create hyperlinks without checking terminal support:

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

Or, use the `:never` value to force the [link_to](#23-link_to) to create
text-only links:

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

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

```shell
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](#23-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](#23-link_to) method replaces the present token with the given
argument.

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

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

This will create the following string from the default template:

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

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

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

Then passing the same arguments to the [link_to](#23-link_to) method:

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

This will create the following string from the custom template:

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

### 2.2 link?

The `link?` method detects whether the terminal supports hyperlinks against
[supported terminals](#3-supported-terminals). The [link_to](#23-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:

```ruby
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`:

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

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

```ruby
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:

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

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

```ruby
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](https://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](https://github.com/piotrmurach/tty-link/blob/master/CODE_OF_CONDUCT.md).

## License

The gem is available as open source under the terms of the
[MIT License](https://opensource.org/licenses/MIT).

## 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](https://github.com/piotrmurach/tty-link/blob/master/CODE_OF_CONDUCT.md).

## Copyright

Copyright (c) 2019 Piotr Murach. See
[LICENSE.txt](https://github.com/piotrmurach/tty-link/blob/master/LICENSE.txt)
for further details.