tty-link 0.1.0 → 0.2.0

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for detecting hyperlink support in the WezTerm terminal
+      #
+      # @api private
+      class Wezterm < Abstract
+        # The WezTerm terminal name pattern
+        #
+        # @return [Regexp]
+        #
+        # @api private
+        WEZTERM = /WezTerm/i.freeze
+        private_constant :WEZTERM
+
+        # The version release
+        #
+        # @return [String]
+        #
+        # @api private
+        VERSION_RELEASE = "20180218"
+        private_constant :VERSION_RELEASE
+
+        # The version separator
+        #
+        # @return [String]
+        #
+        # @api private
+        VERSION_SEPARATOR = "-"
+        private_constant :VERSION_SEPARATOR
+
+        private
+
+        # Detect WezTerm terminal
+        #
+        # @example
+        #   wezterm.name?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def name?
+          !(term_program =~ WEZTERM).nil?
+        end
+
+        # Detect whether the WezTerm version supports terminal hyperlinks
+        #
+        # @example
+        #   wezterm.version?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def version?
+          return false unless term_program_version
+
+          current_semantic_version =
+            semantic_version(term_program_version, separator: VERSION_SEPARATOR)
+
+          current_semantic_version >= semantic_version(VERSION_RELEASE, 0, 0)
+        end
+      end # Wezterm
+    end # Terminals
+  end # Link
+end # TTY

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+
+module TTY
+  class Link
+    module Terminals
+      # Responsible for detecting hyperlink support in the Windows Terminal
+      #
+      # @api private
+      class Wt < Abstract
+        # The wt session environment variable name
+        #
+        # @return [String]
+        #
+        # @api private
+        WT_SESSION = "WT_SESSION"
+        private_constant :WT_SESSION
+
+        private
+
+        # Detect Windows Terminal
+        #
+        # @example
+        #   wt.name?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def name?
+          !wt_session.nil?
+        end
+
+        # Detect any Windows Terminal version to support terminal hyperlinks
+        #
+        # @example
+        #   wt.version?
+        #   # => true
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def version?
+          true
+        end
+
+        # Read the wt session environment variable
+        #
+        # @example
+        #   wt.wt_session
+        #   # => "the-unique-identifier"
+        #
+        # @return [String, nil]
+        #
+        # @api private
+        def wt_session
+          env[WT_SESSION]
+        end
+      end # Wt
+    end # Terminals
+  end # Link
+end # TTY

data/lib/tty/link/terminals.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TTY
+  class Link
+    # Responsible for loading terminals
+    #
+    # @api private
+    module Terminals
+      # The directory name for terminals
+      #
+      # @return [String]
+      #
+      # @api private
+      DIR_NAME = "terminals"
+      private_constant :DIR_NAME
+
+      # The Ruby file pattern
+      #
+      # @return [String]
+      #
+      # @api private
+      RUBY_FILE = "*.rb"
+      private_constant :RUBY_FILE
+
+      # The registered terminal classes
+      #
+      # @example
+      #   TTY::Link::Terminals.registered
+      #
+      # @return [Array<TTY::Link::Terminals::Abstract>]
+      #
+      # @api private
+      def self.registered
+        @registered ||= []
+      end
+
+      # Register a terminal class
+      #
+      # @example
+      #   TTY::Link::Terminals.register(TTY::Link::Terminals::Iterm)
+      #
+      # @param [TTY::Link::Terminals::Abstract] terminal_class
+      #   the terminal class to register
+      #
+      # @return [void]
+      #
+      # @api private
+      def self.register(terminal_class)
+        registered << terminal_class
+      end
+
+      # Require all terminal files from the terminals directory
+      #
+      # @example
+      #   TTY::Link::Terminals.require_terminals
+      #
+      # @return [void]
+      #
+      # @api private
+      def self.require_terminals
+        terminals_dir = ::File.join(__dir__, DIR_NAME, RUBY_FILE)
+        ::Dir.glob(terminals_dir).sort.each do |terminal_path|
+          require_relative ::File.join(DIR_NAME, ::File.basename(terminal_path))
+        end
+      end
+      private_class_method :require_terminals
+
+      require_terminals
+    end
+  end # Link
+end # TTY

data/lib/tty/link/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module TTY
-  module Link
-    VERSION = "0.1.0"
+  class Link
+    VERSION = "0.2.0"
   end # Link
 end # TTY

data/lib/tty/link.rb

@@ -1,74 +1,313 @@
 # frozen_string_literal: true
 
+require_relative "link/ansi_link"
+require_relative "link/errors"
+require_relative "link/hyperlink_parameter"
+require_relative "link/plain_link"
+require_relative "link/semantic_version"
+require_relative "link/terminals"
 require_relative "link/version"
 
 module TTY
