README
¶
SourceError
Purpose
This module offers the ErrSource error type that wraps another error instance, along with the file name, line number, and function name where the error occurred.
All public fields should be considered R/O - there really isn't any reason to modify those fields apart from confusing yourself :-) The fields are as follows:
- `File`: The source file where the error was encountered.
- `Function`: The function wherein the error was encountered
- `Line`: The code line within the `File`.
- `Stack`: The call stack to where the error was created.
The ErrSource methods Error() and String() mention another field
- `Error`: The string representation of the wrapped error.
The ErrSource can be used especially during development to help finding problems in the source code.
In case the error call-stacks are not needed just set the NOSTACK flag to true (which will save some time an memory).
Once the source code is free of avoidable errors, just set the NODEBUG flag to true without any need to change the source code otherwise.
Installation
You can use Go to install this package for you:
go get -u github.com/mwat56/sourceerror
Usage
It can be used by calling the provided constructor function:
import (
"github.com/mwat56/sourceerror"
)
// ...
// if the call-stacks are not needed:
sourceerror.NOSTACK = true
// uncomment the next line when your code is production ready:
// sourceerror.NODEBUG = true
// ...
// here some error occurs:
err := someFunction()
if nil != err {
err = sourceerror.Wrap(err, 2)
// `err` now wraps the original 'err` and points
// two lines up i.e. to the line where the error
// was encountered.
return err
// ... or perform some proper error handling here
}
// ...
Libraries
No external libraries were used building sourceerror.
Licence
Copyright © 2024 M.Watermann, 10247 Berlin, Germany
All rights reserved
EMail : <support@mwat.de>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.
Documentation
¶
Overview ¶
Package sourceerror implements an error type that wraps another error instance. That error type includes the file name, line number, and function name where the error occurred, along with original error's text.
Copyright © 2024 M.Watermann, 10247 Berlin, Germany
All rights reserved
EMail : <support@mwat.de>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.
Copyright © 2024 M.Watermann, 10247 Berlin, Germany
All rights reserved EMail : <support@mwat.de>
Index ¶
Constants ¶
const (
// The constant error message of the `ErrSourceLocation` error type.
StringSourceLocation = "error in source"
)
Variables ¶
var ( // If set `true`, the `Wrap()` function will skip the error // location investigation. NODEBUG bool // If set `true`, the `Wrap()` function will skip the error's // call-stack investigation. NOSTACK bool )
Functions ¶
func Wrap ¶ added in v0.2.0
`Wrap()` is a function that wraps an error with additional information about the location where the error occurred. It uses certain `runtime` functions to determine the file- and function-names, as well as the code line and the call stack. The `aLines` parameter allows for adjusting the reported line number by subtracting the specified number of lines from the actual line number.
NOTE: If the global `NODEBUG` flag is `true`, this function returns an instance with the given `aErr`, while file, function, line number, stacktrace fields remain empty.
Parameters: - `aErr`: The error to be wrapped. - `aLines`: The number of lines to subtract from the caller's line number.
Returns: - `error`: A new `ErrSourceLocation` instance that contains `aErr`, as well as file, function, and adjusted line number of the code causing the error.
Types ¶
type ErrSource ¶ added in v0.2.0
type ErrSource struct {
File string // 16 bytes
Function string // dito
Line int // 8 bytes
Stack []byte // 24 bytes
// contains filtered or unexported fields
}
`ErrSource` is an error type that wraps another error with the location of where that other error was encountered. All public fields should be considered R/O (there really isn't any reason to modify those fields apart from confusing yourself).
The fields are as follows: - `File`: The source file where the error was encountered. - `Function`: The function wherein the error was encountered - `Line`: The code line within the `File`. - `Stack`: The call stack to where the error was created.
func (ErrSource) Error ¶ added in v0.2.0
`Error()` returns a string representation of the error message along with the error location.
It includes the file name, line number, and function name where the error occurred, along with original error's text.
Returns: - `string`: a string representation of the error message and location.
func (ErrSource) String ¶ added in v0.2.0
`String()` implements the `Stringer` interface and returns a string representation of the error location.
It includes the file name, line number, and function name where the error occurred ass well as a call stack.
Returns: - `string`: a string representation of the error location.
Source Files