exc: Move exception-style error-handling routines from git-backup[1] here

This is pristine import. Files are taken as-is from git-backup 3ba6cf73.
Will adapt them to live in separate package in the next commit.

[1] https://lab.nexedi.com/kirr/git-backup

exc/error.go

+// Copyright (C) 2015-2016  Nexedi SA and Contributors.
+//                          Kirill Smelkov <kirr@nexedi.com>
+//
+// This program is free software: you can Use, Study, Modify and Redistribute
+// it under the terms of the GNU General Public License version 3, or (at your
+// option) any later version, as published by the Free Software Foundation.
+//
+// This program is distributed WITHOUT ANY WARRANTY; without even the implied
+// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+//
+// See COPYING file for full licensing terms.
+
+// Git-backup | Exception-style errors
+package main
+
+import (
+    "fmt"
+    "runtime"
+    "strings"
+)
+
+// error type which is raised by raise(arg)
+type Error struct {
+    arg  interface{}
+    link *Error // chain of linked Error(s) - see e.g. errcontext()
+}
+
+func (e *Error) Error() string {
+    msgv := []string{}
+    msg := ""
+    for e != nil {
+        // TODO(go1.7) -> runtime.Frame  (see xtraceback())
+        if f, ok := e.arg.(Frame); ok {
+            //msg = f.Function
+            //msg = fmt.Sprintf("%s (%s:%d)", f.Function, f.File, f.Line)
+            msg = strings.TrimPrefix(f.Name(), _errorpkgdot) // XXX -> better prettyfunc
+        } else {
+            msg = fmt.Sprint(e.arg)
+        }
+        msgv = append(msgv, msg)
+        e = e.link
+    }
+
+    return strings.Join(msgv, ": ")
+}
+
+// turn any value into Error
+// if v is already Error - it stays the same
+// otherwise new Error is created
+func aserror(v interface{}) *Error {
+    if e, ok := v.(*Error); ok {
+        return e
+    }
+    return &Error{v, nil}
+}
+
+// raise error to upper level
+func raise(arg interface{}) {
+    panic(aserror(arg))
+}
+
+// raise formatted string
+func raisef(format string, a ...interface{}) {
+    panic(aserror(fmt.Sprintf(format, a...)))
+}
+
+// raise if err != nil
+// NOTE err can be != nil even if typed obj = nil:
+//   var obj *T;
+//   err = obj
+//   err != nil     is true
+func raiseif(err error) {
+    //if err != nil && !reflect.ValueOf(err).IsNil() {
+    if err != nil {
+        panic(aserror(err))
+    }
+}
+
+// checks recovered value to be of *Error
+// if there is non-Error error - repanic it
+// otherwise return Error either nil (no panic), or actual value
+func _errcatch(r interface{}) *Error {
+    e, _ := r.(*Error)
+    if e == nil && r != nil {
+        panic(r)
+    }
+    return e
+}
+
+// catch error and call f(e) if it was caught.
+// must be called under defer
+func errcatch(f func(e *Error)) {
+    e := _errcatch(recover())
+    if e == nil {
+        return
+    }
+
+    f(e)
+}
+
+// be notified when error unwinding is being happening.
+// hook into unwinding process with f() call. Returned error is reraised.
+// see also: errcontext()
+// must be called under defer
+func erronunwind(f func(e *Error) *Error) {
+    // cannot do errcatch(...)
+    // as recover() works only in first-level called functions
+    e := _errcatch(recover())
+    if e == nil {
+        return
+    }
+
+    e = f(e)
+    panic(e)
+}
+
+// provide error context to automatically add on unwinding.
+// f is called if error unwinding is happening.
+// call result is added to raised error as "prefix" context
+// must be called under defer
+func errcontext(f func() interface{}) {
+    e := _errcatch(recover())
+    if e == nil {
+        return
+    }
+
+    arg := f()
+    panic(erraddcontext(e, arg))
+}
+
+// add "prefix" context to error
+func erraddcontext(e *Error, arg interface{}) *Error {
+    return &Error{arg, e}
+}
+
+func _myfuncname(nskip int) string {
+    pcv := [1]uintptr{}
+    runtime.Callers(nskip, pcv[:])
+    f := runtime.FuncForPC(pcv[0])
+    if f == nil {
+        return ""
+    }
+    return f.Name()
+}
+
+// get name of currently running function (caller of myfuncname())
+// name is fully qualified package/name.function(.x)
+func myfuncname() string {
+    return _myfuncname(3)
+}
+
+// get name of currently running function's package
+// package is fully qualified package/name
+func mypkgname() string {
+    myfunc := _myfuncname(3)
+    if myfunc == "" {
+        return ""
+    }
+    // NOTE dots in package name are after last slash are escaped by go as %2e
+    // this way the first '.' after last '/' is delimiter between package and function
+    //
+    // lab.nexedi.com/kirr/git-backup/package%2ename.Function
+    // lab.nexedi.com/kirr/git-backup/pkg2.qqq/name%2ezzz.Function
+    islash := strings.LastIndexByte(myfunc, '/')
+    iafterslash := islash + 1   // NOTE if '/' not found iafterslash = 0
+    idot := strings.IndexByte(myfunc[iafterslash:], '.')
+    if idot == -1 {
+        panic(fmt.Errorf("funcname %q is not fully qualified", myfunc))
+    }
+    return myfunc[:iafterslash+idot]
+}
+
+// TODO(go1.7) goes away in favour of runtime.Frame
+type Frame struct {
+    *runtime.Func
+    pc  uintptr
+}
+
+// get current calling traceback as []Frame
+// nskip meaning: the same as in runtime.Callers()
+// TODO(go1.7) []Frame -> []runtime.Frame
+func xtraceback(nskip int) []Frame {
+    // all callers
+    var pcv = []uintptr{0}
+    for {
+        pcv = make([]uintptr, 2*len(pcv))
+        n := runtime.Callers(nskip+1, pcv)
+        if n < len(pcv) {
+            pcv = pcv[:n]
+            break
+        }
+    }
+
+    // pcv -> frames
+/*
+    framev := make([]runtime.Frame, 0, len(pcv))
+    frames := runtime.CallersFrames(pcv)
+    for more := true; more; {
+        var frame runtime.Frame
+        frame, more = frames.Next()
+        framev = append(framev, frame)
+    }
+*/
+    framev := make([]Frame, 0, len(pcv))
+    for _, pc := range pcv {
+        framev = append(framev, Frame{runtime.FuncForPC(pc), pc})
+    }
+
+    return framev
+}
+
+var (
+    _errorpkgname string // package name under which error.go lives
+    _errorpkgdot  string // errorpkg.
+    _errorraise   string // errorpkg.raise
+)
+
+func init() {
+    _errorpkgname = mypkgname()
+    _errorpkgdot  = _errorpkgname + "."
+    _errorraise   = _errorpkgname + ".raise"
+}
+
+// add calling context to error.
+// Add calling function names as error context up-to topfunc not including.
+// see also: erraddcontext()
+func erraddcallingcontext(topfunc string, e *Error) *Error {
+    seenraise := false
+    for _, f := range xtraceback(2) {
+        // do not show anything after raise*()
+        if !seenraise && strings.HasPrefix(f.Name(), _errorraise) {
+            seenraise = true
+            continue
+        }
+        if !seenraise {
+            continue
+        }
+
+        // do not go beyond topfunc
+        if topfunc != "" && f.Name() == topfunc {
+            break
+        }
+
+        // skip intermediates
+        if strings.HasSuffix(f.Name(), "_") { // XXX -> better skipfunc
+            continue
+        }
+
+        e = &Error{f, e}
+    }
+
+    return e
+}
+
+// error merging multiple errors (e.g. after collecting them from several parallel workers)
+type Errorv []error
+
+func (ev Errorv) Error() string {
+    if len(ev) == 1 {
+        return ev[0].Error()
+    }
+
+    msg := fmt.Sprintf("%d errors:\n", len(ev))
+    for _, e := range ev {
+        msg += fmt.Sprintf("\t- %s\n", e)
+    }
+    return msg
+}

