From 9504c8a01b06507d34439ad6a1f1c020347924cc Mon Sep 17 00:00:00 2001
From: Timon Ringwald <timon.ringwald@m2xpert.com>
Date: Wed, 9 Sep 2020 11:55:13 +0200
Subject: [PATCH] added README

---
 README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 193 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..94256f3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,193 @@
+# adverr
+--
+    import "adverr"
+
+Package adverr implements errors with call stack traces as well as error
+templates for error equality
+
+
+Usage examples
+
+Creating templates:
+
+    var (
+    	ErrDoStuffFailed = adverr.NewErrTmpl("ErrDoStuffFailed", "Could'nt do stuff because of %s")
+    )
+
+Creating independent error (without error template):
+
+    func doStuffWithIndependentErr() error {
+    	return adverr.New("Could'nt do stuff")
+    }
+
+Creating error based on template:
+
+    func doStuff() error {
+    	return ErrDoStuffFailed.New("reasons")
+    }
+
+Printing errors on stderr convieniently:
+
+    Print(myErr)
+    Println(myErr)
+
+Printing errors on stderr and exit with exitcode:
+
+    Fatal(myErr, 1)
+    Fatalln(myErr, 1)
+
+Advantages of error templates
+
+    two errors made by the same template will return true when called with errors.Is()
+
+## Usage
+
+```go
+var CallStackLength int = 100
+```
+CallStackLength decides how many calls from the call stack should be gathered at
+most
+
+```go
+var (
+	// ErrTmplUsedAsErr is returned from ErrTmpl.Error() because an error template should never be used as an actual error value
+	ErrTmplUsedAsErr = NewErrTmpl("ErrTmplUsedAsErr", "Error template used as error value: %s")
+)
+```
+
+```go
+var TraceCallStack bool = true
+```
+TraceCallStack decides if any call stack traces will be gathered when creating
+Errors If your application is doing performance-heavy tasks with lots of Error
+creations, you may consider setting this to false If set to false, all
+CallTraces in Error will be nil
+
+#### func  Fatal
+
+```go
+func Fatal(err error, exitcode int)
+```
+Fatal prints the given err to stderr and exits immediately with the given exit
+code
+
+#### func  Fatalln
+
+```go
+func Fatalln(err error, exitcode int)
+```
+Fatalln prints the given err to stderr followed by a newline and exits
+immediately with the given exit code
+
+#### func  Print
+
+```go
+func Print(err error)
+```
+Print prints the given err to stderr
+
+#### func  Println
+
+```go
+func Println(err error)
+```
+Println prints the given err to stderr followed by a newline
+
+#### type CallTrace
+
+```go
+type CallTrace struct {
+}
+```
+
+CallTrace represents a call stack trace similar to Java's stack trace
+
+#### func  Trace
+
+```go
+func Trace(skip int) *CallTrace
+```
+Trace returns a new CallTrace starting from this call Use skip to skip the first
+entries in the trace
+
+#### func (*CallTrace) String
+
+```go
+func (ct *CallTrace) String() string
+```
+
+#### type ErrTmpl
+
+```go
+type ErrTmpl struct {
+}
+```
+
+ErrTmpl is an error template to define equalities between different errors
+
+#### func  NewErrTmpl
+
+```go
+func NewErrTmpl(name, format string) *ErrTmpl
+```
+NewErrTmpl returns a new error template with the given format string as a
+predefined error message
+
+#### func (*ErrTmpl) Error
+
+```go
+func (t *ErrTmpl) Error() string
+```
+Error implementation just for satisfying the error interface Please dont use
+ErrTmpls as actual errors
+
+#### func (*ErrTmpl) New
+
+```go
+func (t *ErrTmpl) New(args ...interface{}) *Error
+```
+New returns a new Error in which the given values are being formatted into the
+format string of its template
+
+#### type Error
+
+```go
+type Error struct {
+}
+```
+
+Error is a wrapper for error with stack trace
+
+#### func  New
+
+```go
+func New(msg string) *Error
+```
+New returns a new Error with the given message
+
+#### func  Wrap
+
+```go
+func Wrap(msg string, cause error) *Error
+```
+Wrap returns a new Error with the given message which is caused by cause
+
+#### func (*Error) Error
+
+```go
+func (e *Error) Error() string
+```
+
+#### func (*Error) Is
+
+```go
+func (e *Error) Is(target error) bool
+```
+Is implements the error equality function used by errors.Is() It returns true if
+the error is the same instance or is created using the same ErrTmpl
+
+#### func (*Error) Unwrap
+
+```go
+func (e *Error) Unwrap() error
+```