module Puppet::Util::Errors

Some helper methods for throwing and populating errors.

@api public

Public Class Methods

error_location(file, line=nil, column=nil) click to toggle source

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

@param file [String] the file path for the error (nil or “”, for not known) @param line [String] the line number for the error (nil or “”, for not known) @param column [String] the column number for the error (nil or “”, for not known) @return [String] description of file, line, and column

   # File lib/puppet/util/errors.rb
42 def self.error_location(file, line=nil, column=nil)
43   file = nil if (file.is_a?(String) && file.empty?)
44   line = nil if (line.is_a?(String) && line.empty?)
45   column = nil if (column.is_a?(String) && column.empty?)
46   if file and line and column
47     _("(file: %{file}, line: %{line}, column: %{column})") % { file: file, line: line, column: column }
48   elsif file and line
49     _("(file: %{file}, line: %{line})") % { file: file, line: line }
50   elsif line and column
51     _("(line: %{line}, column: %{column})") % { line: line, column: column }
52   elsif line
53     _("(line: %{line})") % { line: line }
54   elsif file
55     _("(file: %{file})") % { file: file }
56   else
57     ''
58   end
59 end
error_location_with_space(file, line=nil, column=nil) click to toggle source

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

@param file [String] the file path for the error (nil or “”, for not known) @param line [String] the line number for the error (nil or “”, for not known) @param column [String] the column number for the error (nil or “”, for not known) @return [String] description of file, line, and column

   # File lib/puppet/util/errors.rb
70 def self.error_location_with_space(file, line=nil, column=nil)
71   error_location_str = error_location(file, line, column)
72   if error_location_str.empty?
73     ''
74   else
75     ' ' + error_location_str
76   end
77 end
error_location_with_unknowns(file, line) click to toggle source

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

@param file [String] the file path for the error (nil or “”, for not known) @param line [String] the line number for the error (nil or “”, for not known) @return [String] description of file, and line

   # File lib/puppet/util/errors.rb
85 def self.error_location_with_unknowns(file, line)
86   file = nil if (file.is_a?(String) && file.empty?)
87   line = nil if (line.is_a?(String) && line.empty?)
88   file = _('unknown') unless file
89   line = _('unknown') unless line
90   error_location(file, line)
91 end

Public Instance Methods

adderrorcontext(error, other = nil) click to toggle source

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.

@param error [Exception] exception that is populated with info @param other [Exception] original exception, source of backtrace info @return [Exception] error parameter

   # File lib/puppet/util/errors.rb
22 def adderrorcontext(error, other = nil)
23   error.line ||= self.line if error.respond_to?(:line=) and self.respond_to?(:line) and self.line
24   error.file ||= self.file if error.respond_to?(:file=) and self.respond_to?(:file) and self.file
25   error.original ||= other if error.respond_to?(:original=)
26 
27   error.set_backtrace(other.backtrace) if other and other.respond_to?(:backtrace)
28   # It is not meaningful to keep the wrapped exception since its backtrace has already
29   # been adopted by the error. (The instance variable is private for good reasons).
30   error.instance_variable_set(:@original, nil)
31   error
32 end
devfail(msg) click to toggle source

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

@param msg [String] message used in raised error @raise [Puppet::DevError] always raised with the supplied message

   # File lib/puppet/util/errors.rb
10 def devfail(msg)
11   self.fail(Puppet::DevError, msg)
12 end
error_context() click to toggle source

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

@return [String] description of file and line with a leading space

   # File lib/puppet/util/errors.rb
97 def error_context
98   Puppet::Util::Errors.error_location_with_space(file, line)
99 end
exceptwrap(options = {}) { || ... } click to toggle source

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

@param options [Hash<Symbol,Object>] options used to create error @option options [Class] :type error type to raise, defaults to

Puppet::DevError

@option options [String] :message message to use in error, default mentions

the name of this class

@raise [Puppet::Error] re-raised with extra context if the block raises it @raise [Error] of type options, when the block raises other

exceptions
    # File lib/puppet/util/errors.rb
112 def exceptwrap(options = {})
113   options[:type] ||= Puppet::DevError
114   begin
115     return yield
116   rescue Puppet::Error => detail
117     raise adderrorcontext(detail)
118   rescue => detail
119     message = options[:message] || _("%{klass} failed with error %{error_type}: %{detail}") % { klass: self.class, error_type: detail.class, detail: detail }
120 
121     error = options[:type].new(message)
122     # We can't use self.fail here because it always expects strings,
123     # not exceptions.
124     raise adderrorcontext(error, detail)
125   end
126 
127   retval
128 end
fail(*args) click to toggle source

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

@overload fail(message, ..)

Throw a Puppet::Error with a message concatenated from the given
arguments.
@param [String] message error message(s)

@overload fail(error_klass, message, ..)

Throw an exception of type error_klass with a message concatenated from
the given arguments.
@param [Class] type of error
@param [String] message error message(s)

@overload fail(error_klass, message, ..)

Throw an exception of type error_klass with a message concatenated from
the given arguments.
@param [Class] type of error
@param [String] message error message(s)
@param [Exception] original exception, source of backtrace info
    # File lib/puppet/util/errors.rb
147 def fail(*args)
148   if args[0].is_a?(Class)
149     type = args.shift
150   else
151     type = Puppet::Error
152   end
153 
154   other = args.count > 1 ? args.pop : nil
155   error = adderrorcontext(type.new(args.join(" ")), other)
156 
157   raise error
158 end