net-imap 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc6f6d65e2f5092b38316ed4d381551838dd412a5b376c06359225e8f53a020c
-  data.tar.gz: d5daf47c70a868650687f7db3d1a1e074555a634708c16792e19f1cb53f8cc83
+  metadata.gz: 4249dc5d175bd3ae3a3b3b79e0f368e674ec96045510a8b504e829feefb54f3d
+  data.tar.gz: 6adbee15b0303b36ec1c574991d4bdbf518bcd5621c6b668f05df0bc201ba50a
 SHA512:
-  metadata.gz: 1aeb682e73a666591079aac75c4325f22079dfbf61dbe71df135059b9087890633c31fd036e61757a217f1b1ff3e1d3771801a7ec6f3817646a0f8d2c0896386
-  data.tar.gz: 8cd118d9943b83010dd2f4916ab7641e120743991d3bc06062c4eb286098d1af8af05d86854b3e44235a0b3263b801db1cf9a7d64ac3140d89eda1aca086e6cd
+  metadata.gz: a20c230ac3977d9acc09bc964badc60acbedaca84246d1ce67787c78443cdea350ade6907e58b61a5c9f09bf3b12e5e57cd319ef82a096c3780f97dc7017ed31
+  data.tar.gz: 68ab8b48664998bbf05d5367fea4e5b06e3ba3b2d4e48ba8ae026069060b23f7dafaf7ecf2681fc5aa4ff0f134e55d9399ca51456ff3a7ec718ba829629866b7

data/lib/net/imap/config/attr_accessors.rb

@@ -27,24 +27,23 @@ module Net
 
         def self.attr_accessor(name) # :nodoc: internal API
           name = name.to_sym
+          raise ArgumentError, "already defined #{name}" if attributes.include?(name)
+          attributes << name
           def_delegators :data, name, :"#{name}="
         end
 
-        def self.attributes
-          instance_methods.grep(/=\z/).map { _1.to_s.delete_suffix("=").to_sym }
-        end
-        private_class_method :attributes
+        # An array of Config attribute names
+        singleton_class.attr_reader :attributes
+        @attributes = []
 
         def self.struct # :nodoc: internal API
-          unless defined?(self::Struct)
-            const_set :Struct, Struct.new(*attributes)
-          end
-          self::Struct
+          attributes.freeze
+          Struct.new(*attributes)
         end
 
         def initialize # :notnew:
           super()
-          @data = AttrAccessors.struct.new
+          @data = Config::Struct.new
         end
 
         # Freezes the internal attributes struct, in addition to +self+.

data/lib/net/imap/config/attr_inheritance.rb

@@ -66,11 +66,61 @@ module Net
         # inherited, or +false+ if any of them are overriden.  When no +attrs+
         # are given, returns +true+ if *all* attributes are inherited, or
         # +false+ if any attribute is overriden.
+        #
+        # Related: #overrides?
         def inherited?(*attrs)
           attrs = data.members if attrs.empty?
           attrs.all? { data[_1] == INHERITED }
         end
 
+        # :call-seq:
+        #   inherits_defaults?(*attrs) -> true | Rational | nil | false
+        #
+        # Returns whether all +attrs+ are inherited from a default config.
+        # When no +attrs+ are given, returns whether *all* attributes are
+        # inherited from a default config.
+        #
+        # Returns +true+ when all attributes inherit from Config.default, the
+        # version number (as a Rational) when all attributes inherit from a
+        # versioned default (see Config@Versioned+defaults), +nil+ if any
+        # attributes inherit from Config.global overrides (but not from
+        # non-global ancestors), or +false+ when any attributes have been
+        # overridden by +self+ or an ancestor (besides global or default
+        # configs),
+        #
+        # Related: #overrides?
+        def inherits_defaults?(*attrs)
+          if equal?(Config.default)
+            true
+          elsif equal?(Config.global)
+            true if inherited?(*attrs)
+          elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
+            attrs  = DEFAULT_TO_INHERIT if attrs.empty?
+            attrs &= DEFAULT_TO_INHERIT
+            (attrs.empty? || parent.inherits_defaults?(*attrs)) && v
+          else
+            inherited?(*attrs) && parent.inherits_defaults?(*attrs)
+          end
+        end
+
+        # :call-seq:
+        #   overrides?(attr)   -> true or false
+        #   overrides?(*attrs) -> true or false
+        #   overrides?         -> true or false
+        #
+        # Returns +true+ if +attr+ is defined on this config and not inherited
+        # from #parent.
+        #
+        # When multiple +attrs+ are given, returns +true+ if
+        # *any* of them are defined on +self+.  When no +attrs+ are given,
+        # returns +true+ if *any* attribute is overriden.
+        #
+        # Related: #inherited?
+        def overrides?(*attrs)
+          attrs = data.members if attrs.empty?
+          attrs.any? { data[_1] != INHERITED }
+        end
+
         # :call-seq:
         #   reset -> self
         #   reset(attr) -> attribute value

