clang::ssaf::ErrorBuilder Class Reference

Fluent API for constructing contextual errors. More...

#include "clang/Analysis/Scalable/Support/ErrorBuilder.h"

Public Member Functions
ErrorBuilder &	context (const char *Msg)
	Add context information as a plain string.
template<typename... Args>
ErrorBuilder &	context (const char *Fmt, Args &&...ArgVals)
	Add context information with formatted string.
llvm::Error	build () const
	Build and return the final error.

Static Public Member Functions
template<typename... Args>
static ErrorBuilder	create (std::error_code EC, const char *Fmt, Args &&...ArgVals)
	Create an ErrorBuilder with an error code and formatted message.
template<typename... Args>
static ErrorBuilder	create (std::errc EC, const char *Fmt, Args &&...ArgVals)
	Convenience overload that accepts std::errc instead of std::error_code.
static ErrorBuilder	wrap (llvm::Error E)
	Wrap an existing error and optionally add context.
template<typename... Args>
static void	fatal (const char *Fmt, Args &&...ArgVals)
	Report a fatal error with formatted message and terminate execution.

Detailed Description

Fluent API for constructing contextual errors.

ErrorBuilder allows building error messages with layered context information. Context is added innermost to outermost, and the final error message presents the context in reverse order (outermost first).

Example usage:

return ErrorBuilder::create(std::errc::invalid_argument,
                            "invalid value {0}", value)
    .context("processing field '{0}'", fieldName)
    .context("reading configuration")
    .build();

Definition at line 40 of file ErrorBuilder.h.

Member Function Documentation

build()

llvm::Error clang::ssaf::ErrorBuilder::build

(

)

const

Build and return the final error.

Constructs an llvm::Error with all accumulated context. The context is presented in reverse order: most recent context first, original error message last. Each context layer is separated by a newline.

Returns

An llvm::Error containing the error code and formatted message. Even if no context was added (empty context stack), an error with the stored error code is returned.

Precondition

The ErrorBuilder must have been created via create() or wrap(). Constructing an ErrorBuilder directly is not supported.

Example output:

   ErrorBuilder::create(errc::invalid_argument, "value is 42")
       .context("processing field 'age'")
       .context("reading config")
       .build();
 
// Produces:
// "reading config
//  processing field 'age'
//  value is 42"

Definition at line 54 of file ErrorBuilder.cpp.

References clang::ssaf::ContextSeparator.

Referenced by clang::ssaf::EntityLinker::link(), clang::ssaf::JSONFormat::readTUSummary(), and clang::ssaf::JSONFormat::writeTUSummary().

context() [1/2]

template<typename... Args>

ErrorBuilder & clang::ssaf::ErrorBuilder::context ( const char * Fmt, Args &&... ArgVals )

inline

Add context information with formatted string.

Uses llvm::formatv for formatting. Empty messages (after formatting) are ignored and not added to the context stack.

Parameters

Fmt	Format string (using llvm::formatv syntax).
ArgVals	Arguments for the format string.

Returns

Reference to this ErrorBuilder for method chaining.

Example:

return ErrorBuilder::create(...)
    .context("processing field '{0}'", fieldName)
    .context("at line {0}, column {1}", line, col)
    .build();

Definition at line 150 of file ErrorBuilder.h.

context() [2/2]

ErrorBuilder & clang::ssaf::ErrorBuilder::context

(

const char *

Msg

)

Add context information as a plain string.

Empty strings are ignored and not added to the context stack.

Parameters

Msg	Context message to add. Must be a null-terminated string.

Returns

Reference to this ErrorBuilder for method chaining.

Example:

return ErrorBuilder::create(...)
    .context("reading configuration file")
    .build();

Definition at line 49 of file ErrorBuilder.cpp.

Referenced by clang::ssaf::JSONFormat::readTUSummary(), and clang::ssaf::JSONFormat::writeTUSummary().

create() [1/2]

template<typename... Args>

ErrorBuilder clang::ssaf::ErrorBuilder::create ( std::errc EC, const char * Fmt, Args &&... ArgVals )

inlinestatic

Convenience overload that accepts std::errc instead of std::error_code.

Parameters

EC	The error condition for this error.
Fmt	Format string for the error message.
ArgVals	Arguments for the format string.

Returns

A new ErrorBuilder with the initial error message.

Definition at line 91 of file ErrorBuilder.h.

References create().

create() [2/2]

template<typename... Args>

ErrorBuilder clang::ssaf::ErrorBuilder::create ( std::error_code EC, const char * Fmt, Args &&... ArgVals )

inlinestatic

Create an ErrorBuilder with an error code and formatted message.

Parameters

EC	The error code for this error.
Fmt	Format string for the error message (using llvm::formatv).
ArgVals	Arguments for the format string.

Returns

A new ErrorBuilder with the initial error message.

Example:

return ErrorBuilder::create(std::errc::invalid_argument,
                            "invalid value: {0}", 42)
    .build();

Definition at line 77 of file ErrorBuilder.h.

Referenced by create(), clang::ssaf::EntityLinker::link(), and clang::ssaf::JSONFormat::readTUSummary().

fatal()

template<typename... Args>

void clang::ssaf::ErrorBuilder::fatal ( const char * Fmt, Args &&... ArgVals )

inlinestatic

Report a fatal error with formatted message and terminate execution.

Combines llvm::formatv and llvm::report_fatal_error. This is a static utility method for reporting unrecoverable errors that indicate bugs or corrupted data.

Parameters

Fmt	Format string for the error message (using llvm::formatv).
ArgVals	Arguments for the format string.

Precondition

Fmt must be a valid llvm::formatv format string with the correct number and types of arguments. An invalid format string is undefined behaviour.

Example:

ErrorBuilder::fatal("Entity {0} with {1} linkage already exists",
                    entityId, linkageType);

Definition at line 199 of file ErrorBuilder.h.

References noreturn.

wrap()

ErrorBuilder clang::ssaf::ErrorBuilder::wrap ( llvm::Error E )

static

Wrap an existing error and optionally add context.

Extracts the error code and message(s) from the given error. If multiple errors are joined (via llvm::joinErrors), their messages are combined using " + " separator.

Parameters

E	The error to wrap. Must be a failure (cannot be success).

Returns

A new ErrorBuilder containing the wrapped error information.

Precondition

E must evaluate to true (i.e., must be a failure). Wrapping Error::success() is a programming error and will trigger an assertion failure in debug builds.

Example:

if (auto Err = foo())
  return ErrorBuilder::wrap(std::move(Err))
      .context("while processing file")
      .build();

Definition at line 19 of file ErrorBuilder.cpp.

References clang::ssaf::ErrorSeparator.

Referenced by clang::ssaf::JSONFormat::readTUSummary(), and clang::ssaf::JSONFormat::writeTUSummary().

---

The documentation for this class was generated from the following files:

• include/clang/Analysis/Scalable/Support/ErrorBuilder.h
• lib/Analysis/Scalable/Support/ErrorBuilder.cpp