Merge pull request #62 from cdr/force-json-example

Add ForceJSON example

Author: nhooyr

README.md

@@ -92,7 +92,7 @@ Here is a list of reasons how we improved on zap with slog.
 
 1. Structured logging of Go structures with `json.Marshal`
     - All values will be logged with `json.Marshal` unless they implement `fmt.Stringer` or `error`.
-        - You can force JSON by using [`slog.JSON`](https://godoc.org/cdr.dev/slog#JSON). 
+        - You can force JSON by using [`slog.ForceJSON`](https://godoc.org/cdr.dev/slog#ForceJSON). 
     - One may implement [`slog.Value`](https://godoc.org/cdr.dev/slog#Value) to override the representation completely.
     - With zap, We found ourselves often implementing zap's
       [ObjectMarshaler](https://godoc.org/go.uber.org/zap/zapcore#ObjectMarshaler) to log Go structures. This was

example_force_json_test.go

@@ -0,0 +1,30 @@
+package slog_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+)
+
+type stringer struct {
+	X int `json:"x"`
+}
+
+func (s *stringer) String() string {
+	return fmt.Sprintf("string method: %v", s.X)
+}
+
+func (s *stringer) SlogValue() interface{} {
+	return slog.ForceJSON(s)
+}
+
+func ExampleForceJSON() {
+	l := sloghuman.Make(os.Stdout)
+
+	l.Info(context.Background(), "hello", slog.F("stringer", &stringer{X: 3}))
+
+	// 2019-12-06 23:33:40.263 [INFO]	<example_force_json_test.go:27>	hello	{"stringer": {"x": 3}}
+}

examples_test.go renamed to example_test.go

@@ -34,9 +34,11 @@ func (m Map) MarshalJSON() ([]byte, error) {
 	return b.Bytes(), nil
 }
 
-// JSON ensures the value is logged via json.Marshal even
-// in the presence of the fmt.Stringer and error interfaces.
-func JSON(v interface{}) interface{} {
+// ForceJSON ensures the value is logged via json.Marshal even
+// if it implements fmt.Stringer or error.
+//
+// See the ForceJSON example.
+func ForceJSON(v interface{}) interface{} {
 	return jsonVal{v: v}
 }
 
@@ -70,7 +72,7 @@ func marshalArray(a []interface{}) []byte {
 func encode(v interface{}) []byte {
 	switch v := v.(type) {
 	case Value:
-		return encode(v.LogValue())
+		return encode(v.SlogValue())
 	case []interface{}:
 		return marshalArray(v)
 	case xerrors.Formatter:

map.go

@@ -92,7 +92,7 @@ func TestMap(t *testing.T) {
 					{
 						"msg": "failed to marshal to JSON",
 						"fun": "cdr.dev/slog.encode",
-						"loc": "`+mapTestFile+`:84"
+						"loc": "`+mapTestFile+`:86"
 					},
 					"json: unsupported type: func(*testing.T, string) string"
 				],
@@ -148,7 +148,7 @@ func TestMap(t *testing.T) {
 		t.Parallel()
 
 		test(t, slog.M(
-			slog.F("error", slog.JSON(io.EOF)),
+			slog.F("error", slog.ForceJSON(io.EOF)),
 		), `{
 			"error": {}
 		}`)
@@ -169,7 +169,7 @@ type meow struct {
 	a int
 }
 
-func (m meow) LogValue() interface{} {
+func (m meow) SlogValue() interface{} {
 	return "xdxd"
 }
 

map_test.go

@@ -34,10 +34,10 @@ func M(fs ...Field) Map {
 }
 
 // Value represents a log value.
-// Implement LogValue in your own types to override
+// Implement SlogValue in your own types to override
 // the value encoded when logging.
 type Value interface {
-	LogValue() interface{}
+	SlogValue() interface{}
 }
 
 // Error is the standard key used for logging a Go error value.