data/lib/net/imap/config/attr_version_defaults.rb

@@ -24,7 +24,7 @@ module Net
         VERSIONS = ((0.0r..FUTURE_VERSION) % 0.1r).to_a.freeze
 
         # See Config.version_defaults.
-        singleton_class.attr_accessor :version_defaults
+        singleton_class.attr_reader :version_defaults
 
         @version_defaults = Hash.new {|h, k|
           # NOTE: String responds to both so the order is significant.
@@ -59,10 +59,6 @@ module Net
         end
 
         def self.compile_version_defaults!
-          # Temporarily assign Config.default, enabling #load_defaults(:default)
-          version_defaults[:default] = Config.default
-          # Use #load_defaults so some attributes are inherited from global.
-          version_defaults[:default] = Config.new.load_defaults(:default).freeze
           version_defaults[0.0r]     = Config[version_defaults.fetch(0.0r)]
 
           VERSIONS.each_cons(2) do |prior, version|
@@ -81,6 +77,7 @@ module Net
 
           version_defaults[:original] = Config[0.0r]
           version_defaults[:current]  = Config[CURRENT_VERSION]
+          version_defaults[:default]  = Config[CURRENT_VERSION]
           version_defaults[:next]     = Config[NEXT_VERSION]
           version_defaults[:future]   = Config[FUTURE_VERSION]
 

data/lib/net/imap/config.rb

@@ -578,7 +578,6 @@ module Net
         if    equal? Config.default   then "#{Config}.default"
         elsif equal? Config.global    then "#{Config}.global"
         elsif equal? Config[0.0r]     then "#{Config}[:original]"
-        elsif equal? Config[:default] then "#{Config}[:default]"
         elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
           "%s[%0.1f]" % [Config, v]
         else
@@ -631,6 +630,7 @@ module Net
         to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end
 
+      Struct   = AttrAccessors.struct
       @default = AttrVersionDefaults.compile_default!
       @global  = default.new
       AttrVersionDefaults.compile_version_defaults!

data/lib/net/imap/errors.rb

@@ -51,7 +51,159 @@ module Net
     end
 
     # Error raised when a response from the server is non-parsable.
+    #
+    # NOTE: Parser attributes are provided for debugging and inspection only.
+    # Their names and semantics may change incompatibly in any release.
     class ResponseParseError < Error
+      # returns "" for all highlights
+      ESC_NO_HL = Hash.new("").freeze
+      private_constant :ESC_NO_HL
+
+      # Translates hash[:"/foo"] to hash[:reset] when hash.key?(:foo), else ""
+      #
+      # TODO: DRY this up with Config::AttrTypeCoercion.safe
+      if defined?(::Ractor.shareable_proc)
+        default_highlight = Ractor.shareable_proc {|hash, key|
+          %r{\A/(.+)} =~ key && hash.key?($1.to_sym) ? hash[:reset] : ""
+        }
+      else
+        default_highlight = nil.instance_eval { Proc.new {|hash, key|
+          %r{\A/(.+)} =~ key && hash.key?($1.to_sym) ? hash[:reset] : ""
+        } }
+        ::Ractor.make_shareable(default_highlight) if defined?(::Ractor)
+      end
+
+      # ANSI highlights, but no colors
+      ESC_NO_COLOR = Hash.new(&default_highlight).update(
+        reset: "\e[m",
+        val:   "\e[1m",   # bold
+        alt:   "\e[1;4m", # bold and underlined
+        sym:   "\e[1m",   # bold
+        label: "\e[1m",   # bold
+      ).freeze
+      private_constant :ESC_NO_COLOR
+
+      # ANSI highlights, with color
+      ESC_COLORS = Hash.new(&default_highlight).update(
+        reset: "\e[m",
+        key:   "\e[95m",      # bright magenta
+        idx:   "\e[34m",      # blue
+        val:   "\e[36;40m",   # cyan on black (to ensure contrast)
+        alt:   "\e[1;33;40m", # bold; yellow on black
+        sym:   "\e[33;40m",   # yellow on black
+        label: "\e[1m",       # bold
+        nil:   "\e[35m",      # magenta
+      ).freeze
+      private_constant :ESC_COLORS
+
+      # Net::IMAP::ResponseParser, unless a custom parser produced the error.
+      attr_reader :parser_class
+
+      # The full raw response string which was being parsed.
+      attr_reader :string
+
+      # The parser's byte position in #string when the error was raised.
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :pos
+
+      # The parser's lex state
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :lex_state
+
+      # The last lexed token
+      #
+      # May be +nil+ when the parser has accepted the last token and peeked at
+      # the next byte without generating a token.
+      #
+      # _NOTE:_ This attribute is provided for debugging and inspection only.
+      # Its name and semantics may change incompatibly in any release.
+      attr_reader :token
+
+      def initialize(message = "unspecified parse error",
+                     parser_class: Net::IMAP::ResponseParser,
+                     parser_state: nil,
+                     string:    parser_state&.at(0), # see ParserUtils#parser_state
+                     lex_state: parser_state&.at(1), # see ParserUtils#parser_state
+                     pos:       parser_state&.at(2), # see ParserUtils#parser_state
+                     token:     parser_state&.at(3)) # see ParserUtils#parser_state
+        @parser_class = parser_class
+        @string    = string
+        @pos       = pos
+        @lex_state = lex_state
+        @token     = token
+        super(message)
+      end
+
+      # When +parser_state+ is true, debug info about the parser state is
+      # included.  Defaults to the value of Net::IMAP.debug.
+      #
+      # When +parser_backtrace+ is true, a simplified backtrace is included,
+      # 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.
+      #
+      # By default, +highlight+ uses colors from the basic ANSI palette.  When
+      # +highlight_no_color+ is true or the +NO_COLOR+ environment variable is
+      # not empty, only monochromatic highlights are used: bold, underline, etc.
+      def detailed_message(parser_state: Net::IMAP.debug,
+                           parser_backtrace: false,
+                           highlight: default_highlight_from_env,
+                           highlight_no_color: (ENV["NO_COLOR"] || "") != "",
+                           **)
+        return super unless parser_state || parser_backtrace
+        msg = super.dup
+        esc = !highlight ? ESC_NO_HL : highlight_no_color ? ESC_NO_COLOR : ESC_COLORS
+        hl  = ->str { str % esc }
+        val = ->str, val { hl[val.nil? ? "%{nil}%%p%{/nil}" : str] % val }
+        if parser_state && (string || pos || lex_state || token)
+          msg << hl["\n  %{key}processed %{/key}: "] << val["%{val}%%p%{/val}", processed_string]
+          msg << hl["\n  %{key}remaining %{/key}: "] << val["%{alt}%%p%{/alt}", remaining_string]
+          msg << hl["\n  %{key}pos       %{/key}: "] << val["%{val}%%p%{/val}", pos]
+          msg << hl["\n  %{key}lex_state %{/key}: "] << val["%{sym}%%p%{/sym}", lex_state]
+          msg << hl["\n  %{key}token     %{/key}: "] << val[
+            "%{sym}%%<symbol>p%{/sym} => %{val}%%<value>p%{/val}", token&.to_h
+          ]
+        end
+        if parser_backtrace
+          backtrace_locations&.each_with_index do |loc, idx|
+            next  if    loc.base_label.include? "parse_error"
+            break if    loc.base_label == "parse"
+            if loc.label.include?("#") # => Class#method, since ruby 3.4
+              next unless loc.label&.include?(parser_class.name)
+            else
+              next unless loc.path&.include?("net/imap/response_parser")
+            end
+            msg << "\n  %s: %s (%s:%d)" % [
+              hl["%{key}caller[%{/key}%{idx}%%2d%{/idx}%{key}]%{/key}"] % idx,
+              hl["%{label}%%-30s%{/label}"] % loc.base_label,
+              File.basename(loc.path, ".rb"), loc.lineno
+            ]
+          end
+        end
+        msg
+      rescue => error
+        msg ||= super.dup
+        msg << "\n  BUG in %s#%s: %s" % [self.class, __method__,
+                                         error.detailed_message]
+        msg
+      end
+
+      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

data/lib/net/imap/response_parser/parser_utils.rb

@@ -215,29 +215,20 @@ module Net
           @token = nil
         end
 
-        def parse_error(fmt, *args)
-          msg = format(fmt, *args)
-          if config.debug?
-            local_path = File.dirname(__dir__)
-            tok = @token ? "%s: %p" % [@token.symbol, @token.value] : "nil"
-            warn "%s %s: %s"        % [self.class, __method__, msg]
-            warn "  tokenized : %s" % [@str[...@pos].dump]
-            warn "  remaining : %s" % [@str[@pos..].dump]
-            warn "  @lex_state: %s" % [@lex_state]
-            warn "  @pos      : %d" % [@pos]
-            warn "  @token    : %s" % [tok]
-            caller_locations(1..20).each_with_index do |cloc, idx|
-              next unless cloc.path&.start_with?(local_path)
-              warn "  caller[%2d]: %-30s (%s:%d)" % [
-                idx,
-                cloc.base_label,
-                File.basename(cloc.path, ".rb"),
-                cloc.lineno
-              ]
-            end
-          end
-          raise ResponseParseError, msg
-        end
+        def parse_error(fmt, *args) = raise exception format(fmt, *args)
+
+        def exception(message) = ResponseParseError.new(
+          message, parser_state:, parser_class: self.class
+        )
+
+        # This can be used to backtrack after a parse error, and re-attempt to
+        # parse using a fallback.
+        #
+        # NOTE: Reckless backtracking could lead to O(n²) situations, so this
+        # should very rarely be used.  Ideally, fallbacks should not backtrack.
+        def restore_state(state) = (@lex_state, @pos, @token = state)
+        def current_state        = [@lex_state, @pos, @token]
+        def parser_state         = [@str, *current_state]
 
       end
     end

data/lib/net/imap/response_parser.rb

@@ -38,6 +38,11 @@ module Net
         @lex_state = EXPR_BEG
         @token = nil
         return response
+      rescue ResponseParseError => error
+        if config.debug?
+          warn error.detailed_message(parser_state: true, parser_backtrace: true)
+        end
+        raise
       end
 
       private
@@ -1883,12 +1888,17 @@ module Net
       # We leniently re-interpret this as
       #   resp-text       = ["[" resp-text-code "]" [SP [text]] / [text]
       def resp_text
-        if lbra?
-          code = resp_text_code; rbra
-          ResponseText.new(code, SP? && text? || "")
-        else
-          ResponseText.new(nil, text? || "")
+        begin
+          state = current_state
+          if lbra?
+            code = resp_text_code; rbra
+            return ResponseText.new(code, SP? && text? || "")
+          end
+        rescue ResponseParseError => error
+          raise if /\buid-set\b/i.match? error.message
+          restore_state state
         end
+        ResponseText.new(nil, text? || "")
       end
 
       # RFC3501 (See https://www.rfc-editor.org/errata/rfc3501):
@@ -2017,13 +2027,18 @@ module Net
         CopyUID(validity, src_uids, dst_uids)
       end
 
+      PARSER_PATH = File.expand_path(__FILE__).delete_suffix(".rb")
+
       # TODO: remove this code in the v0.6.0 release
       def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
         return unless config.parser_use_deprecated_uidplus_data
+        uplevel = caller_locations
+          .find_index { !_1.path.start_with?(PARSER_PATH) }
+          &.succ
         warn("#{Config}#parser_use_deprecated_uidplus_data is ignored " \
              "since v0.6.0.  Disable this warning by setting " \
              "config.parser_use_deprecated_uidplus_data = false.",
-             category: :deprecated, uplevel: 9)
+             category: :deprecated, uplevel:)
         nil
       end
 

data/lib/net/imap.rb

@@ -788,7 +788,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.6.2"
+    VERSION = "0.6.3"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.3
 platform: ruby
 authors:
 - Shugo Maeda
@@ -129,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []