tty-link 0.1.1 → 0.2.0

data/lib/tty/link/plain_link.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Responsible for converting a URL to a plain terminal link
+    #
+    # @api private
+    class PlainLink
+      # The replacement tokens pattern
+      #
+      # @return [Regexp]
+      #
+      # @api private
+      REPLACEMENT_TOKENS_PATTERN = /:(name|url)/i.freeze
+      private_constant :REPLACEMENT_TOKENS_PATTERN
+
+      # Create a {TTY::Link::PlainLink} instance
+      #
+      # @example
+      #   plain_link = TTY::Link::PlainLink.new(
+      #     "TTY Toolkit", "https://ttytoolkit.org", ":name (:url)")
+      #
+      # @param [String] name
+      #   the URL name
+      # @param [String] url
+      #   the URL target
+      # @param [String] template
+      #   the URL replacement template
+      #
+      # @api public
+      def initialize(name, url, template)
+        @name = name
+        @url = url
+        @template = template
+      end
+
+      # Convert this link to a plain string
+      #
+      # @example
+      #   plain_link.to_s
+      #   # => "TTY Toolkit (https://ttytoolkit.org)"
+      #
+      # @return [String]
+      #
+      # @api public
+      def to_s
+        replacements = {":name" => @name, ":url" => @url}
+        @template.gsub(REPLACEMENT_TOKENS_PATTERN, replacements)
+      end
+    end # PlainLink
+  end # Link
+end # TTY

data/lib/tty/link/semantic_version.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Responsible for comparing terminal release versions
+    #
+    # @api private
+    class SemanticVersion
+      include Comparable
+
+      # The unseparated version pattern
+      #
+      # @return [Regexp]
+      #
+      # @api private
+      UNSEPARATED_VERSION_PATTERN = /^(\d{1,2})(\d{2})$/.freeze
+      private_constant :UNSEPARATED_VERSION_PATTERN
+
+      # The version separator
+      #
+      # @return [String]
+      #
+      # @api private
+      VERSION_SEPARATOR = "."
+      private_constant :VERSION_SEPARATOR
+
+      # The zero number
+      #
+      # @return [String]
+      #
+      # @api private
+      ZERO_NUMBER = "0"
+      private_constant :ZERO_NUMBER
+
+      # Create a {TTY::Link::SemanticVersion} instance from a version value
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.from(1, 2, 3)
+      #
+      # @example
+      #   TTY::Link::SemanticVersion[1, 2, 3]
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.from("1234")
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.from("1.2.3")
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.from("1-2-3", separator: "-")
+      #
+      # @param [Array<Integer, String>] version
+      #   the version to convert to a semantic version
+      # @param [String] separator
+      #   the version separator
+      #
+      # @return [TTY::Link::SemanticVersion]
+      #
+      # @api public
+      def self.from(*version, separator: VERSION_SEPARATOR)
+        major, minor, patch =
+          if version.size == 1 && version[0].respond_to?(:split)
+            convert_to_array(version[0], separator: separator)
+          else
+            version
+          end
+        new(major.to_i, minor.to_i, patch.to_i)
+      end
+      singleton_class.send(:alias_method, :[], :from)
+
+      # Convert a string version to an array
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.from("1234")
+      #   # => ["0", "12", "34"]
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.convert_to_array("1.2.3")
+      #   # => ["1", "2", "3"]
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.convert_to_array("1-2-3", separator: "-")
+      #   # => ["1", "2", "3"]
+      #
+      # @param [String] version
+      #   the version to convert to an array
+      # @param [String] separator
+      #   the version separator
+      #
+      # @return [Array<String>]
+      #
+      # @api private
+      def self.convert_to_array(version, separator: VERSION_SEPARATOR)
+        if (matches = version.match(UNSEPARATED_VERSION_PATTERN))
+          [ZERO_NUMBER, matches[1], matches[2]]
+        else
+          version.split(separator)
+        end
+      end
+      private_class_method :convert_to_array
+
+      # The major number
+      #
+      # @example
+      #   semantic_version.major
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :major
+
+      # The minor number
+      #
+      # @example
+      #   semantic_version.minor
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :minor
+
+      # The patch number
+      #
+      # @example
+      #   semantic_version.patch
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :patch
+
+      # Create a {TTY::Link::SemanticVersion} instance
+      #
+      # @example
+      #   TTY::Link::SemanticVersion.new(1, 2, 3)
+      #
+      # @param [Integer] major
+      #   the major number
+      # @param [Integer] minor
+      #   the minor number
+      # @param [Integer] patch
+      #   the patch number
+      #
+      # @api private
+      def initialize(major, minor, patch)
+        @major = major
+        @minor = minor
+        @patch = patch
+      end
+      private_class_method :new
+
+      # Compare this semantic version with another object
+      #
+      # @example
+      #   semantic_version >= other
+      #
+      # @param [Object] other
+      #   the other object to compare with
+      #
+      # @return [Integer, nil]
+      #   Return negative, zero, or positive number when
+      #   this semantic version is less than, equal to, or
+      #   greater than other semantic version. Return nil
+      #   when the other object is not a semantic version.
+      #
+      # @api public
+      def <=>(other)
+        return unless other.is_a?(self.class)
+
+        major_comparison = @major <=> other.major
+        return major_comparison unless major_comparison.zero?
+
+        minor_comparison = @minor <=> other.minor
+        return minor_comparison unless minor_comparison.zero?
+
+        @patch <=> other.patch
+      end
+
+      # Generate hash value for this semantic version
+      #
+      # @example
+      #   semantic_version.hash
+      #
+      # @return [Integer]
+      #
+      # @api public
+      def hash
+        [self.class, @major, @minor, @patch].hash
+      end
+
+      # Convert this semantic version to a string
+      #
+      # @example
+      #   semantic_version.inspect
+      #
+      # @return [String]
+      #
+      # @api public
+      def inspect
+        [@major, @minor, @patch].join(VERSION_SEPARATOR)
+      end
+    end # SemanticVersion
+  end # Link
+end # TTY

