Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotABoolean = NewTypeSentinel("boolean") ErrNotAPort = NewTypeSentinel("port") ErrNotAnInputPort = NewTypeSentinel("input port") ErrNotAnOutputPort = NewTypeSentinel("output port") ErrNotABox = NewTypeSentinel("box") ErrNotAnOpaqueValue = NewTypeSentinel("opaque value") ErrNotAByte = NewTypeSentinel("byte") // ErrNotAByteInputPort and ErrNotAByteOutputPort use "binary" to match the // user-facing terminology in R7RS and values/value_type.go; the var names // keep "Byte" for historical reasons but the message phrases track the // rest of the codebase. ErrNotAByteInputPort = NewTypeSentinel("binary input port") ErrNotAByteOutputPort = NewTypeSentinel("binary output port") ErrNotATextualPort = NewTypeSentinel("textual port") ErrNoIOState = NewStaticError("no io state") ErrStopIteration = NewStaticError("stop iteration") ErrNotAPrimitive = NewTypeSentinel("primitive") ErrNoSuchBinding = NewStaticError("no such binding") ErrAmbiguousBinding = NewStaticError("ambiguous binding") ErrNotANumber = NewTypeSentinel("number") ErrCannotCompare = NewStaticError("cannot compare values") ErrNotAReal = NewTypeSentinel("real number") ErrDivisionByZero = NewStaticError("division by zero") ErrNotAList = NewTypeSentinel("list") ErrCircularList = NewStaticError("circular list") ErrNotACloseParen = NewStaticError("not a close parenthesis") ErrDatumLabelUndefined = NewStaticError("undefined datum label") ErrWrongNumberOfArguments = NewStaticError("wrong number of arguments") ErrNotAMachineContext = NewTypeSentinel("machine context") ErrNotAPair = NewTypeSentinel("pair") ErrNotACons = NewTypeSentinel("cons") ErrNotACharacter = NewTypeSentinel("character") ErrNotACharSet = NewTypeSentinel("char-set") ErrStackUnderflow = NewStaticError("stack underflow") ErrStackOverflow = NewStaticError("stack overflow") ErrNotASyntaxValue = NewTypeSentinel("syntax value") ErrNotASyntaxPair = NewTypeSentinel("syntax pair") ErrNotASyntaxSymbol = NewTypeSentinel("syntax symbol") ErrNotASyntaxList = NewTypeSentinel("syntax list") ErrNotASyntaxObject = NewTypeSentinel("syntax object") ErrNotASymbol = NewTypeSentinel("symbol") ErrInvalidSyntax = NewStaticError("invalid syntax") // ErrIncompleteInput marks input that is a valid prefix of an expression but // ended before completing (unterminated string/symbol, source ending inside an // unclosed form). REPLs errors.Is this to decide whether to read more input. // Lives in werr (not internal/parser) so the tokenizer can reference it without // an import cycle. ErrIncompleteInput = NewStaticError("incomplete input") ErrInvalidArgument = NewStaticError("invalid argument") ErrInternal = NewStaticError("internal error") ErrDuplicateBinding = NewStaticError("duplicate binding") ErrNotAClosure = NewTypeSentinel("closure") ErrUnknownCharacterMnemonic = NewStaticError("unknown character mnemonic") ErrNotAnInteger = NewTypeSentinel("integer") ErrNotALocalEnvironmentFrame = NewTypeSentinel("local environment frame") ErrNotAMachineTemplate = NewTypeSentinel("machine template") ErrUnexpectedNil = NewStaticError("unexpected nil value") ErrUnexpectedTransformer = NewStaticError("unexpected transformer") ErrNotAString = NewTypeSentinel("string") ErrNotANamespace = NewTypeSentinel("namespace") ErrNotAVector = NewTypeSentinel("vector") ErrNotAByteVector = NewTypeSentinel("bytevector") ErrNotAProcedure = NewTypeSentinel("procedure") ErrNotAParameter = NewTypeSentinel("parameter") // ErrComposableContinuationFromGo marks an attempt to invoke a composable // continuation from Go via Engine.Call; composable continuations require the // VM winding stack and have no Go-callable form. ErrComposableContinuationFromGo = NewStaticError("cannot call composable continuation from Go") ErrNotAStringOutputPort = NewTypeSentinel("string output port") ErrNotABytevectorOutputPort = NewTypeSentinel("bytevector output port") ErrNotANativeError = NewTypeSentinel("error object") ErrNotARecord = NewTypeSentinel("record") ErrNotARecordType = NewTypeSentinel("record type") ErrOpaqueRecord = NewStaticError("record type is opaque") ErrFileNotFound = NewStaticError("file not found") ErrFileOpen = NewStaticError("file open failed") ErrLibraryNotFound = NewStaticError("library not found") ErrCircularDependency = NewStaticError("circular library dependency") ErrUnexportedIdentifier = NewStaticError("identifier not exported") ErrNotAThread = NewTypeSentinel("thread") ErrNotAMutex = NewTypeSentinel("mutex") ErrNotAConditionVariable = NewTypeSentinel("condition variable") ErrNotAnUncaughtException = NewTypeSentinel("uncaught-exception") ErrNotATime = NewTypeSentinel("time") ErrNotARWMutex = NewTypeSentinel("rw-mutex") // ErrNotAOnce passes an explicit article because "once" is pronounced // /wuns/: the letter rule would give "an once", but the consonant /w/ // sound calls for "a". The "a "-prefix pass-through in NewTypeSentinel // preserves it. ErrNotAOnce = NewTypeSentinel("a once") ErrNotAnAtomic = NewTypeSentinel("atomic") ErrPortClosed = NewStaticError("port is closed") ErrNotAHashtable = NewTypeSentinel("hashtable") ErrNoCaptureContext = NewStaticError("no capture context for expansion") ErrExactnessConversion = NewStaticError("exactness conversion failed") ErrLossyConversion = NewStaticError("lossy conversion") ErrNumericRegistry = NewStaticError("numeric registry violation") ErrInvalidFormat = NewStaticError("invalid number format") ErrUnknownOpCode = NewStaticError("unknown op code") ErrNotAMatch = NewTypeSentinel("match") ErrNotAPromptTag = NewTypeSentinel("prompt tag") ErrNotAContinuationMarkSet = NewTypeSentinel("continuation mark set") ErrNotAContinuation = NewTypeSentinel("continuation") ErrNotAnErrorContext = NewTypeSentinel("error context") ErrTypeConversion = NewStaticError("type conversion failed") ErrCodepointOutOfRange = NewStaticError("codepoint out of range") ErrIndexOutOfRange = NewStaticError("index out of range") ErrImmutableString = NewStaticError("cannot mutate immutable string") ErrImmutablePair = NewStaticError("cannot mutate immutable pair") ErrImmutableVector = NewStaticError("cannot mutate immutable vector") ErrImmutableBytevector = NewStaticError("cannot mutate immutable bytevector") ErrImmutableBinding = NewStaticError("cannot mutate immutable binding") ErrInvariantViolation = NewStaticError("invariant violation") ErrFFIRegistration = NewStaticError("FFI registration error") ErrFFICallbackError = NewStaticError("FFI callback error") ErrCallbackResultConversion = NewStaticError("callback result conversion failed") ErrHashtableInsertionFailed = NewStaticError("hashtable insertion failed") ErrEngineInit = NewStaticError("engine initialization error") ErrExpansion = NewStaticError("expansion error") ErrCompilation = NewStaticError("compilation error") ErrMissingNamespace = NewStaticError("missing Namespace") ErrMissingPhaseRegistry = NewStaticError("missing PhaseRegistry") ErrNilParentEnvironment = NewStaticError("nil parent environment") ErrThreadPanic = NewStaticError("thread panic") ErrPanicRecovery = NewStaticError("panic recovery") // ErrNotImplemented marks a primitive that is registered and callable but has // no working implementation behind it. It is deliberately distinct from a // runtime failure sentinel: the operation did not fail on its inputs, it does // not exist yet, and no input would make it succeed. Callers matching on it // are asking "is this feature wired?", not "did this call go wrong?". ErrNotImplemented = NewStaticError("not implemented") ErrCannotDoubleSyntaxWrap = NewStaticError("cannot wrap syntax value in SyntaxObject") ErrNoMatchingClause = NewStaticError("no matching clause") ErrUnsupportedTransformer = NewStaticError("unsupported transformer") ErrLibraryConfiguration = NewStaticError("library configuration error") ErrLibraryFormMalformed = NewStaticError("malformed library form") ErrLibraryNameMismatch = NewStaticError("library name mismatch") ErrHashtableKeyNotFound = NewStaticError("hashtable key not found") ErrAllocationLimitExceeded = NewStaticError("allocation limit exceeded") ErrNonContinuableException = NewStaticError("non-continuable exception") ErrCallDepthExceeded = NewStaticError("call depth exceeded") ErrParseDepthExceeded = NewStaticError("parse nesting depth exceeded") ErrExpandDepthExceeded = NewStaticError("macro expansion nesting depth exceeded") ErrWriteDepthExceeded = NewStaticError("write nesting depth exceeded") ErrExpiredEscape = NewStaticError("expired escape procedure") ErrContinuationBarrier = NewStaticError("continuation barrier violation") ErrRandomGenerationFailed = NewStaticError("random generation failed") ErrInvalidLoadPath = NewStaticError("invalid load path") // ErrOperationCancelled is raised when a thread blocked acquiring a // synchronization primitive (rw-mutex lock) is unparked by ctx cancellation // before it acquires. mutex-lock! signals the same condition as #f (it has a // did-not-acquire value already). ErrOperationCancelled = NewStaticError("synchronization operation cancelled") ErrNotAProcess = NewTypeSentinel("process") ErrJoinTimeout = NewStaticError("thread-join!: timeout") ErrThreadAlreadyStarted = NewStaticError("thread-start!: thread already started") ErrCrossThreadContinuation = NewStaticError("cannot invoke continuation from different thread") )
Standard error values for type checking and runtime errors.
Functions ¶
func RecoverAsError ¶ added in v1.19.0
RecoverAsError normalizes the value returned by recover() into an error carrying the caller's sentinel.
A nil r (no panic in flight) yields a nil error, so a deferred closure may assign the result unconditionally. Every other value acquires the sentinel: an r that is already an error is chained as the cause, and any other value (panic("...") / panic(42)) has its text preserved in the message.
The sentinel must reach an error-typed r, not just a string one. A Go runtime fault inside foreign code — nil deref, index out of range, nil-map write — arrives here as a runtime.Error, which satisfies error. Returning it unchanged would strip the site's sentinel from precisely the panics that indicate host memory corruption, leaving them indistinguishable at the VM boundary from a deliberate (error "...") raised by a well-behaved primitive.
Chaining as a cause rather than returning unchanged does not disturb callers that route on the panic's identity: ForeignError.Is/As traverse the cause, so the VM's foreign-call bridge still matches prompt-abort, exception-escape, timer-interrupt, and continuation-resume signals through the wrap. No site type-asserts those signals directly.
The sentinel is a parameter rather than a fixed ErrInternal because each recover site's sentinel is part of that site's contract: the VM boundary reports ErrInternal, a thread root reports ErrThreadPanic, a foreign call reports ErrPanicRecovery.
site names the recovering site and prefixes the message, e.g. "thread \"w\"" or "foreign function call". Pass "" when the caller wraps the result again with its own prefix, so the site name does not appear twice.
func TypeNameOf ¶
TypeNameOf extracts the expected-type phrase from any error wrapping a type-mismatch sentinel. Returns "" for non-sentinel errors or sentinels without a type name. Use this in helpers that format error messages from a sentinel parameter — it works regardless of where the helper lives in the dependency graph.
Types ¶
type ForeignError ¶
type ForeignError struct {
// contains filtered or unexported fields
}
ForeignError is an error type for Go primitive implementations (functions foreign to Scheme). It wraps an optional underlying error with a message.
func NewForeignErrorf ¶
func NewForeignErrorf(msg string, vs ...any) *ForeignError
NewForeignErrorf creates a new foreign error with a formatted message.
func WrapForeignErrorWithCause ¶
func WrapForeignErrorWithCause(sentinel, cause error, msg string, vs ...any) *ForeignError
WrapForeignErrorWithCause wraps a sentinel and a root cause into a single ForeignError. The sentinel is matched by errors.Is for programmatic dispatch; the cause preserves the underlying failure for diagnostics.
func WrapForeignErrorf ¶
func WrapForeignErrorf(err error, msg string, vs ...any) *ForeignError
WrapForeignErrorf wraps an existing error with a formatted message.
func (*ForeignError) As ¶
func (p *ForeignError) As(target any) bool
As checks whether the sentinel or cause can be assigned to target.
func (*ForeignError) Cause ¶
func (p *ForeignError) Cause() error
Cause returns the root cause error, if any. Useful for debugging/logging when you need the underlying failure directly.
func (*ForeignError) Error ¶
func (p *ForeignError) Error() string
func (*ForeignError) Is ¶
func (p *ForeignError) Is(target error) bool
Is reports whether target matches the sentinel or the cause. This replaces Unwrap and gives ForeignError precise two-chain semantics: the sentinel identifies the error category, the cause preserves the root failure from the underlying operation.
type ForeignFileError ¶
type ForeignFileError struct {
*ForeignError
Filename string // the file path that caused the error
Op string // the operation (e.g., "open-input-file", "delete-file")
}
ForeignFileError represents an error from a file system operation. R7RS §6.11: detected by file-error? predicate.
func WrapForeignFileError ¶
func WrapForeignFileError(err error, op string, filename string) *ForeignFileError
WrapForeignFileError wraps an OS error with file context.
type ForeignProcessError ¶
type ForeignProcessError struct {
*ForeignError
Command string // the command that was run
Op string // the operation (e.g., "process-spawn", "system")
}
ForeignProcessError represents an error from a process operation. Parallel to ForeignFileError for programmatic inspection of failed process operations.
func WrapForeignProcessError ¶
func WrapForeignProcessError(err error, op string, command string) *ForeignProcessError
WrapForeignProcessError wraps an OS error with process context.
type ForeignReadError ¶
type ForeignReadError struct {
*ForeignError
}
ForeignReadError represents an error from a read or parse operation. R7RS §6.11: detected by read-error? predicate.
func NewForeignReadErrorf ¶
func NewForeignReadErrorf(msg string, vs ...any) *ForeignReadError
NewForeignReadErrorf creates a new read error with a formatted message.
func WrapForeignReadErrorf ¶
func WrapForeignReadErrorf(err error, msg string, vs ...any) *ForeignReadError
WrapForeignReadErrorf wraps an error as a read error.
type StaticError ¶
type StaticError struct {
// contains filtered or unexported fields
}
StaticError is a sentinel error type for programmatic matching via errors.Is. Each sentinel carries a fixed human-readable message and serves as a stable identity that callers can match across error wrapping layers.
Type-mismatch sentinels (declared via NewTypeSentinel) additionally carry an expectedType phrase (e.g., "a string") used by argument-extraction helpers in registry/helpers to format error messages without each call site repeating the phrase.
func NewStaticError ¶
func NewStaticError(msg string) *StaticError
NewStaticError creates a new static error with the given message. The returned sentinel has no expectedType; callers using it with type-checking helpers will get a degraded ("expected but got ...") error message. Use NewTypeSentinel for type-mismatch sentinels.
func NewTypeSentinel ¶
func NewTypeSentinel(noun string) *StaticError
NewTypeSentinel creates a sentinel for a type-mismatch error. The noun argument is the bare type-name ("string", "integer", "char-set", …); NewTypeSentinel auto-prefixes "a"/"an" using articleFor. The sentinel's Error() value is "not " + article + " " + noun, e.g. "not a string" or "not an integer".
For irregular cases where letter-based article selection produces the wrong result (e.g., "once" pronounced /wuns/ wants "a", not "an"), pass the already-articled phrase: NewTypeSentinel("a once"). Inputs starting with "a " or "an " are used verbatim.
Panics on empty noun — a type sentinel without a noun is a programmer bug, since the resulting "expected " phrase would be useless. Use NewStaticError for sentinels that aren't type-mismatch errors.
func (*StaticError) Error ¶
func (p *StaticError) Error() string
func (*StaticError) TypeName ¶
func (p *StaticError) TypeName() string
TypeName returns the expected-type phrase for type-mismatch sentinels (those constructed via NewTypeSentinel). Returns "" for sentinels constructed via NewStaticError.
Source Files