tty-link 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34124696be1323e7ee9ace0870d5e3039790de3c6802d63e54e27ce8c9cfcc2f
-  data.tar.gz: 9391c73775b6b8e630f6949a25e846bd7f757f36f705ccf8997695d3d2f69fd4
+  metadata.gz: 5bbfbeed607763fe4eece7cc6351d84123d9caca1185636424fe452c0cb590d7
+  data.tar.gz: f577fb6db5a7a0a0b0e337068d828e01d2b6abaf6d0941405fce55a2272d33b4
 SHA512:
-  metadata.gz: d3ca88361271eb978c36ae7da6ba7cb17d2b4744817478135bea33192931689409aa29ea7f25667ecf1e1e2d78fccd75ce03d74973d8f28002b114d87ac5c165
-  data.tar.gz: e0924a44d4b531aa5cbebbfcae82e072fb5ad1ee164bd9efc24cb5f7185c0fd927e33f7715c7fb30c487c6c07ca9453204333631d60436402487e288097beced
+  metadata.gz: 1198ec8d93ab064c8e6c6cb2c7adec21cf36f11ad0afb99cb7d25387ff105a6478d3a1f6b8a0999081331dcfed3c41c9157b74be125268e4f9fe3001ff0564e4
+  data.tar.gz: 3ef6ee73c3cbf5a8a1eb974d512b4f6b67c50024ba1c9f726e2128ae07c04ff7536f9c84071de32a122bbf99cc2408d971954c21da47a9a507fb0a1b63caf38b

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change log
 
+## [v0.2.0] - 2024-11-03
+
+### Added
+* Add the ability to configure the environment variables, hyperlink detection,
+  output stream and plain URL template to the initialize method
+* Add the ability to configure the hyperlink detection with the environment
+  variable
+* Add the ability to create hyperlinks from the URL only to the link_to method
+* Add an attrs option to the link_to method to allow configuring URL attributes
+* Add hyperlinks support detection in Alacritty, Contour, DomTerm, foot, Hyper,
+  JediTerm, kitty, Konsole, mintty, Rio, Tabby, Terminology, VSCode, WezTerm
+  and Windows Terminal
+
+### Changed
+* Change the BEL and OSC control characters from Unicode to escape code
+* Change the OSC constant to OSC8 to include the hyperlink control number
+* Change the TTY::Link module to a class
+* Change the TTY::Link class to remove the ESC constant
+* Change the TTY::Link class constants to be private
+* Change the TTY::Link class to check the iTerm program version presence
+* Change the support_link? method to rename to link?
+
 ## [v0.1.1] - 2020-01-25
 
 ### Changed
@@ -9,4 +31,6 @@
 
 * Initial implementation and release
 
