README.md in tty-link-0.1.1 vs README.md in tty-link-0.2.0
- old
+ new
@@ -1,80 +1,331 @@
<div align="center">
- <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+ <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 [][gitter]
+# TTY::Link
[][gem]
-[][travis]
+[][gh_actions_ci]
[][appveyor]
[][codeclimate]
[][coverage]
-[][inchpages]
-[gitter]: https://gitter.im/piotrmurach/tty
-[gem]: http://badge.fury.io/rb/tty-link
-[travis]: http://travis-ci.org/piotrmurach/tty-link
+[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
-[inchpages]: http://inch-ci.org/github/piotrmurach/tty-link
-> Hyperlinks in your terminal
+> Terminal hyperlinks support detection and generation.
-**TTY::Link** allows you to test whether a terminal supports hyperlinks and print them to the console. It is a component in [TTY toolkit](https://github.com/piotrmurach/tty)
+**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).
-Terminal emulators such as `iTerm2` or `GNOME`, `XFCE` that use `VTE` widget support web style hyperlinks via `Ctrl+click` or `Cmd+click`.
-
## Installation
Add this line to your application's Gemfile:
```ruby
-gem 'tty-link'
+gem "tty-link"
```
And then execute:
- $ bundle
+```shell
+$ bundle
+```
Or install it yourself as:
- $ gem install tty-link
+```shell
+$ gem install tty-link
+```
-## Usage
+## Contents
-To print hyperlink in your terminal do:
+* [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
-puts TTY::Link.link_to("TTY toolkit", "https://ttytoolkit.org")
-# =>
-# TTY toolkit
+link = TTY::Link.new
```
-In cases when the terminal cannot support hyperlinks, an alternative is printed:
+Then use the [link_to](#23-link_to) method to print a hyperlink in the terminal:
```ruby
-# TTY toolkit -> https://ttytoolkit.org
+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.
+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).
+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 [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+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).
+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).
+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 for further details.
+Copyright (c) 2019 Piotr Murach. See
+[LICENSE.txt](https://github.com/piotrmurach/tty-link/blob/master/LICENSE.txt)
+for further details.