Module: Puppet::Util::Errors

Overview

Some helper methods for throwing and populating errors.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.error_location(file, line = nil, column = nil) ⇒ String

Return a human-readable string of this object's file, line, and pos attributes, if set.

Parameters:

  • file (String)

    the file path for the error (nil or “”, for not known)

  • line (String) (defaults to: nil)

    the line number for the error (nil or “”, for not known)

  • column (String) (defaults to: nil)

    the column number for the error (nil or “”, for not known)

Returns:

  • (String)

    description of file, line, and column


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# File 'lib/puppet/util/errors.rb', line 42

def self.error_location(file, line=nil, column=nil)
  file = nil if (file.is_a?(String) && file.empty?)
  line = nil if (line.is_a?(String) && line.empty?)
  column = nil if (column.is_a?(String) && column.empty?)
  if file and line and column
    _("(file: %{file}, line: %{line}, column: %{column})") % { file: file, line: line, column: column }
  elsif file and line
    _("(file: %{file}, line: %{line})") % { file: file, line: line }
  elsif line and column
    _("(line: %{line}, column: %{column})") % { line: line, column: column }
  elsif line
    _("(line: %{line})") % { line: line }
  elsif file
    _("(file: %{file})") % { file: file }
  else
    ''
  end
end

.error_location_with_space(file, line = nil, column = nil) ⇒ String

Return a human-readable string of this object's file, line, and pos attributes, with a proceeding space in the output if set.

Parameters:

  • file (String)

    the file path for the error (nil or “”, for not known)

  • line (String) (defaults to: nil)

    the line number for the error (nil or “”, for not known)

  • column (String) (defaults to: nil)

    the column number for the error (nil or “”, for not known)

Returns:

  • (String)

    description of file, line, and column


70
71
72
73
74
75
76
77
# File 'lib/puppet/util/errors.rb', line 70

def self.error_location_with_space(file, line=nil, column=nil)
  error_location_str = error_location(file, line, column)
  if error_location_str.empty?
    ''
  else
    ' ' + error_location_str
  end
end

.error_location_with_unknowns(file, line) ⇒ String

Return a human-readable string of this object's file and line where unknown entries are listed as 'unknown'

Parameters:

  • file (String)

    the file path for the error (nil or “”, for not known)

  • line (String)

    the line number for the error (nil or “”, for not known)

Returns:

  • (String)

    description of file, and line


85
86
87
88
89
90
91
# File 'lib/puppet/util/errors.rb', line 85

def self.error_location_with_unknowns(file, line)
  file = nil if (file.is_a?(String) && file.empty?)
  line = nil if (line.is_a?(String) && line.empty?)
  file = _('unknown') unless file
  line = _('unknown') unless line
  error_location(file, line)
end

Instance Method Details

#adderrorcontext(error, other = nil) ⇒ Exception

Add line and file info to the supplied exception if info is available from this object, is appropriately populated and the supplied exception supports it. When other is supplied, the backtrace will be copied to the error object and the 'original' will be dropped from the error.

Parameters:

  • error (Exception)

    exception that is populated with info

  • other (Exception) (defaults to: nil)

    original exception, source of backtrace info

Returns:

  • (Exception)

    error parameter


22
23
24
25
26
27
28
29
30
31
32
# File 'lib/puppet/util/errors.rb', line 22

def adderrorcontext(error, other = nil)
  error.line ||= self.line if error.respond_to?(:line=) and self.respond_to?(:line) and self.line
  error.file ||= self.file if error.respond_to?(:file=) and self.respond_to?(:file) and self.file
  error.original ||= other if error.respond_to?(:original=)

  error.set_backtrace(other.backtrace) if other and other.respond_to?(:backtrace)  # It is not meaningful to keep the wrapped exception since its backtrace has already
  # been adopted by the error. (The instance variable is private for good reasons).

  error.instance_variable_set(:@original, nil)
  error
end

#devfail(msg) ⇒ Object

Throw a Puppet::DevError with the specified message. Used for unknown or internal application failures.

Parameters:

  • msg (String)

    message used in raised error

Raises:


10
11
12
# File 'lib/puppet/util/errors.rb', line 10

def devfail(msg)
  self.fail(Puppet::DevError, msg)
end

#error_contextString

Return a human-readable string of this object's file and line attributes, if set.

Returns:

  • (String)

    description of file and line with a leading space


97
98
99
# File 'lib/puppet/util/errors.rb', line 97

def error_context
  Puppet::Util::Errors.error_location_with_space(file, line)
end

#exceptwrap(options = {}) ⇒ Object

Wrap a call in such a way that we always throw the right exception and keep as much context as possible.

Parameters:

  • options (Hash<Symbol,Object>) (defaults to: {})

    options used to create error

Options Hash (options):

  • :type (Class)

    error type to raise, defaults to Puppet::DevError

  • :message (String)

    message to use in error, default mentions the name of this class

Raises:

  • (Puppet::Error)

    re-raised with extra context if the block raises it

  • (Error)

    of type options, when the block raises other exceptions


112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
# File 'lib/puppet/util/errors.rb', line 112

def exceptwrap(options = {})
  options[:type] ||= Puppet::DevError
  begin
    return yield
  rescue Puppet::Error => detail
    raise adderrorcontext(detail)
  rescue => detail
    message = options[:message] || _("%{klass} failed with error %{error_type}: %{detail}") % { klass: self.class, error_type: detail.class, detail: detail }

    error = options[:type].new(message)    # We can't use self.fail here because it always expects strings,
    # not exceptions.

    raise adderrorcontext(error, detail)
  end

  retval
end

#fail(message, ..) ⇒ Object #fail(error_klass, message, ..) ⇒ Object #fail(error_klass, message, ..) ⇒ Object

Throw an error, defaulting to a Puppet::Error.

Overloads:

  • #fail(message, ..) ⇒ Object

    Throw a Puppet::Error with a message concatenated from the given arguments.

    Parameters:

    • message (String)

      error message(s)

  • #fail(error_klass, message, ..) ⇒ Object

    Throw an exception of type error_klass with a message concatenated from the given arguments.

    Parameters:

    • type (Class)

      of error

    • message (String)

      error message(s)

  • #fail(error_klass, message, ..) ⇒ Object

    Throw an exception of type error_klass with a message concatenated from the given arguments.

    Parameters:

    • type (Class)

      of error

    • message (String)

      error message(s)

    • original (Exception)

      exception, source of backtrace info


147
148
149
150
151
152
153
154
155
156
157
158
# File 'lib/puppet/util/errors.rb', line 147

def fail(*args)
  if args[0].is_a?(Class)
    type = args.shift
  else
    type = Puppet::Error
  end

  other = args.count > 1 ? args.pop : nil
  error = adderrorcontext(type.new(args.join(" ")), other)

  raise error
end