+[v0.2.0]: https://github.com/piotrmurach/tty-link/compare/v0.1.1...v0.2.0
+[v0.1.1]: https://github.com/piotrmurach/tty-link/compare/v0.1.0...v0.1.1
 [v0.1.0]: https://github.com/piotrmurach/tty-link/compare/v0.1.0

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Piotr Murach
+Copyright (c) 2019 Piotr Murach (piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -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](https://badges.gitter.im/Join%20Chat.svg)][gitter]
+# TTY::Link
 
 [![Gem Version](https://badge.fury.io/rb/tty-link.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-link.svg?branch=master)][travis]
+[![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]
-[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-link.svg?branch=master)][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)
-
-Terminal emulators such as `iTerm2` or `GNOME`, `XFCE` that use `VTE` widget support web style hyperlinks via `Ctrl+click` or `Cmd+click`.
+**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'
+gem "tty-link"
 ```
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install tty-link
+```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:
 
-## Usage
+```ruby
+link.link?
+```
 
-To print hyperlink in your terminal do:
+Overwrite this automatic detection with the [:hyperlink](#213-hyperlink)
+keyword.
+
+For example, to always create hyperlinks in the terminal:
 
 ```ruby
-puts TTY::Link.link_to("TTY toolkit", "https://ttytoolkit.org")
-# =>
-# TTY toolkit
+link = TTY::Link.new(hyperlink: :always)
 ```
 
-In cases when the terminal cannot support hyperlinks, an alternative is printed:
+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
-# TTY toolkit -> https://ttytoolkit.org
+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.

data/lib/tty/link/ansi_link.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Responsible for converting a URL to an ANSI-controlled terminal link
+    #
+    # @api private
+    class ANSILink
+      # The attribute separator
+      #
+      # @return [String]
+      #
+      # @api private
+      ATTRIBUTE_SEPARATOR = "="
+      private_constant :ATTRIBUTE_SEPARATOR
+
+      # The attribute pair separator
+      #
+      # @return [String]
+      #
+      # @api private
+      ATTRIBUTE_PAIR_SEPARATOR = ":"
+      private_constant :ATTRIBUTE_PAIR_SEPARATOR
+
+      # The bell control code
+      #
+      # @return [String]
+      #
+      # @api private
+      BEL = "\a"
+      private_constant :BEL
+
+      # The hyperlink operating system command code
+      #
+      # @return [String]
+      #
+      # @api private
+      OSC8 = "\e]8"
+      private_constant :OSC8
+
+      # The parameters separator
+      #
+      # @return [String]
+      #
+      # @api private
+      SEP = ";"
+      private_constant :SEP
+
+      # Create an {TTY::Link::ANSILink} instance
+      #
+      # @example
+      #   ansi_link = TTY::Link::ANSILink.new(
+      #     "TTY Toolkit", "https://ttytoolkit.org", {id: "tty-toolkit"})
+      #
+      # @param [String] name
+      #   the URL name
+      # @param [String] url
+      #   the URL target
+      # @param [Hash{Symbol => String}] attrs
+      #   the URL attributes
+      #
+      # @api public
+      def initialize(name, url, attrs)
+        @name = name
+        @url = url
+        @attrs = attrs
+      end
+
+      # Convert this link to an ANSI-controlled string
+      #
+      # @example
+      #   ansi_link.to_s
+      #   # => "\e]8;id=tty-toolkit;https://ttytoolkit.org\aTTY Toolkit\e]8;;\a"
+      #
+      # @return [String]
+      #
+      # @api public
+      def to_s
+        attributes = convert_to_attributes(@attrs)
+        [OSC8, SEP, attributes, SEP, @url, BEL, @name, OSC8, SEP, SEP, BEL].join
+      end
+
+      private
+
+      # Convert the attributes hash to a string list
+      #
+      # @example
+      #   ansi_link.convert_to_attributes(
+      #     {id: "tty-toolkit", title: "TTY Toolkit"})
+      #   # => "id=tty-toolkit:title=TTY Toolkit"
+      #
+      # @param [Hash{Symbol => String}] attrs
+      #   the attributes to convert to a string list
+      #
+      # @return [String]
+      #
+      # @api private
+      def convert_to_attributes(attrs)
+        attrs.map do |attr_pair|
+          attr_pair.join(ATTRIBUTE_SEPARATOR)
+        end.join(ATTRIBUTE_PAIR_SEPARATOR)
+      end
+    end # ANSILink
+  end # Link
+end # TTY

data/lib/tty/link/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Raised to signal an error condition
+    #
+    # @api public
+    Error = Class.new(StandardError)
+
+    # Raised when an abstract method is called
+    #
+    # @api public
+    class AbstractMethodError < Error
+      MESSAGE = "the %<class_name>s class must implement " \
+                "the `%<method_name>s` method"
+
+      # Create an {TTY::Link::AbstractMethodError} instance
+      #
+      # @example
+      #   TTY::Link::AbstractMethodError.new("Terminal", "name?")
+      #
+      # @param [String] class_name
+      #   the class name
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      # @api private
+      def initialize(class_name, method_name)
+        super(format(MESSAGE, class_name: class_name, method_name: method_name))
+      end
+    end
+
+    # Raised when a parameter value doesn't match the allowed values
+    #
+    # @api public
+    class ValueError < Error
+      # The error message template
+      #
+      # @return [String]
+      #
+      # @api private
+      MESSAGE = "invalid value for the %<param_name>s parameter: " \
+                "%<invalid_value>s.\nMust be one of: %<allowed_values>s."
+      private_constant :MESSAGE
+
+      # The allowed values separator
+      #
+      # @return [String]
+      #
+      # @api private
+      VALUES_SEPARATOR = ", "
+      private_constant :VALUES_SEPARATOR
+
+      # Create a {TTY::Link::ValueError} instance
+      #
+      # @example
+      #   TTY::Link::ValueError.new(:name, :invalid, %i[valid_a valid_b])
+      #
+      # @param [Symbol] param_name
+      #   the parameter name
+      # @param [Object] invalid_value
+      #   the invalid value
+      # @param [Array] allowed_values
+      #   the allowed values
+      #
+      # @api private
+      def initialize(param_name, invalid_value, allowed_values)
+        super(format(
+          MESSAGE,
+          param_name: param_name.inspect,
+          invalid_value: invalid_value.inspect,
+          allowed_values: allowed_values.map(&:inspect).join(VALUES_SEPARATOR)
+        ))
+      end
+    end # ValueError
+  end # Link
+end # TTY

data/lib/tty/link/hyperlink_parameter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Responsible for representing hyperlink parameter value
+    #
+    # @api private
+    class HyperlinkParameter
+      # The allowed parameter values
+      #
+      # @return [Array<String>]
+      #
+      # @api private
+      ALLOWED_VALUES = %w[always auto never].freeze
+      private_constant :ALLOWED_VALUES
+
+      # Create a {TTY::Link::HyperlinkParameter} instance
+      #
+      # @example
+      #   hyperlink_parameter = TTY::Link::HyperlinkParameter.new(:always)
+      #
+      # @param [String, Symbol] value
+      #   the parameter value
+      #
+      # @raise [TTY::Link::ValueError]
+      #   the value isn't always, auto or never
+      #
+      # @api public
+      def initialize(value)
+        @value = validate(value).to_sym
+      end
+
+      # Check whether this parameter value is always
+      #
+      # @example
+      #   hyperlink_parameter.always?
+      #   # => true
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def always?
+        @value == :always
+      end
+
+      # Check whether this parameter value is auto
+      #
+      # @example
+      #   hyperlink_parameter.auto?
+      #   # => false
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def auto?
+        @value == :auto
+      end
+
+      # Check whether this parameter value is never
+      #
+      # @example
+      #   hyperlink_parameter.never?
+      #   # => false
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def never?
+        @value == :never
+      end
+
+      private
+
+      # Validate this parameter value
+      #
+      # @example
+      #   hyperlink_parameter.validate(:invalid)
+      #
+      # @param [Object] value
+      #   the value to validate
+      #
+      # @return [String, Symbol]
+      #
+      # @raise [TTY::Link::ValueError]
+      #   the value isn't always, auto or never
+      #
+      # @api private
+      def validate(value)
+        return value if ALLOWED_VALUES.include?(value.to_s)
+
+        raise ValueError.new(:hyperlink, value, ALLOWED_VALUES.map(&:to_sym))
+      end
+    end # HyperlinkParameter
+  end # Link
+end # TTY