data/lib/tty/link/terminals/abstract.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for providing common terminal detection
+      #
+      # @abstract Override {#name?} and {#version?} to implement
+      #           terminal hyperlinks detection
+      #
+      # @api private
+      class Abstract
+        # The term environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        TERM = "TERM"
+        private_constant :TERM
+
+        # The term program environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        TERM_PROGRAM = "TERM_PROGRAM"
+        private_constant :TERM_PROGRAM
+
+        # The term program version environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        TERM_PROGRAM_VERSION = "TERM_PROGRAM_VERSION"
+        private_constant :TERM_PROGRAM_VERSION
+
+        # Register a terminal class with terminals
+        #
+        # @param [TTY::Link::Terminal::Abstract] terminal_class
+        #   the terminal class to register
+        #
+        # @return [void]
+        #
+        # @api private
+        def self.inherited(terminal_class)
+          super
+          Terminals.register(terminal_class)
+        end
+        private_class_method :inherited
+
+        # Create an {TTY::Link::Terminals::Abstract} instance
+        #
+        # @example
+        #   terminal = TTY::Link::Terminals::Abstract.new(SemanticVersion, ENV)
+        #
+        # @param [TTY::Link::SemanticVersion] semantic_version
+        #   the semantic version creator
+        # @param [ENV, Hash{String => String}] env
+        #   the environment variables
+        #
+        # @api public
+        def initialize(semantic_version, env)
+          @semantic_version = semantic_version
+          @env = env
+        end
+
+        # Detect a terminal hyperlink support
+        #
+        # @example
+        #   terminal.link?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def link?
+          name? && version?
+        end
+
+        protected
+
+        # Detect a terminal name
+        #
+        # @example
+        #   terminal.name?
+        #
+        # @raise [TTY::Link::AbstractMethodError]
+        #   the class doesn't implement the name? method
+        #
+        # @abstract
+        #
+        # @api private
+        def name?
+          raise AbstractMethodError.new(self.class.name, __method__)
+        end
+
+        # Detect whether a terminal version supports terminal hyperlinks
+        #
+        # @example
+        #   terminal.version?
+        #
+        # @raise [TTY::Link::AbstractMethodError]
+        #   the class doesn't implement the version? method
+        #
+        # @abstract
+        #
+        # @api private
+        def version?
+          raise AbstractMethodError.new(self.class.name, __method__)
+        end
+
+        # The environment variables
+        #
+        # @example
+        #   terminal.env
+        #
+        # @return [ENV, Hash{String => String}]
+        #
+        # @api private
+        attr_reader :env
+
+        # Create a {TTY::Link::SemanticVersion} instance from a version value
+        #
+        # @example
+        #   terminal.semantic_version(1, 2, 3)
+        #
+        # @example
+        #   terminal.semantic_version("1.2.3")
+        #
+        # @param [Array<Integer, String>] version
+        #   the version to convert to a semantic version
+        # @param [Hash{Symbol => String}] options
+        #   the options to convert to a semantic version
+        # @option options [String] :separator
+        #   the version separator
+        #
+        # @return [TTY::Link::SemanticVersion]
+        #
+        # @see SemanticVersion#from
+        #
+        # @api private
+        def semantic_version(*version, **options)
+          @semantic_version.from(*version, **options)
+        end
+
+        # Read the term environment variable
+        #
+        # @example
+        #   terminal.term
+        #   # => "alacritty"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def term
+          env[TERM]
+        end
+
+        # Read the term program environment variable
+        #
+        # @example
+        #   terminal.term_program
+        #   # => "iTerm.app"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def term_program
+          env[TERM_PROGRAM]
+        end
+
+        # Read the term program version environment variable
+        #
+        # @example
+        #   terminal.term_program_version
+        #   # => "1.2.3"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def term_program_version
+          env[TERM_PROGRAM_VERSION]
+        end
+      end # Abstract
+    end # Terminals
+  end # Link
+end # TTY