exc/error_test.go

+// Copyright (C) 2015-2016  Nexedi SA and Contributors.
+//                          Kirill Smelkov <kirr@nexedi.com>
+//
+// This program is free software: you can Use, Study, Modify and Redistribute
+// it under the terms of the GNU General Public License version 3, or (at your
+// option) any later version, as published by the Free Software Foundation.
+//
+// This program is distributed WITHOUT ANY WARRANTY; without even the implied
+// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+//
+// See COPYING file for full licensing terms.
+
+package main
+
+import (
+    "errors"
+    "strings"
+    "testing"
+)
+
+func do_raise1() {
+    raise(1)
+}
+
+func TestErrRaiseCatch(t *testing.T) {
+    defer errcatch(func(e *Error) {
+        if !(e.arg == 1 && e.link == nil) {
+            t.Fatalf("error caught but unexpected: %#v  ; want {1, nil}", e)
+        }
+    })
+    do_raise1()
+    t.Fatal("error not caught")
+}
+
+// verify err chain has .arg(s) as expected
+func verifyErrChain(t *testing.T, e *Error, argv ...interface{}) {
+    i := 0
+    for ; e != nil; i, e = i+1, e.link {
+        if i >= len(argv) {
+            t.Fatal("too long error chain")
+        }
+        if e.arg != argv[i] {
+            t.Fatalf("error caught but unexpected %vth arg: %v  ; want %v", i, e.arg, argv[i])
+        }
+    }
+    if i < len(argv) {
+        t.Fatal("too small error chain")
+    }
+}
+
+func do_onunwind1(t *testing.T) {
+    defer erronunwind(func(e *Error) *Error {
+        t.Fatal("on unwind called without raise")
+        return nil
+    })
+}
+
+func do_onunwind2() {
+    defer erronunwind(func(e *Error) *Error {
+        return &Error{2, e}
+    })
+    do_raise1()
+}
+
+func TestErrOnUnwind(t *testing.T) {
+    defer errcatch(func(e *Error) {
+        verifyErrChain(t, e, 2, 1)
+    })
+    do_onunwind1(t)
+    do_onunwind2()
+    t.Fatal("error not caught")
+}
+
+func do_context1(t *testing.T) {
+    defer errcontext(func() interface{} {
+        t.Fatal("on context called without raise")
+        return nil
+    })
+}
+
+func do_context2() {
+    defer errcontext(func() interface{} {
+        return 3
+    })
+    do_raise1()
+}
+
+func TestErrContext(t *testing.T) {
+    defer errcatch(func(e *Error) {
+        verifyErrChain(t, e, 3, 1)
+    })
+    do_context1(t)
+    do_context2()
+    t.Fatal("error not caught")
+}
+
+func TestMyFuncName(t *testing.T) {
+    myfunc := myfuncname()
+    // go test changes full package name (putting filesystem of the tree into ti)
+    // thus we check only for suffix
+    wantsuffix := ".TestMyFuncName"
+    if !strings.HasSuffix(myfunc, wantsuffix) {
+        t.Errorf("myfuncname() -> %v  ; want *%v", myfunc, wantsuffix)
+    }
+}
+
+func do_raise11() {
+    do_raise1()
+}
+
+func do_raise3if() {
+    raiseif(errors.New("3"))
+}
+
+func do_raise3if1() {
+    do_raise3if()
+}
+
+func do_raise4f() {
+    raisef("%d", 4)
+}
+
+func do_raise4f1() {
+    do_raise4f()
+}
+
+
+func TestErrAddCallingContext(t *testing.T) {
+    var tests = []struct{ f func(); wanterrcontext string } {
+        {do_raise11,    "do_raise11: do_raise1: 1"},
+        {do_raise3if1,  "do_raise3if1: do_raise3if: 3"},
+        {do_raise4f1,   "do_raise4f1: do_raise4f: 4"},
+    }
+
+    for _, tt := range tests {
+        func() {
+            myfunc := myfuncname()
+            defer errcatch(func(e *Error) {
+                e = erraddcallingcontext(myfunc, e)
+                msg := e.Error()
+                if msg != tt.wanterrcontext {
+                    t.Fatalf("err + calling context: %q  ; want %q", msg, tt.wanterrcontext)
+                }
+            })
+            tt.f()
+            t.Fatal("error not caught")
+        }()
+    }
+
+}