Documentation
¶
Overview ¶
Package xerrors provides contextual error chains and structured error results.
New, Newf, and NewKV create failures. Wrap, Wrapf, and WrapKV annotate their cause chains while processing continues. Collectors accumulate scoped failures.
Inspect collects failures into an independent Error snapshot for rendering and metadata inspection, preserving the input and its original causes.
Code generated by internal/tools/cmd/ecode. DO NOT EDIT.
Index ¶
- Constants
- Variables
- func E0001(sheetName string, bookName string) error
- func E0002(filename string, messageName string, error_ error, lines string) error
- func E0003(name string, position1 string, position2 string) error
- func E0004() error
- func E0005(message string) error
- func E1000(filename string, bookName1 string, bookName2 string) error
- func E2000(type_ string, value string, min any, max any) error
- func E2001(refer string, messageName string) error
- func E2002(value string, refer string) error
- func E2003(value string, sequence int64) error
- func E2004(value any, range_ string) error
- func E2005(key any) error
- func E2006(value any, enumName any) error
- func E2007(value any, error_ error) error
- func E2008(value any, error_ error) error
- func E2009(key any, fieldName string) error
- func E2010(typeValue any, fieldNumber any) error
- func E2011() error
- func E2012(fieldType any, value any, error_ error) error
- func E2013(value any, error_ error) error
- func E2014(column string) error
- func E2015(column string, referBookName string, referSheetName string) error
- func E2016(firstNonePresentIndex int, nextPresentIndex int) error
- func E2017(mapType string) error
- func E2018(keyName string) error
- func E2019(value string, error_ error) error
- func E2020(value string, error_ error) error
- func E2021(enumType any, enumValue1 any, enumValue2 any, alias any) error
- func E2022(fieldName string, key any) error
- func E2023(currValue any, prevValue any) error
- func E2024(value string, error_ error) error
- func E2025(value string, pattern string) error
- func E2026(value any, prevValue any, order string) error
- func E2027(violation string, fieldValue any) error
- func E2028(elem any) error
- func E2029(fieldName string, fieldType string) error
- func E2030(referBookName string, referSheetName string) error
- func E2031(typeName string, cellData string, expected int, actual int, sep string) error
- func E3000(sheetSpecifier string, pattern string) error
- func E3001(sheetName string, bookName string) error
- func E3002(error_ error) error
- func E3003(glob string) error
- func New(msg string) error
- func NewKV(msg string, keysAndValues ...any) error
- func Newf(format string, args ...any) error
- func Wrap(err error) error
- func WrapEcodeWithCallerSkip(skip int, err error, code *ecode) error
- func WrapKV(err error, keysAndValues ...any) error
- func WrapKVWithCallerSkip(skip int, err error, keysAndValues ...any) error
- func Wrapf(err error, format string, args ...any) error
- type CellLocation
- type Collector
- type Error
- type ErrorDetail
- type FieldLocation
- type Frame
- type Group
- type SourceLocation
- type StackTrace
Constants ¶
const ( ModuleDefault = "default" ModuleProto = "protogen" ModuleConf = "confgen" )
const ( // Selects the localized summary template; values: default, proto, conf. KeyModule = "Module" KeyIndir = "Indir" // input dir KeySubdir = "Subdir" // input subdir KeyOutdir = "Outdir" // output dir KeyBookName = "BookName" // workbook name KeyPrimaryBookName = "PrimaryBookName" // primary workbook name KeySheetName = "SheetName" // worksheet name KeyPrimarySheetName = "PrimarySheetName" // primary worksheet name KeyBookAlias = "BookAlias" // schema workbook alias KeySheetAlias = "SheetAlias" // schema worksheet alias (protobuf message name) KeyMerger = "Merger" // configured merger sheet specifiers KeyScatter = "Scatter" // configured scatter sheet specifiers KeyReferBookName = "ReferBookName" // referred workbook name KeyReferSheetName = "ReferSheetName" // referred worksheet name KeyNameCellPos = "NameCellPos" // name cell position KeyNameCell = "NameCell" // name cell value KeyTrimmedNameCell = "TrimmedNameCell" // trimmed name cell value KeyTypeCellPos = "TypeCellPos" // type cell position KeyTypeCell = "TypeCell" // type cell value KeyNoteCellPos = "NoteCellPos" // note cell position KeyNoteCell = "NoteCell" // note cell value KeyDataCellPos = "DataCellPos" // data cell position KeyDataCell = "DataCell" // data cell value KeyPBMessage = "PBMessage" // protobuf message name KeyPBFieldName = "PBFieldName" // protobuf message field name KeyPBFieldType = "PBFieldType" // protobuf message field type KeyPBFieldOpts = "PBFieldOpts" // protobuf message field options (extensions) KeyColumnName = "ColumnName" // column name KeyErrCode = "ErrCode" KeyErrDesc = "ErrDesc" KeyReason = "Reason" // error reason // KeyHelp suggests how to fix the error. // See https://rustc-dev-guide.rust-lang.org/diagnostics.html#suggestions KeyHelp = "Help" )
structured error keys
Variables ¶
var ErrE0001 = newEcode("E0001", `sheet not found in book`)
var ErrE0002 = newEcode("E0002", `cannot unmarshal file content to given proto.Message`)
var ErrE0003 = newEcode("E0003", `duplicate column name`)
var ErrE0004 = newEcode("E0004", `unknown error`)
var ErrE0005 = newEcode("E0005", `custom check failed`)
var ErrE1000 = newEcode("E1000", `generated proto filename conflict`)
var ErrE2000 = newEcode("E2000", `integer overflow`)
var ErrE2001 = newEcode("E2001", `field prop "refer" not configured correctly`)
var ErrE2002 = newEcode("E2002", `field value not in referred space`)
var ErrE2003 = newEcode("E2003", `illegal sequence number`)
var ErrE2004 = newEcode("E2004", `value is out of range`)
var ErrE2005 = newEcode("E2005", `map key not unique`)
var ErrE2006 = newEcode("E2006", `enum value not defined in enum type`)
var ErrE2007 = newEcode("E2007", `invalid datetime format`)
var ErrE2008 = newEcode("E2008", `invalid duration format`)
var ErrE2009 = newEcode("E2009", `duplicate key exists in different sheets`)
var ErrE2010 = newEcode("E2010", `union type has no corresponding value field`)
var ErrE2011 = newEcode("E2011", `field presence required but cell not filled`)
var ErrE2012 = newEcode("E2012", `invalid syntax of numerical value`)
var ErrE2013 = newEcode("E2013", `invalid syntax of boolean value`)
var ErrE2014 = newEcode("E2014", `sheet column not found`)
var ErrE2015 = newEcode("E2015", `referred sheet column not found`)
var ErrE2016 = newEcode("E2016", `list elements are not present continuously`)
var ErrE2017 = newEcode("E2017", `map contains multiple empty keys`)
var ErrE2018 = newEcode("E2018", `map key not exists`)
var ErrE2019 = newEcode("E2019", `invalid fraction pattern`)
var ErrE2020 = newEcode("E2020", `invalid comparator pattern`)
var ErrE2021 = newEcode("E2021", `duplicate enum value alias`)
var ErrE2022 = newEcode("E2022", `sub-field's value not unique in map values or list elements`)
var ErrE2023 = newEcode("E2023", `field value conflict across rows or columns`)
var ErrE2024 = newEcode("E2024", `invalid version pattern`)
var ErrE2025 = newEcode("E2025", `version value mismatches pattern`)
var ErrE2026 = newEcode("E2026", `illegally ordered values`)
var ErrE2027 = newEcode("E2027", `protovalidate violation`)
var ErrE2028 = newEcode("E2028", `duplicate elements in incell keyed-list`)
var ErrE2029 = newEcode("E2029", `no cell with digit suffix for horizontal list/map field`)
var ErrE2030 = newEcode("E2030", `referred sheet not found`)
var ErrE2031 = newEcode("E2031", `incell struct field count exceeds limit`)
var ErrE3000 = newEcode("E3000", `no workbook file found about sheet specifier`)
var ErrE3001 = newEcode("E3001", `no worksheet found in workbook`)
var ErrE3002 = newEcode("E3002", `failed to open file`)
var ErrE3003 = newEcode("E3003", `CSV workbook glob pattern matches no files`)
Functions ¶
func Wrap ¶
Wrap adds caller context to the cause chain by attaching a stack trace. Returns nil if err is nil.
func WrapEcodeWithCallerSkip ¶ added in v0.17.0
WrapEcodeWithCallerSkip adds code defaults through the existing metadata wrapper without replacing individual messages. Forwarding APIs pass one to capture their caller; existing codes, metadata, causes, and stacks survive.
func WrapKV ¶
WrapKV adds fields to an error. Fields on a regular join apply to its children; a collector Join result keeps the scope of its collector tree. Returns nil if err is nil.
func WrapKVWithCallerSkip ¶ added in v0.17.0
WrapKVWithCallerSkip is WrapKV with control over the captured caller. skip counts additional caller frames to omit; zero starts at this function's caller. Forwarding APIs pass one to capture their own caller instead. An existing stack is preserved.
Types ¶
type CellLocation ¶ added in v0.17.0
type CellLocation struct {
Position string `json:"position,omitempty"`
Data string `json:"data,omitempty"`
TrimmedData string `json:"trimmedData,omitempty"`
}
CellLocation contains the source position and data of a cell. Position can also identify a node in a document input. TrimmedData is used for headers.
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector accumulates errors concurrently up to a configurable limit. Children represent narrower scopes; Join includes their errors automatically.
func NewCollector ¶
NewCollector creates a root Collector. maxErrs: <=0 unlimited, 1 fail-fast, >1 stops after N errors.
func (*Collector) Collect ¶
Collect accumulates err into the collector.
A nil error or a Join result already in this tree adds nothing. Once this collector or an ancestor is full, further calls stop without consuming another level's budget. The call that reaches a limit is still stored and returns the joined errors.
func (*Collector) HasErrors ¶
HasErrors reports whether this collector's subtree has any errors. It is a fast, lock-free check suitable for guarding expensive Collector.Join calls.
func (*Collector) IsFull ¶
IsFull reports whether this collector or any ancestor has reached its limit.
func (*Collector) NewChild ¶
NewChild creates a child collector registered under the receiver. Scope fields describe every error in the child's subtree; each leaf keeps its own cell and field details. maxErrs follows NewCollector.
type Error ¶ added in v0.17.0
type Error struct {
Details []*ErrorDetail `json:"details"`
// contains filtered or unexported fields
}
Error reports one or more structured failures from Tableau. Use Inspect to obtain it from an operation's error. Details contains one entry per failure, including when only one cell fails. Error renders these details as a localized summary. JSON omits underlying errors and stack traces.
func Inspect ¶ added in v0.17.0
Inspect collects all failures in err into an independent *Error snapshot. Wrapped and joined errors are flattened into Details, preserving each failure's metadata. The Error method renders the details consistently, numbering multiple failures in one sequence: [1], [2], [3], ... Call Inspect once at the reporting boundary.
Editing the snapshot does not change err. Original causes remain reachable through errors.Is and errors.As. An ordinary Go error yields one detail containing its message; nil returns nil.
func (*Error) Format ¶ added in v0.17.0
Format includes structured debugging fields and stacks only for %+v.
func (*Error) GetValue ¶ added in v0.17.0
GetValue returns the value associated with key in the first detail. It returns nil if the error is nil, has no details, its first detail is nil, or the key is absent from that detail.
This is a convenience for inspecting a single failure. For aggregate errors, it neither searches later details nor combines their metadata. Iterate over Details and call each detail's GetValue to keep values tied to their failure.
type ErrorDetail ¶ added in v0.17.0
type ErrorDetail struct {
Code string `json:"code,omitempty"`
Description string `json:"description,omitempty"`
Message string `json:"message"`
Help string `json:"help,omitempty"`
Module string `json:"module,omitempty"`
Source *SourceLocation `json:"source,omitempty"`
Field *FieldLocation `json:"field,omitempty"`
// contains filtered or unexported fields
}
ErrorDetail describes one failure, independently of error wrappers and localized text formatting. Source and Field are omitted when unavailable.
func (*ErrorDetail) GetValue ¶ added in v0.17.0
func (d *ErrorDetail) GetValue(key string) any
GetValue returns the value associated with key in the detail, or nil if the key is absent. It supports typed source and field metadata as well as error-specific parameters.
func (*ErrorDetail) String ¶ added in v0.17.0
func (d *ErrorDetail) String() string
String renders this detail using the shared localized summary template.
type FieldLocation ¶ added in v0.17.0
type FieldLocation struct {
Message string `json:"message,omitempty"`
Name string `json:"name,omitempty"`
Type string `json:"type,omitempty"`
Options string `json:"options,omitempty"`
Column string `json:"column,omitempty"`
}
FieldLocation identifies the protobuf message and field associated with a failure. Options contains the textual Tableau field options, when available.
type Frame ¶
type Frame uintptr
Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.
func (Frame) Format ¶
Format formats the frame according to the fmt.Formatter interface.
%s source file %d source line %n function name %v equivalent to %s:%d
Format accepts flags that alter the printing of some verbs, as follows:
%+s function name and path of source file relative to the compile time
GOPATH separated by \n\t (<funcname>\n\t<path>)
%+v equivalent to %+s:%d
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group ties an errgroup.Group to a Collector for concurrent collection. Context is cancelled when the collector becomes full.
type SourceLocation ¶ added in v0.17.0
type SourceLocation struct {
Workbook string `json:"workbook,omitempty"`
PrimaryWorkbook string `json:"primaryWorkbook,omitempty"`
Worksheet string `json:"worksheet,omitempty"`
PrimaryWorksheet string `json:"primaryWorksheet,omitempty"`
WorkbookAlias string `json:"workbookAlias,omitempty"`
WorksheetAlias string `json:"worksheetAlias,omitempty"`
Merger []string `json:"merger,omitempty"`
Scatter []string `json:"scatter,omitempty"`
ReferencedWorkbook string `json:"referencedWorkbook,omitempty"`
ReferencedWorksheet string `json:"referencedWorksheet,omitempty"`
InputDir string `json:"inputDir,omitempty"`
Subdir string `json:"subdir,omitempty"`
OutputDir string `json:"outputDir,omitempty"`
Cell *CellLocation `json:"cell,omitempty"`
NameCell *CellLocation `json:"nameCell,omitempty"`
TypeCell *CellLocation `json:"typeCell,omitempty"`
NoteCell *CellLocation `json:"noteCell,omitempty"`
}
SourceLocation identifies the actual source of a failure. PrimaryWorkbook and PrimaryWorksheet identify the schema's source when a shard is loaded. Aliases and merger/scatter specifiers describe that schema, independently of the actual workbook, worksheet, and cell where the failure occurred. WorksheetAlias is the protobuf message name when it differs from the schema worksheet name.
type StackTrace ¶
type StackTrace []Frame
StackTrace is stack of Frames from innermost (newest) to outermost (oldest).
func (StackTrace) Format ¶
func (st StackTrace) Format(s fmt.State, verb rune)
Format formats the stack of Frames according to the fmt.Formatter interface.
%s lists source files for each Frame in the stack %v lists the source file and line number for each Frame in the stack
Format accepts flags that alter the printing of some verbs, as follows:
%+v Prints filename, function, and line number for each Frame in the stack.
Source Files