reporter

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
  • func Error(span ast.SourceSpan, err error) ErrorWithPos
  • func Errorf(span ast.SourceSpan, format string, args ...interface{}) ErrorWithPos
• type Handler
  • func NewHandler(rep Reporter) *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
  • func NewReporter(errs ErrorReporter, warnings WarningReporter) Reporter
• type SymbolRedeclaredError
  • func SymbolRedeclared(name string, otherDeclaration ast.SourceSpan) SymbolRedeclaredError
  • func (e SymbolRedeclaredError) Error() string
• type WarningReporter

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.

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
	// GetPosition returns the source position that caused the underlying error.
	GetPosition() ast.SourceSpan
	// 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

func NewHandler(rep Reporter) *Handler

NewHandler creates a new Handler that reports errors and warnings using the given reporter.

func (*Handler) Error

func (h *Handler) Error() 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

func (h *Handler) HandleError(err error) error

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

func (h *Handler) ReporterError() error

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

func (h *Handler) SubHandler() *Handler

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 SymbolRedeclaredError

type SymbolRedeclaredError struct {
	OtherDeclaration ast.SourceSpan
	// contains filtered or unexported fields
}

func SymbolRedeclared

func SymbolRedeclared(name string, otherDeclaration ast.SourceSpan) SymbolRedeclaredError

func (SymbolRedeclaredError) Error

func (e SymbolRedeclaredError) Error() string

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.