errors

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2025 License: Apache-2.0 Imports: 3 Imported by: 0

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

View Source 
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.

View Source 
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.

View Source 
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).

View Source 
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).

View Source 
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 

func FormatCaret(width, column int) string

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 

func SetFileReader(fn func(string) (string, error))

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 

type SourceLine struct {
	Number int    // Line number (1-based)
	Text   string // Line content
}

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.