merge: added examples and added descriptions to README.md (#17)

README.md

@@ -23,11 +23,38 @@ Moreover, by separating as layers, applications using this framework can change
 <a name="usage"></a>
 ## Usage
 
-### Write logic
+1. [Write logics with a dax interface](#write_logic)
+2. [Write dax implementations](#write_dax)
+3. [Write mapping of a dax interface and dax implementations](#write_mapping)
+4. [Write execution of a procedure](#write_procedure)
 
-### Write dax
+<a name="write_logic"></a>
+### Write logics with a dax interface
+
+```
+  type MyDax interface {
+    GetData() (Data, sabi.Err)
+    SetData(data Data) sabi.Err
+  }
+
+  func MyLogic(dax Dax) sabi.Err {
+    data, err := dax.GetData()
+    if !err.IsOk() {
+      return err
+    }
+    return dax.SetData(data)
+  }
+```
+
+<a name="write_dax"></a>
+### Write dax implementations
+
+<a name="write_mapping"></a>
+### Write mapping of a dax interface and dax implementations
+
+<a name="write_procedure"></a>
+### Write execution of a procedure
 
-### Write procedure
 
 <a name="support-go-versions"></a>
 ## Supporting Go versions
@@ -36,8 +63,8 @@ This framework supports Go 1.18 or later.
 
 ### Actually checked Go versions:
 
-- 1.19.1
-- 1.18.6
+- 1.19.3
+- 1.18.8
 
 <a name="license"></a>
 ## License

example_conn_test.go

@@ -0,0 +1,138 @@
+package sabi_test
+
+import (
+	"fmt"
+	"github.com/sttk-go/sabi"
+	"reflect"
+)
+
+func unused(v interface{}) {}
+
+type FooConn struct {
+}
+
+func (conn *FooConn) Commit() sabi.Err {
+	return sabi.Ok()
+}
+
+func (conn *FooConn) Rollback() {
+}
+
+func (conn *FooConn) Close() {
+}
+
+type FooConnCfg struct {
+}
+
+func (cfg FooConnCfg) CreateConn() (sabi.Conn, sabi.Err) {
+	return &FooConn{}, sabi.Ok()
+}
+
+type BarConn struct {
+}
+
+func (conn *BarConn) Commit() sabi.Err {
+	return sabi.Ok()
+}
+
+func (conn *BarConn) Rollback() {
+}
+
+func (conn *BarConn) Close() {
+}
+
+type BarConnCfg struct {
+}
+
+func (cfg BarConnCfg) CreateConn() (sabi.Conn, sabi.Err) {
+	return &BarConn{}, sabi.Ok()
+}
+
+func ExampleAddGlobalConnCfg() {
+	sabi.AddGlobalConnCfg("foo", FooConnCfg{})
+	sabi.AddGlobalConnCfg("bar", BarConnCfg{})
+
+	base := sabi.NewConnBase()
+
+	type FooBarDax struct {
+		sabi.Dax
+	}
+
+	dax := FooBarDax{Dax: base}
+
+	conn, err := dax.GetConn("foo")
+	fmt.Printf("conn = %v\n", reflect.TypeOf(conn))
+	fmt.Printf("err.IsOk() = %v\n", err.IsOk())
+
+	conn, err = dax.GetConn("bar")
+	fmt.Printf("conn = %v\n", reflect.TypeOf(conn))
+	fmt.Printf("err.IsOk() = %v\n", err.IsOk())
+
+	// Output:
+	// conn = *sabi_test.FooConn
+	// err.IsOk() = true
+	// conn = *sabi_test.BarConn
+	// err.IsOk() = true
+
+	sabi.Clear()
+}
+
+func ExampleSealGlobalConnCfgs() {
+	sabi.AddGlobalConnCfg("foo", FooConnCfg{})
+	sabi.SealGlobalConnCfgs()
+	sabi.AddGlobalConnCfg("bar", BarConnCfg{}) // Bad example
+
+	base := sabi.NewConnBase()
+
+	type FooBarDax struct {
+		sabi.Dax
+	}
+
+	dax := FooBarDax{Dax: base}
+
+	conn, err := dax.GetConn("foo")
+	fmt.Printf("conn = %v\n", reflect.TypeOf(conn))
+	fmt.Printf("err.IsOk() = %v\n", err.IsOk())
+
+	conn, err = dax.GetConn("bar")
+	fmt.Printf("conn = %v\n", reflect.TypeOf(conn))
+	fmt.Printf("err.IsOk() = %v\n", err.IsOk())
+	fmt.Printf("err.Error() = %v\n", err.Error())
+
+	// Output:
+	// conn = *sabi_test.FooConn
+	// err.IsOk() = true
+	// conn = <nil>
+	// err.IsOk() = false
+	// err.Error() = {reason=ConnCfgIsNotFound, Name=bar}
+
+	sabi.Clear()
+}
+
+func ExampleNewConnBase() {
+	base := sabi.NewConnBase()
+
+	// Output:
+	unused(base)
+}
+
+func ExampleConnBase_AddLocalConnCfg() {
+	base := sabi.NewConnBase()
+	base.AddLocalConnCfg("foo", FooConnCfg{})
+
+	type FooBarDax struct {
+		sabi.Dax
+	}
+
+	dax := FooBarDax{Dax: base}
+
+	conn, err := dax.GetConn("foo")
+	fmt.Printf("conn = %v\n", reflect.TypeOf(conn))
+	fmt.Printf("err.IsOk() = %v\n", err.IsOk())
+
+	// Output:
+	// conn = *sabi_test.FooConn
+	// err.IsOk() = true
+
+	sabi.Clear()
+}

example_dax_test.go

@@ -0,0 +1,33 @@
+package sabi_test
+
+import (
+	"github.com/sttk-go/sabi"
+)
+
+func ExampleDax() {
+	base := sabi.NewConnBase()
+
+	type MyDax interface {
+		GetData() string
+		SetData(data string)
+	}
+
+	dax := struct {
+		FooGetterDax
+		BarSetterDax
+	}{
+		FooGetterDax: FooGetterDax{Dax: base},
+		BarSetterDax: BarSetterDax{Dax: base},
+	}
+
+	proc := sabi.NewProc[MyDax](base, dax)
+	proc.RunTxn(func(dax MyDax) sabi.Err {
+		data := dax.GetData()
+		dax.SetData(data)
+		return sabi.Ok()
+	})
+
+	// Output:
+
+	sabi.Clear()
+}

example_notify_test.go

@@ -0,0 +1,61 @@
+package sabi_test
+
+import (
+	"fmt"
+	"github.com/sttk-go/sabi"
+	"time"
+)
+
+func ExampleAddAsyncErrHandler() {
+	sabi.AddAsyncErrHandler(func(err sabi.Err, tm time.Time) {
+		fmt.Println("Asynchronous error handling: " + err.Error())
+	})
+	sabi.SealErrCfgs()
+
+	type FailToDoSomething struct{ Name string }
+
+	sabi.ErrBy(FailToDoSomething{Name: "abc"})
+
+	// Output:
+	// Asynchronous error handling: {reason=FailToDoSomething, Name=abc}
+
+	time.Sleep(100 * time.Millisecond)
+	sabi.ClearErrHandlers()
+}
+
+func ExampleAddSyncErrHandler() {
+	sabi.AddSyncErrHandler(func(err sabi.Err, tm time.Time) {
+		fmt.Println("Synchronous error handling: " + err.Error())
+	})
+	sabi.SealErrCfgs()
+
+	type FailToDoSomething struct{ Name string }
+
+	sabi.ErrBy(FailToDoSomething{Name: "abc"})
+
+	// Output:
+	// Synchronous error handling: {reason=FailToDoSomething, Name=abc}
+
+	sabi.ClearErrHandlers()
+}
+
+func ExampleSealErrCfgs() {
+	sabi.AddSyncErrHandler(func(err sabi.Err, tm time.Time) {
+		fmt.Println("This handler is registered")
+	})
+
+	sabi.SealErrCfgs()
+
+	sabi.AddSyncErrHandler(func(err sabi.Err, tm time.Time) { // Bad example
+		fmt.Println("This handler is not registered")
+	})
+
+	type FailToDoSomething struct{ Name string }
+
+	sabi.ErrBy(FailToDoSomething{Name: "abc"})
+
+	// Output:
+	// This handler is registered
+
+	sabi.ClearErrHandlers()
+}