🥅💄 Auto-highlight parse error based on env vars

Highlighting will be used when either:
* `ENV["TERM"]` is set, and not empty, "dumb", or "unknown"
* `ENV["FORCE_COLOR"]` is set, and not empty, or "0"

I originally checked `$stderr.tty?`, but I think that, in this case,
using ENV vars is both simpler and better.

Author: nevans

lib/net/imap/errors.rb

@@ -116,9 +116,12 @@ def initialize(message = "unspecified parse error",
       # containing only frames for methods in parser_class (since ruby 3.4) or
       # which have "net/imap/response_parser" in the path (before ruby 3.4).
       # Most parser method names are based on rules in the IMAP grammar.
+      #
+      # When +highlight+ is not explicitly set, highlights may be enabled
+      # automatically, based on +TERM+ and +FORCE_COLOR+ environment variables.
       def detailed_message(parser_state: Net::IMAP.debug,
                            parser_backtrace: false,
-                           highlight: false,
+                           highlight: default_highlight_from_env,
                            **)
         return super unless parser_state || parser_backtrace
         msg = super.dup
@@ -161,6 +164,12 @@ def detailed_message(parser_state: Net::IMAP.debug,
       def processed_string = string && pos && string[...pos]
       def remaining_string = string && pos && string[pos..]
 
+      private
+
+      def default_highlight_from_env
+        (ENV["FORCE_COLOR"] || "") !~ /\A(?:0|)\z/ ||
+          (ENV["TERM"] || "") !~ /\A(?:dumb|unknown|)\z/i
+      end
     end
 
     # Superclass of all errors used to encapsulate "fail" responses

test/net/imap/test_errors.rb

@@ -12,6 +12,15 @@ def self.SGR(*attr) = CSI attr.join(?;), ?m
   BOLD           = SGR 1
   BOLD_UNDERLINE = SGR 1, 4
 
+  setup do
+    @term_env_vars = ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"]
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = nil, nil, nil
+  end
+
+  teardown do
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = @term_env_vars
+  end
+
   test "ResponseParseError" do
     # The first examples don't add parser state, so this makes no difference.
     # It affects the last example, which has parser state.
@@ -64,15 +73,16 @@ def self.SGR(*attr) = CSI attr.join(?;), ?m
       "#{BOLD}#{msg} (#{BOLD_UNDERLINE}#{name}#{RESET}#{BOLD})#{RESET}",
       err.detailed_message(highlight: true, parser_state: false)
     )
-    assert_equal(<<~MSG.strip, err.detailed_message)
+
+    expected_no_hl = <<~MSG.strip
       #{msg} (#{name})
         processed : "tag OK [Error=\\"Microsoft.Exchange.Error: foo\\""
         remaining : "] done\\r\\n"
         pos       : 45
         lex_state : :EXPR_BEG
         token     : :QUOTED => "Microsoft.Exchange.Error: foo"
     MSG
-    assert_equal(<<~MSG.strip, err.detailed_message(highlight: true))
+    expected_no_color = <<~MSG.strip
       #{BOLD}#{msg} (#{BOLD_UNDERLINE}#{name}#{RESET}#{BOLD})#{RESET}
         processed : #{BOLD}"tag OK [Error=\\"Microsoft.Exchange.Error: foo\\""#{RESET}
         remaining : #{BOLD_UNDERLINE}"] done\\r\\n"#{RESET}
@@ -81,6 +91,29 @@ def self.SGR(*attr) = CSI attr.join(?;), ?m
         token     : #{BOLD}:QUOTED#{RESET} => #{BOLD}"Microsoft.Exchange.Error: foo"#{RESET}
     MSG
 
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = nil, nil, "0"
+    assert_equal(expected_no_hl,    err.detailed_message)
+    assert_equal(expected_no_color, err.detailed_message(highlight: true))
+
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = "dumb", "1", nil
+    assert_equal(expected_no_hl,    err.detailed_message)
+    assert_equal(expected_no_color, err.detailed_message(highlight: true))
+
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = "xterm", nil, nil
+    assert_equal(expected_no_color, err.detailed_message)
+    assert_equal(expected_no_hl,    err.detailed_message(highlight: false))
+
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = "dumb", nil, "1"
+    assert_equal(expected_no_color, err.detailed_message)
+    assert_equal(expected_no_hl,    err.detailed_message(highlight: false))
+
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = "unknown", "1", "1"
+    assert_equal(expected_no_color, err.detailed_message)
+    assert_equal(expected_no_hl,    err.detailed_message(highlight: false))
+
+    # reset to nil
+    ENV["TERM"], ENV["NO_COLOR"], ENV["FORCE_COLOR"] = nil, nil, nil
+
     # `parser_state` defaults to `Net::IMAP.debug`:
     Net::IMAP.debug = false
     assert_equal("#{msg} (#{name})", err.detailed_message)