Documentation
¶
Overview ¶
Package reporter contains the types used for reporting errors from protocompile operations. It contains error types as well as interfaces for reporting and handling errors and warnings.
Index ¶
- Variables
- type ErrorReporter
- type ErrorWithPos
- type Handler
- func (h *Handler) Error() error
- func (h *Handler) HandleError(err error) error
- func (h *Handler) HandleErrorWithPos(span ast.SourceSpan, err error) error
- func (h *Handler) HandleErrorf(span ast.SourceSpan, format string, args ...interface{}) error
- func (h *Handler) HandleWarning(err ErrorWithPos)
- func (h *Handler) HandleWarningWithPos(span ast.SourceSpan, err error)
- func (h *Handler) HandleWarningf(span ast.SourceSpan, format string, args ...interface{})
- func (h *Handler) ReporterError() error
- func (h *Handler) SubHandler() *Handler
- type Reporter
- type WarningReporter
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidSource = errors.New("parse failed: invalid proto source")
ErrInvalidSource is a sentinel error that is returned by compilation and stand-alone compilation steps (such as parsing, linking) when one or more errors is reported but the configured ErrorReporter always returns nil.
Functions ¶
This section is empty.
Types ¶
type ErrorReporter ¶
type ErrorReporter func(err ErrorWithPos) error
ErrorReporter is responsible for reporting the given error. If the reporter returns a non-nil error, parsing/linking will abort with that error. If the reporter returns nil, parsing will continue, allowing the parser to try to report as many syntax and/or link errors as it can find.
type ErrorWithPos ¶
type ErrorWithPos interface {
error
ast.SourceSpan
// GetPosition returns the start source position that caused the underlying error.
GetPosition() ast.SourcePos
// Unwrap returns the underlying error.
Unwrap() error
}
ErrorWithPos is an error about a proto source file that adds information about the location in the file that caused the error.
func Error ¶
func Error(span ast.SourceSpan, err error) ErrorWithPos
Error creates a new ErrorWithPos from the given error and source position.
func Errorf ¶
func Errorf(span ast.SourceSpan, format string, args ...interface{}) ErrorWithPos
Errorf creates a new ErrorWithPos whose underlying error is created using the given message format and arguments (via fmt.Errorf).
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is used by protocompile operations for handling errors and warnings. This type is thread-safe. It uses a mutex to serialize calls to its reporter so that reporter instances do not have to be thread-safe (unless re-used across multiple handlers).
func NewHandler ¶
NewHandler creates a new Handler that reports errors and warnings using the given reporter.
func (*Handler) Error ¶
Error returns the handler result. If any errors have been reported then this returns a non-nil error. If the reporter never returned a non-nil error then ErrInvalidSource is returned. Otherwise, this returns the error returned by the handler's reporter (the same value returned by ReporterError).
func (*Handler) HandleError ¶
HandleError handles the given error. If the given err is an ErrorWithPos, it is reported, and this function returns the error returned by the reporter. If the given err is NOT an ErrorWithPos, the current operation will abort immediately.
If the handler has already aborted (by returning a non-nil error from a prior call to HandleError or HandleErrorf), that same error is returned and the given error is not reported.
func (*Handler) HandleErrorWithPos ¶
func (h *Handler) HandleErrorWithPos(span ast.SourceSpan, err error) error
HandleErrorWithPos handles an error with the given source position.
If the handler has already aborted (by returning a non-nil error from a prior call to HandleError or HandleErrorf), that same error is returned and the given error is not reported.
func (*Handler) HandleErrorf ¶
func (h *Handler) HandleErrorf(span ast.SourceSpan, format string, args ...interface{}) error
HandleErrorf handles an error with the given source position, creating the error using the given message format and arguments.
If the handler has already aborted (by returning a non-nil error from a call to HandleError or HandleErrorf), that same error is returned and the given error is not reported.
func (*Handler) HandleWarning ¶
func (h *Handler) HandleWarning(err ErrorWithPos)
HandleWarning handles the given warning. This will delegate to the handler's configured reporter.
func (*Handler) HandleWarningWithPos ¶
func (h *Handler) HandleWarningWithPos(span ast.SourceSpan, err error)
HandleWarningWithPos handles a warning with the given source position. This will delegate to the handler's configured reporter.
func (*Handler) HandleWarningf ¶
func (h *Handler) HandleWarningf(span ast.SourceSpan, format string, args ...interface{})
HandleWarningf handles a warning with the given source position, creating the actual error value using the given message format and arguments.
func (*Handler) ReporterError ¶
ReporterError returns the error returned by the handler's reporter. If the reporter has either not been invoked (no errors handled) or has not returned any non-nil value, then this returns nil.
func (*Handler) SubHandler ¶
SubHandler returns a "child" of h. Use of a child handler is the same as use of the parent, except that the Error() and ReporterError() functions only report non-nil for errors that were reported using the child handler. So errors reported directly to the parent or to a different child handler won't be returned. This is useful for making concurrent access to the handler more deterministic: if a child handler is only used from one goroutine, its view of reported errors is consistent and unimpacted by concurrent operations.
type Reporter ¶
type Reporter interface {
// Error is called when the given error is encountered and needs to be
// reported to the calling program. This signature matches ErrorReporter
// because it has the same semantics. If this function returns non-nil
// then the operation will abort immediately with the given error. But
// if it returns nil, the operation will continue, reporting more errors
// as they are encountered. If the reporter never returns non-nil then
// the operation will eventually fail with ErrInvalidSource.
Error(ErrorWithPos) error
// Warning is called when the given warnings is encountered and needs to be
// reported to the calling program. Despite the argument being an error
// type, a warning will never cause the operation to abort or fail (unless
// the reporter's implementation of this method panics).
Warning(ErrorWithPos)
}
Reporter is a type that handles reporting both errors and warnings. A reporter does not need to be thread-safe. Safe concurrent access is managed by a Handler.
func NewReporter ¶
func NewReporter(errs ErrorReporter, warnings WarningReporter) Reporter
NewReporter creates a new reporter that invokes the given functions on error or warning.
type WarningReporter ¶
type WarningReporter func(ErrorWithPos)
WarningReporter is responsible for reporting the given warning. This is used for indicating non-error messages to the calling program for things that do not cause the parse to fail but are considered bad practice. Though they are just warnings, the details are supplied to the reporter via an error type.
Source Files