Exception: Net::IMAP::ResponseParseError

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Error`, StandardError
Instance Chain: self, `Error`, StandardError
Inherits:	Net::IMAP::Error Object StandardError Net::IMAP::Error Net::IMAP::ResponseParseError
Defined in:	lib/net/imap/errors.rb

Overview

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.

Constant Summary

ESC_COLORS = private

ANSI highlights, with color

# File 'lib/net/imap/errors.rb', line 87

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

ESC_NO_COLOR = private

ANSI highlights, but no colors

# File 'lib/net/imap/errors.rb', line 77

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

ESC_NO_HL = private

returns "" for all highlights

# File 'lib/net/imap/errors.rb', line 59
```
Hash.new("").freeze
```

Class Method Summary

.new(message = "unspecified parse error", parser_class: Net::IMAP::ResponseParser, parser_state: nil, string: parser_state&.at(0), lex_state: parser_state&.at(1), pos: parser_state&.at(2), token: parser_state&.at(3)) ⇒ ResponseParseError constructor

Instance Attribute Summary

#lex_state readonly

The parser's lex state.
#parser_class readonly

ResponseParser, unless a custom parser produced the error.
#pos readonly

The parser's byte position in #string when the error was raised.
#string readonly

The full raw response string which was being parsed.
#token readonly

The last lexed token.

Instance Method Summary

#==(other)

Returns true when all attributes are equal, except for #backtrace and #backtrace_locations which are replaced with #parser_methods.
#detailed_message(parser_state: Net::IMAP.debug, parser_backtrace: false, highlight: default_highlight_from_env, highlight_no_color: (ENV["NO_COLOR"] || "") != "")

When parser_state is true, debug info about the parser state is included.
#parser_methods

Lists the methods (from #backtrace_locations or #backtrace) called on parser_class (since ruby 3.4) or which have "net/imap/response_parser" in the path (before ruby 3.4).
#processed_string
#remaining_string
#default_highlight_from_env private
#normalize_backtrace private
#normalized_parser_backtrace private

Constructor Details

.new(message = "unspecified parse error", parser_class: Net::IMAP::ResponseParser, parser_state: nil, string: parser_state&.at(0), lex_state: parser_state&.at(1), pos: parser_state&.at(2), token: parser_state&.at(3)) ⇒ `ResponseParseError`

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 126


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

Instance Attribute Details

#lex_state (readonly)

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.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 115


attr_reader :lex_state

#parser_class (readonly)

ResponseParser, unless a custom parser produced the error.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 100


attr_reader :parser_class

#pos (readonly)

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.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 109


attr_reader :pos

#string (readonly)

The full raw response string which was being parsed.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 103


attr_reader :string

#token (readonly)

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.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 124


attr_reader :token

Instance Method Details

#==(other)

Returns true when all attributes are equal, except for #backtrace and #backtrace_locations which are replaced with #parser_methods. This allows deserialized errors to be compared.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 197


def ==(other)
  return false if self.class != other.class
  methods       = parser_methods
  other_methods = other.parser_methods
  message     == other.message &&
    methods   == other_methods &&
    string    == other.string &&
    pos       == other.pos &&
    lex_state == other.lex_state &&
    token     == other.token
end

#default_highlight_from_env (private)

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 239


def default_highlight_from_env
  (ENV["FORCE_COLOR"] || "") !~ /\A(?:0|)\z/ ||
    (ENV["TERM"] || "") !~ /\A(?:dumb|unknown|)\z/i
end

#detailed_message(parser_state: Net::IMAP.debug, parser_backtrace: false, highlight: default_highlight_from_env, highlight_no_color: (ENV["NO_COLOR"] || "") != "")

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 ::Net::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.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 155


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
    normalized_parser_backtrace.each do |idx, path, lineno, label, base_label|
      msg << "\n  %s: %s (%s:%d)" % [
        hl["%{key}caller[%{/key}%{idx}%%2d%{/idx}%{key}]%{/key}"] % idx,
        hl["%{label}%%-30s%{/label}"] % base_label,
        File.basename(path, ".rb"), lineno
      ]
    end
  end
  msg
rescue => error
  msg ||= super.dup
  msg << "\n  BUG in %s#%s: %s" % [self.class, __method__,
                                   error.detailed_message]
  msg
end

#normalize_backtrace (private)

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 231


def normalize_backtrace
  (backtrace_locations&.each_with_index&.map {|loc, idx|
    [idx, loc.path, loc.lineno, loc.label, loc.base_label]
  } || backtrace&.each_with_index&.map {|bt, idx|
    [idx, *bt.match(/\A(\S):(\d):in [`'](.*?([\w]+[?!]?))'\z/)&.captures]
  } || [])
end

#normalized_parser_backtrace (private)

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 217


def normalized_parser_backtrace
  normalize_backtrace
    .take_while {|_, _, _, _, base_label| base_label != "parse" }
    .reject {|_, _, _, _, base_label| base_label.nil? }
    .reject {|_, _, _, _, base_label| base_label.include? "parse_error" }
    .select {|_, path, _, label, _|
      if label.include?("#") # => Class#method, since ruby 3.4
        label.include?(parser_class.name)
      else
        path.include?("net/imap/response_parser")
      end
    }
end

#parser_methods

Lists the methods (from #backtrace_locations or #backtrace) called on 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 ::Net::IMAP grammar.

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 213


def parser_methods = normalized_parser_backtrace.map(&:last)

#processed_string

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 191


def processed_string = string && pos && string[...pos]

#remaining_string

[ GitHub ]

# File 'lib/net/imap/errors.rb', line 192


def remaining_string = string && pos && string[pos..]

Exception: Net::IMAP::ResponseParseError

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(message = "unspecified parse error", parser_class: Net::IMAP::ResponseParser, parser_state: nil, string: parser_state&.at(0), lex_state: parser_state&.at(1), pos: parser_state&.at(2), token: parser_state&.at(3)) ⇒ ResponseParseError

Instance Attribute Details

#lex_state (readonly)

#parser_class (readonly)

#pos (readonly)

#string (readonly)

#token (readonly)

Instance Method Details

#==(other)

#default_highlight_from_env (private)

#detailed_message(parser_state: Net::IMAP.debug, parser_backtrace: false, highlight: default_highlight_from_env, highlight_no_color: (ENV["NO_COLOR"] || "") != "")

#normalize_backtrace (private)

#normalized_parser_backtrace (private)

#parser_methods

#processed_string

#remaining_string

.new(message = "unspecified parse error", parser_class: Net::IMAP::ResponseParser, parser_state: nil, string: parser_state&.at(0), lex_state: parser_state&.at(1), pos: parser_state&.at(2), token: parser_state&.at(3)) ⇒ `ResponseParseError`