-  module Link
-    class Error < StandardError; end
+  # Responsible for detecting and generating terminal hyperlinks
+  #
+  # @api public
+  class Link
+    # The default plain URL template
+    #
+    # @return [String]
+    #
+    # @api private
+    DEFAULT_TEMPLATE = ":name -> :url"
+    private_constant :DEFAULT_TEMPLATE
 
-    ESC = "\u001B["
-    OSC = "\u001B]"
-    BEL = "\u0007"
-    SEP = ";"
+    # The hyperlink environment variable name
+    #
+    # @return [String]
+    #
+    # @api private
+    HYPERLINK_ENV = "TTY_LINK_HYPERLINK"
+    private_constant :HYPERLINK_ENV
 
-    ITERM = /iTerm(\s*\d+){0,1}.app/x.freeze
+    # Generate terminal hyperlink
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org")
+    #
+    # @example
+    #   TTY::Link.link_to("https://ttytoolkit.org")
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                     attrs: {id: "tty-toolkit"})
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                     env: {"VTE_VERSION" => "7603"})
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                     hyperlink: :always)
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                     output: $stderr)
+    #
+    # @example
+    #   TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                     plain: ":name (:url)")
+    #
+    # @param [String] name
+    #   the name for the URL
+    # @param [String, nil] url
+    #   the URL target
+    # @param [Hash{Symbol => String}] attrs
+    #   the URL attributes
+    # @param [ENV, Hash{String => String}] env
+    #   the environment variables
+    # @param [String, Symbol] hyperlink
+    #   the hyperlink detection out of always, auto or never
+    # @param [IO] output
+    #   the output stream, defaults to $stdout
+    # @param [String] plain
+    #   the plain URL template
+    #
+    # @return [String]
+    #
+    # @see #link_to
+    #
+    # @api public
+    def self.link_to(name, url = nil, attrs: {}, env: ENV, hyperlink: :auto,
+                     output: $stdout, plain: DEFAULT_TEMPLATE)
+      new(env: env, hyperlink: hyperlink, output: output, plain: plain)
+        .link_to(name, url, attrs: attrs)
+    end
 
-    # Parse version number
+    # Detect terminal hyperlink support
     #
-    # @param [String] version
+    # @example
+    #   TTY::Link.link?
+    #   # => true
     #
-    # @api private
-    def parse_version(version)
-      if (matches = version.match(/^(\d{1,2})(\d{2})$/))
-        major, minor, patch = 0, matches[1].to_i, matches[2].to_i
+    # @example
+    #   TTY::Link.link?(env: {"VTE_VERSION" => "7603"})
+    #   # => true
+    #
+    # @example
+    #   TTY::Link.link?(output: $stderr)
+    #   # => false
+    #
+    # @param [ENV, Hash{String => String}] env
+    #   the environment variables
+    # @param [IO] output
+    #   the output stream, defaults to $stdout
+    #
+    # @return [Boolean]
+    #
+    # @see #link?
+    #
+    # @api public
+    def self.link?(env: ENV, output: $stdout)
+      new(env: env, output: output).link?
+    end
+
+    # Create a {TTY::Link} instance
+    #
+    # @example
+    #   link = TTY::Link.new
+    #
+    # @example
+    #   link = TTY::Link.new(env: {"VTE_VERSION" => "7603"})
+    #
+    # @example
+    #   link = TTY::Link.new(hyperlink: :always)
+    #
+    # @example
+    #   link = TTY::Link.new(output: $stderr)
+    #
+    # @example
+    #   link = TTY::Link.new(plain: ":name (:url)")
+    #
+    # @param [ENV, Hash{String => String}] env
+    #   the environment variables
+    # @param [String, Symbol] hyperlink
+    #   the hyperlink detection out of always, auto or never
+    # @param [IO] output
+    #   the output stream, defaults to $stdout
+    # @param [String] plain
+    #   the plain URL template
+    #
+    # @api public
+    def initialize(env: ENV, hyperlink: :auto, output: $stdout,
+                   plain: DEFAULT_TEMPLATE)
+      @env = env
+      @hyperlink_parameter = hyperlink_parameter(hyperlink_env || hyperlink)
+      @output = output
+      @plain = plain
+    end
+
+    # Generate terminal hyperlink
+    #
+    # @example
+    #   link.link_to("TTY Toolkit", "https://ttytoolkit.org")
+    #
+    # @example
+    #   link.link_to("https://ttytoolkit.org")
+    #
+    # @example
+    #   link.link_to("TTY Toolkit", "https://ttytoolkit.org",
+    #                attrs: {id: "tty-toolkit"})
+    #
+    # @example
+    #   link.link_to("https://ttytoolkit.org",
+    #                attrs: {id: "tty-toolkit", title: "TTY Toolkit"})
+    #
+    # @param [String] name
+    #   the name for the URL
+    # @param [String, nil] url
+    #   the URL target
+    # @param [Hash{Symbol => String}] attrs
+    #   the URL attributes
+    #
+    # @return [String]
+    #
+    # @api public
+    def link_to(name, url = nil, attrs: {})
+      url ||= name
+
+      if ansi_link?
+        ansi_link(name, url, attrs).to_s
       else
-        major, minor, patch = version.split(".").map(&:to_i)
+        plain_link(name, url).to_s
       end
-      { major: major, minor: minor, patch: patch }
     end
-    module_function :parse_version
 
-    # Check if link is supported
+    # Detect terminal hyperlink support
+    #
+    # @example
+    #   link.link?
+    #   # => true
     #
     # @return [Boolean]
     #
     # @api public
-    def support_link?(output: $stdout)
-      return false unless output.tty?
+    def link?
+      return false unless tty?
 
-      if ENV["TERM_PROGRAM"] =~ ITERM
-        version = parse_version(ENV["TERM_PROGRAM_VERSION"])
+      terminals.any?(&:link?)
+    end
 
-        return version[:major] > 3 || version[:major] == 3 && version[:minor] > 0
-      end
+    private
 
-      # uses VTE terminal
-      if ENV["VTE_VERSION"]
-        version = parse_version(ENV["VTE_VERSION"])
+    # Whether to create an {TTY::Link::ANSILink} or a {TTY::Link::PlainLink}
+    #
+    # @example
+    #   link.ansi_link?
+    #   # => true
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def ansi_link?
+      @hyperlink_parameter.always? || (@hyperlink_parameter.auto? && link?)
+    end
 
-        return version[:major] > 0 || version[:minor] > 50 ||
-          version[:minor] == 50 && version[:patch] > 0
-      end
+    # Create an {TTY::Link::ANSILink} instance
+    #
+    # @example
+    #   ansi_link("TTY Toolkit", "https://ttytoolkit.org", {id: "tty-tookit"})
+    #
+    # @param [String] name
+    #   the URL name
+    # @param [String] url
+    #   the URL target
+    # @param [Hash{Symbol => String}] attrs
+    #   the URL attributes
+    #
+    # @return [TTY::Link::ANSILink]
+    #
+    # @see ANSILink#new
+    #
+    # @api private
+    def ansi_link(name, url, attrs)
+      ANSILink.new(name, url, attrs)
+    end
+
+    # Read the hyperlink environment variable
+    #
+    # @example
+    #   link.hyperlink_env
+    #   # => "always"
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    def hyperlink_env
+      @env[HYPERLINK_ENV]
+    end
 
-      return false
+    # Create a {TTY::Link::HyperlinkParameter} instance
+    #
+    # @example
+    #   link.hyperlink_parameter(:always)
+    #
+    # @param [String, Symbol] hyperlink
+    #   the hyperlink detection out of always, auto or never
+    #
+    # @return [TTY::Link::HyperlinkParameter]
+    #
+    # @raise [TTY::Link::ValueError]
+    #   the value isn't always, auto or never
+    #
+    # @api private
+    def hyperlink_parameter(hyperlink)
+      HyperlinkParameter.new(hyperlink)
     end
-    module_function :support_link?
 
-    # Render terminal link
+    # Create a {TTY::Link::PlainLink} instance
+    #
+    # @example
+    #   plain_link("TTY Toolkit", "https://ttytoolkit.org")
     #
     # @param [String] name
+    #   the URL name
     # @param [String] url
+    #   the URL target
     #
-    # @return [String]
+    # @return [TTY::Link::PlainLink]
     #
-    # @api public
-    def link_to(name, url)
-      if support_link?
-        [ OSC, "8", SEP, SEP, url, BEL, name, OSC, "8", SEP, SEP, BEL ].join("")
-      else
-        "#{name} -> #{url}"
+    # @see PlainLink#new
+    #
+    # @api private
+    def plain_link(name, url)
+      PlainLink.new(name, url, @plain)
+    end
+
+    # Terminals for detecting hyperlink support
+    #
+    # @example
+    #   link.terminals
+    #
+    # @return [Array<TTY::Link::Terminals::Abstract>]
+    #
+    # @api private
+    def terminals
+      @terminals ||= Terminals.registered.map do |terminal_class|
+        terminal_class.new(SemanticVersion, @env)
       end
     end
-    module_function :link_to
+
+    # Detect the terminal device
+    #
+    # @example
+    #   link.tty?
+    #   # => true
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def tty?
+      @output.tty?
+    end
   end # Link
 end # TTY

data/lib/tty-link.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require_relative "tty/link"