Documentation
¶
Overview ¶
Package errors provides structured error formatting for the build tool.
The package implements error message templates with:
- Error codes (E001, E100, E200, etc.)
- Source context with line numbers
- Caret pointers to error location
- Notes for additional context
- Help suggestions for fixes
Error Format ¶
Errors are formatted in a Rust-like style:
error[E100]: missing ':' in target definition --> Buildfile:3:10 2 | cc = gcc 3 | build/app deps | ^ 4 | gcc -o build/app deps note: targets require ':' before dependencies help: change to: build/app: deps
Error Code Categories ¶
- E001-E099: Lexical errors (invalid character, bad indentation)
- E100-E199: Syntax errors (unexpected token, missing colon)
- E200-E299: Semantic errors (undefined variable, duplicate definition)
- E300-E399: Evaluation errors (shell failure, bad function args)
- E400-E499: Execution errors (recipe failed, missing file)
Package errors provides structured error formatting for the build tool.
The package implements error message templates with:
- Error codes (E001, E100, E200, etc.)
- Source context with line numbers
- Caret pointers to error location
- Notes for additional context
- Help suggestions for fixes
Index ¶
- Constants
- func FormatCaret(width, column int) string
- func InitFileReader()
- func SetFileReader(fn func(string) (string, error))
- type FormattedError
- func NewAutomaticInPatternError(name string, loc ast.SourceLocation) *FormattedError
- func NewAutomaticOutsideRecipeError(name string, loc ast.SourceLocation) *FormattedError
- func NewCaptureConflictError(name, conflictType string, loc ast.SourceLocation) *FormattedError
- func NewCaptureMismatchError(name string, loc, targetLoc ast.SourceLocation) *FormattedError
- func NewCircularDependencyError(cycle []string) *FormattedError
- func NewCircularIncludeError(file string, loc ast.SourceLocation) *FormattedError
- func NewConditionEvaluationError(reason string, loc ast.SourceLocation) *FormattedError
- func NewDuplicateEnvironmentError(name string, first, second ast.SourceLocation) *FormattedError
- func NewDuplicateTargetError(name string, first, second ast.SourceLocation) *FormattedError
- func NewDuplicateVariableError(name string, first, second ast.SourceLocation) *FormattedError
- func NewFormattedError(code, message string, loc ast.SourceLocation) *FormattedError
- func NewForwardReferenceError(varName, referencedVar string, loc ast.SourceLocation) *FormattedError
- func NewGlobNoMatchError(pattern string, loc ast.SourceLocation) *FormattedError
- func NewIncludeNotFoundError(file string, loc ast.SourceLocation) *FormattedError
- func NewInconsistentIndentationError(expected, got string, loc ast.SourceLocation) *FormattedError
- func NewInvalidCharacterError(ch byte, loc ast.SourceLocation) *FormattedError
- func NewInvalidDirectiveScopeError(directive, currentScope string, validScopes []string, loc ast.SourceLocation) *FormattedError
- func NewInvalidEscapeSequenceError(seq string, loc ast.SourceLocation) *FormattedError
- func NewInvalidFunctionArgumentsError(funcName, reason string, loc ast.SourceLocation) *FormattedError
- func NewInvalidIndentWidthError(got, unit int, loc ast.SourceLocation) *FormattedError
- func NewInvalidModifierError(modifier string, loc ast.SourceLocation) *FormattedError
- func NewInvalidRuntimeError(runtime string, loc ast.SourceLocation) *FormattedError
- func NewLazyEvaluationError(varName, reason string, loc ast.SourceLocation) *FormattedError
- func NewMissingBinaryError(binary string, loc ast.SourceLocation) *FormattedError
- func NewMissingColonError(target string, loc ast.SourceLocation) *FormattedError
- func NewMissingConditionError(keyword string, loc ast.SourceLocation) *FormattedError
- func NewMissingDependencyError(dependency, target string) *FormattedError
- func NewMissingEndError(loc ast.SourceLocation) *FormattedError
- func NewMissingFunctionArgumentError(funcName string, expected, got int, loc ast.SourceLocation) *FormattedError
- func NewMissingIdentifierError(keyword string, loc ast.SourceLocation) *FormattedError
- func NewMissingOperatorError(loc ast.SourceLocation) *FormattedError
- func NewMixedIndentationError(loc ast.SourceLocation) *FormattedError
- func NewNoDefaultTargetError() *FormattedError
- func NewRecipeFailedError(target, command string, exitCode int, loc ast.SourceLocation) *FormattedError
- func NewShellCommandFailedError(cmd string, exitCode int, stderr string, loc ast.SourceLocation) *FormattedError
- func NewShellNotFoundError(shell string, loc ast.SourceLocation) *FormattedError
- func NewTargetNotFoundError(target string) *FormattedError
- func NewUnclosedInterpolationError(name string, loc ast.SourceLocation) *FormattedError
- func NewUndefinedVariableError(name string, loc ast.SourceLocation) *FormattedError
- func NewUnexpectedCharInInterpError(ch byte, loc ast.SourceLocation) *FormattedError
- func NewUnexpectedTokenError(got, expected string, loc ast.SourceLocation) *FormattedError
- func NewVersionMismatchError(binary, required, found string, loc ast.SourceLocation) *FormattedError
- func (e *FormattedError) Error() string
- func (e *FormattedError) Format() string
- func (e *FormattedError) WithHelp(help string) *FormattedError
- func (e *FormattedError) WithNote(note string) *FormattedError
- func (e *FormattedError) WithSourceContext(lines []SourceLine, caretLine, caretColumn int) *FormattedError
- type SourceLine
Constants ¶
const ( // E300: Shell command failed during shell() function CodeShellCommandFailed = "E300" // E301: Glob pattern matched no files CodeGlobNoMatch = "E301" // E302: Invalid arguments to function CodeInvalidFunctionArguments = "E302" // E303: Forward reference in immediate variable CodeForwardReference = "E303" // E304: Error during lazy variable evaluation CodeLazyEvaluationError = "E304" // E305: Error evaluating condition in conditional CodeConditionEvaluationError = "E305" )
Evaluation Error Codes (E300-E399) These errors occur during variable evaluation and function execution.
const ( // E400: Recipe command returned non-zero exit code CodeRecipeFailed = "E400" // E401: Required dependency file does not exist CodeMissingDependency = "E401" // E402: Required binary not found in PATH CodeMissingBinary = "E402" // E403: Specified shell not found CodeShellNotFound = "E403" // E404: Binary version does not meet requirement CodeVersionMismatch = "E404" // E405: Requested target not defined in Buildfile CodeTargetNotFound = "E405" // E406: No default target and none specified CodeNoDefaultTarget = "E406" )
Execution Error Codes (E400-E499) These errors occur during recipe execution and build runtime.
const ( // E001: Invalid character in source CodeInvalidCharacter = "E001" // E002: Mixed tabs and spaces in indentation CodeMixedIndentation = "E002" // E003: Inconsistent indentation character (switched from spaces to tabs or vice versa) CodeInconsistentIndentation = "E003" // E004: Indentation width is not a multiple of the established unit CodeInvalidIndentWidth = "E004" // E005: Interpolation opened with { but not closed with } CodeUnclosedInterpolation = "E005" // E006: Invalid modifier in interpolation (only :raw is valid) CodeInvalidModifier = "E006" // E007: Unexpected character inside interpolation CodeUnexpectedCharInInterp = "E007" // E008: Invalid escape sequence CodeInvalidEscapeSequence = "E008" )
Lexical Error Codes (E001-E099) These errors occur during lexical analysis (tokenization).
const ( // E200: Reference to undefined variable CodeUndefinedVariable = "E200" // E201: Variable defined multiple times CodeDuplicateVariable = "E201" // E202: Target defined multiple times CodeDuplicateTarget = "E202" // E203: Environment defined multiple times CodeDuplicateEnvironment = "E203" // E204: Circular dependency in target graph CodeCircularDependency = "E204" // E205: Capture name conflicts with defined variable or automatic CodeCaptureConflict = "E205" // E206: Capture in dependency not defined in target pattern CodeCaptureMismatch = "E206" // E207: Automatic variable used outside recipe/block scope CodeAutomaticOutsideRecipe = "E207" // E208: Automatic variable used in target pattern CodeAutomaticInPattern = "E208" )
Semantic Error Codes (E200-E299) These errors occur during semantic analysis (validation after parsing).
const ( // E100: Unexpected token during parsing CodeUnexpectedToken = "E100" // E101: Missing colon in target definition CodeMissingColon = "E101" // E102: Missing 'end' to close conditional CodeMissingEnd = "E102" // E103: Directive used in invalid scope CodeInvalidDirectiveScope = "E103" // E104: Missing condition expression after if/elif CodeMissingCondition = "E104" // E105: Missing comparison operator in condition CodeMissingOperator = "E105" // E106: Missing identifier after ifdef/ifndef CodeMissingIdentifier = "E106" // E107: Invalid runtime type in .using directive CodeInvalidRuntime = "E107" // E108: Wrong number of arguments to function CodeMissingFunctionArgument = "E108" // E109: Circular include detected CodeCircularInclude = "E109" // E110: Included file not found CodeIncludeNotFound = "E110" )
Syntax Error Codes (E100-E199) These errors occur during parsing (syntax analysis).
Variables ¶
This section is empty.
Functions ¶
func FormatCaret ¶
FormatCaret creates a caret line pointing to a column. width is the line number field width, column is 1-based.
func InitFileReader ¶
func InitFileReader()
InitFileReader initializes the file reader to use os.ReadFile. Call this in main or init to enable file-based source extraction.
func SetFileReader ¶
SetFileReader sets the file reader function. Used for testing.
Types ¶
type FormattedError ¶
type FormattedError struct {
Code string // Error code (E001, E100, etc.)
Message string // Brief error description
Location ast.SourceLocation // Source location
SourceLines []SourceLine // Source context (1-3 lines)
CaretLine int // Line to show caret on (0 = no caret)
CaretColumn int // Column for caret (1-based)
Note string // Additional context (optional)
Help string // Fix suggestion (optional)
}
FormattedError represents a structured error with source context.
func NewAutomaticInPatternError ¶
func NewAutomaticInPatternError(name string, loc ast.SourceLocation) *FormattedError
NewAutomaticInPatternError creates an error for automatic vars in target patterns.
func NewAutomaticOutsideRecipeError ¶
func NewAutomaticOutsideRecipeError(name string, loc ast.SourceLocation) *FormattedError
NewAutomaticOutsideRecipeError creates an error for automatic vars outside recipe.
func NewCaptureConflictError ¶
func NewCaptureConflictError(name, conflictType string, loc ast.SourceLocation) *FormattedError
NewCaptureConflictError creates an error when capture conflicts with variable/automatic.
func NewCaptureMismatchError ¶
func NewCaptureMismatchError(name string, loc, targetLoc ast.SourceLocation) *FormattedError
NewCaptureMismatchError creates an error when capture in dependency is not in target.
func NewCircularDependencyError ¶
func NewCircularDependencyError(cycle []string) *FormattedError
NewCircularDependencyError creates an error for circular dependencies.
func NewCircularIncludeError ¶
func NewCircularIncludeError(file string, loc ast.SourceLocation) *FormattedError
NewCircularIncludeError creates an error for circular include detection.
func NewConditionEvaluationError ¶
func NewConditionEvaluationError(reason string, loc ast.SourceLocation) *FormattedError
NewConditionEvaluationError creates an error for condition evaluation failures.
func NewDuplicateEnvironmentError ¶
func NewDuplicateEnvironmentError(name string, first, second ast.SourceLocation) *FormattedError
NewDuplicateEnvironmentError creates an error for duplicate environment definitions.
func NewDuplicateTargetError ¶
func NewDuplicateTargetError(name string, first, second ast.SourceLocation) *FormattedError
NewDuplicateTargetError creates an error for duplicate target definitions.
func NewDuplicateVariableError ¶
func NewDuplicateVariableError(name string, first, second ast.SourceLocation) *FormattedError
NewDuplicateVariableError creates an error for duplicate variable definitions.
func NewFormattedError ¶
func NewFormattedError(code, message string, loc ast.SourceLocation) *FormattedError
NewFormattedError creates a basic formatted error.
func NewForwardReferenceError ¶
func NewForwardReferenceError(varName, referencedVar string, loc ast.SourceLocation) *FormattedError
NewForwardReferenceError creates an error for forward references in immediate variables.
func NewGlobNoMatchError ¶
func NewGlobNoMatchError(pattern string, loc ast.SourceLocation) *FormattedError
NewGlobNoMatchError creates an error for glob patterns matching no files.
func NewIncludeNotFoundError ¶
func NewIncludeNotFoundError(file string, loc ast.SourceLocation) *FormattedError
NewIncludeNotFoundError creates an error for missing included files.
func NewInconsistentIndentationError ¶
func NewInconsistentIndentationError(expected, got string, loc ast.SourceLocation) *FormattedError
NewInconsistentIndentationError creates an error for switching between tabs and spaces.
func NewInvalidCharacterError ¶
func NewInvalidCharacterError(ch byte, loc ast.SourceLocation) *FormattedError
NewInvalidCharacterError creates an error for invalid characters in source.
func NewInvalidDirectiveScopeError ¶
func NewInvalidDirectiveScopeError(directive, currentScope string, validScopes []string, loc ast.SourceLocation) *FormattedError
NewInvalidDirectiveScopeError creates an error for directives in wrong scope.
func NewInvalidEscapeSequenceError ¶
func NewInvalidEscapeSequenceError(seq string, loc ast.SourceLocation) *FormattedError
NewInvalidEscapeSequenceError creates an error for invalid escape sequences.
func NewInvalidFunctionArgumentsError ¶
func NewInvalidFunctionArgumentsError(funcName, reason string, loc ast.SourceLocation) *FormattedError
NewInvalidFunctionArgumentsError creates an error for invalid function arguments.
func NewInvalidIndentWidthError ¶
func NewInvalidIndentWidthError(got, unit int, loc ast.SourceLocation) *FormattedError
NewInvalidIndentWidthError creates an error for incorrect indentation width.
func NewInvalidModifierError ¶
func NewInvalidModifierError(modifier string, loc ast.SourceLocation) *FormattedError
NewInvalidModifierError creates an error for invalid interpolation modifiers.
func NewInvalidRuntimeError ¶
func NewInvalidRuntimeError(runtime string, loc ast.SourceLocation) *FormattedError
NewInvalidRuntimeError creates an error for invalid runtime in .using directive.
func NewLazyEvaluationError ¶
func NewLazyEvaluationError(varName, reason string, loc ast.SourceLocation) *FormattedError
NewLazyEvaluationError creates an error for lazy variable evaluation failures.
func NewMissingBinaryError ¶
func NewMissingBinaryError(binary string, loc ast.SourceLocation) *FormattedError
NewMissingBinaryError creates an error for required binaries not in PATH.
func NewMissingColonError ¶
func NewMissingColonError(target string, loc ast.SourceLocation) *FormattedError
NewMissingColonError creates an error for missing colon in target definition.
func NewMissingConditionError ¶
func NewMissingConditionError(keyword string, loc ast.SourceLocation) *FormattedError
NewMissingConditionError creates an error for missing condition after if/elif.
func NewMissingDependencyError ¶
func NewMissingDependencyError(dependency, target string) *FormattedError
NewMissingDependencyError creates an error for missing dependency files.
func NewMissingEndError ¶
func NewMissingEndError(loc ast.SourceLocation) *FormattedError
NewMissingEndError creates an error for missing 'end' keyword.
func NewMissingFunctionArgumentError ¶
func NewMissingFunctionArgumentError(funcName string, expected, got int, loc ast.SourceLocation) *FormattedError
NewMissingFunctionArgumentError creates an error for wrong argument count.
func NewMissingIdentifierError ¶
func NewMissingIdentifierError(keyword string, loc ast.SourceLocation) *FormattedError
NewMissingIdentifierError creates an error for missing identifier after ifdef/ifndef.
func NewMissingOperatorError ¶
func NewMissingOperatorError(loc ast.SourceLocation) *FormattedError
NewMissingOperatorError creates an error for missing comparison operator.
func NewMixedIndentationError ¶
func NewMixedIndentationError(loc ast.SourceLocation) *FormattedError
NewMixedIndentationError creates an error for mixing tabs and spaces in indentation.
func NewNoDefaultTargetError ¶
func NewNoDefaultTargetError() *FormattedError
NewNoDefaultTargetError creates an error when no target is specified and no default exists.
func NewRecipeFailedError ¶
func NewRecipeFailedError(target, command string, exitCode int, loc ast.SourceLocation) *FormattedError
NewRecipeFailedError creates an error for failed recipe execution.
func NewShellCommandFailedError ¶
func NewShellCommandFailedError(cmd string, exitCode int, stderr string, loc ast.SourceLocation) *FormattedError
NewShellCommandFailedError creates an error for shell() function failures.
func NewShellNotFoundError ¶
func NewShellNotFoundError(shell string, loc ast.SourceLocation) *FormattedError
NewShellNotFoundError creates an error for missing shell.
func NewTargetNotFoundError ¶
func NewTargetNotFoundError(target string) *FormattedError
NewTargetNotFoundError creates an error for undefined targets.
func NewUnclosedInterpolationError ¶
func NewUnclosedInterpolationError(name string, loc ast.SourceLocation) *FormattedError
NewUnclosedInterpolationError creates an error for unclosed interpolation.
func NewUndefinedVariableError ¶
func NewUndefinedVariableError(name string, loc ast.SourceLocation) *FormattedError
NewUndefinedVariableError creates an error for undefined variable references.
func NewUnexpectedCharInInterpError ¶
func NewUnexpectedCharInInterpError(ch byte, loc ast.SourceLocation) *FormattedError
NewUnexpectedCharInInterpError creates an error for unexpected characters in interpolation.
func NewUnexpectedTokenError ¶
func NewUnexpectedTokenError(got, expected string, loc ast.SourceLocation) *FormattedError
NewUnexpectedTokenError creates an error for unexpected tokens during parsing.
func NewVersionMismatchError ¶
func NewVersionMismatchError(binary, required, found string, loc ast.SourceLocation) *FormattedError
NewVersionMismatchError creates an error for version requirement not met.
func (*FormattedError) Error ¶
func (e *FormattedError) Error() string
Error implements the error interface.
func (*FormattedError) Format ¶
func (e *FormattedError) Format() string
Format returns the fully formatted error message.
func (*FormattedError) WithHelp ¶
func (e *FormattedError) WithHelp(help string) *FormattedError
WithHelp adds a help suggestion to the error.
func (*FormattedError) WithNote ¶
func (e *FormattedError) WithNote(note string) *FormattedError
WithNote adds a note to the error.
func (*FormattedError) WithSourceContext ¶
func (e *FormattedError) WithSourceContext(lines []SourceLine, caretLine, caretColumn int) *FormattedError
WithSourceContext adds source lines to the error.
type SourceLine ¶
SourceLine represents a single line of source code for error display.
func ExtractSourceLines ¶
func ExtractSourceLines(source string, line, context int) []SourceLine
ExtractSourceLines extracts source lines around a location from source content. context specifies how many lines before and after to include (1-3 recommended).
func ExtractSourceLinesFromFile ¶
func ExtractSourceLinesFromFile(path string, line, context int) ([]SourceLine, error)
ExtractSourceLinesFromFile extracts source lines from a file around a location. context specifies how many lines before and after to include.
func (SourceLine) Format ¶
func (l SourceLine) Format(width int) string
Format formats the source line with a line number prefix. width is the minimum width for the line number.