data/lib/tty/link/terminals/alacritty.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for detecting hyperlink support in the Alacritty terminal
+      #
+      # @api private
+      class Alacritty < Abstract
+        # The Alacritty terminal name pattern
+        #
+        # @return [Regexp]
+        #
+        # @api private
+        ALACRITTY = /alacritty/i.freeze
+        private_constant :ALACRITTY
+
+        private
+
+        # Detect Alacritty terminal
+        #
+        # @example
+        #   alacritty.name?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def name?
+          !(term =~ ALACRITTY).nil?
+        end
+
+        # Detect any Alacritty version to support terminal hyperlinks
+        #
+        # @example
+        #   alacritty.version?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def version?
+          true
+        end
+      end # Alacritty
+    end # Terminals
+  end # Link
+end # TTY

data/lib/tty/link/terminals/contour.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for detecting hyperlink support in the Contour terminal
+      #
+      # @api private
+      class Contour < Abstract
+        # The Contour terminal name pattern
+        #
+        # @return [Regexp]
+        #
+        # @api private
+        CONTOUR = /contour/i.freeze
+        private_constant :CONTOUR
+
+        # The terminal name environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        TERMINAL_NAME = "TERMINAL_NAME"
+        private_constant :TERMINAL_NAME
+
+        # The terminal version triple environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        TERMINAL_VERSION_TRIPLE = "TERMINAL_VERSION_TRIPLE"
+        private_constant :TERMINAL_VERSION_TRIPLE
+
+        private
+
+        # Detect Contour terminal
+        #
+        # @example
+        #   contour.name?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def name?
+          !(terminal_name =~ CONTOUR).nil?
+        end
+
+        # Detect whether the Contour version supports terminal hyperlinks
+        #
+        # @example
+        #   contour.version?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def version?
+          return false unless terminal_version_triple
+
+          current_semantic_version = semantic_version(terminal_version_triple)
+
+          current_semantic_version >= semantic_version(0, 1, 0)
+        end
+
+        # Read the terminal name environment variable
+        #
+        # @example
+        #   contour.terminal_name
+        #   # => "contour"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def terminal_name
+          env[TERMINAL_NAME]
+        end
+
+        # Read the terminal version triple environment variable
+        #
+        # @example
+        #   contour.terminal_version_triple
+        #   # => "1.2.3"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def terminal_version_triple
+          env[TERMINAL_VERSION_TRIPLE]
+        end
+      end # Contour
+    end # Terminals
+  end # Link
+end # TTY

data/lib/tty/link/terminals/domterm.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for detecting hyperlink support in the DomTerm terminal
+      #
+      # @api private
+      class Domterm < Abstract
+        # The domterm environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        DOMTERM = "DOMTERM"
+        private_constant :DOMTERM
+
+        # The key and value separator
+        #
+        # @return [String]
+        #
+        # @api private
+        KEY_VAL_SEP = "="
+        private_constant :KEY_VAL_SEP
+
+        # The parameter separator
+        #
+        # @return [String]
+        #
+        # @api private
+        PARAM_SEP = ";"
+        private_constant :PARAM_SEP
+
+        # The version parameter pattern
+        #
+        # @return [Regexp]
+        #
+        # @api private
+        VERSION_PARAM = /version/i.freeze
+        private_constant :VERSION_PARAM
+
+        private
+
+        # Detect DomTerm terminal
+        #
+        # @example
+        #   domterm.name?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def name?
+          !domterm.nil?
+        end
+
+        # Detect whether the DomTerm version supports terminal hyperlinks
+        #
+        # @example
+        #   domterm.version?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def version?
+          return false unless domterm_version
+
+          current_semantic_version = semantic_version(domterm_version)
+
+          current_semantic_version >= semantic_version(1, 0, 2)
+        end
+
+        # Read the domterm environment variable
+        #
+        # @example
+        #   domterm.domterm
+        #   # => "version=1.2.3;tty=/dev/pts/1"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def domterm
+          env[DOMTERM]
+        end
+
+        # Read the version from the domterm environment variable
+        #
+        # @example
+        #   domterm.domterm_version
+        #   # => "1.2.3"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def domterm_version
+          version_pair = domterm.split(PARAM_SEP).grep(VERSION_PARAM)[0]
+          return unless version_pair
+
+          version_pair.split(KEY_VAL_SEP)[1]
+        end
+      end # Domterm
+    end # Terminals
+  end # Link
+end # TTY