docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd)
- cooler: ExampleFromApp and the articlesController purge declarations; AllowExport run by TestDocsAllowExport on miniredis - diary: blogLog and ExampleFor; the generated main's run function, run by TestDocsRun in a temp directory with diary.Reset on cleanup - festival: PostPublished/ExampleBus_Fire and PostFormExtended/Collected/ ExampleBus_Collect, with a TestDocsDeclarations for Collected - fetchguard: fetch region run by TestDocsFetchImage (loopback refused as private_ip), client region run by TestDocsSyncItems on a stub transport
This commit is contained in:
@@ -41,12 +41,31 @@ Use cases:
|
||||
|
||||
A plugin or module creates its logger once:
|
||||
|
||||
```go
|
||||
var logger = diary.For("blog")
|
||||
```go src=modules/diary/example_test.go#blogLog
|
||||
// blogLog is the component logger of a blog plugin, created once in a
|
||||
// package var block, before diary is set up.
|
||||
var blogLog = diary.For("blog")
|
||||
```
|
||||
|
||||
func publish(ctx context.Context, id int) {
|
||||
logger.InfoContext(ctx, "post published", "id", id)
|
||||
}
|
||||
```go src=modules/diary/example_test.go#ExampleFor
|
||||
// Before diary.Setup runs, records go to the process default logger.
|
||||
// This one drops the time so the output is stable.
|
||||
previous := slog.Default()
|
||||
defer slog.SetDefault(previous)
|
||||
slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
|
||||
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
|
||||
if len(groups) == 0 && a.Key == slog.TimeKey {
|
||||
return slog.Attr{}
|
||||
}
|
||||
return a
|
||||
},
|
||||
})))
|
||||
|
||||
// After diary.Setup the same record reaches the configured channels and
|
||||
// passes log.components.blog, else log.level.
|
||||
blogLog.InfoContext(context.Background(), "post published", "id", 7)
|
||||
// Output:
|
||||
// level=INFO msg="post published" component=blog id=7
|
||||
```
|
||||
|
||||
With the default configuration this prints on a terminal:
|
||||
@@ -59,8 +78,10 @@ and writes warnings and errors as JSON to `storage/logs/summer-YYYY-MM-DD.log`.
|
||||
|
||||
The generated `main` installs it:
|
||||
|
||||
```go
|
||||
func run(args []string, out io.Writer) int {
|
||||
```go src=modules/diary/example_test.go#run
|
||||
// run is the body of the generated main, which calls
|
||||
// os.Exit(run(os.Args[1:], os.Stdout, commands)).
|
||||
func run(args []string, out io.Writer, commands []bonfire.Command) int {
|
||||
g := bonfire.PeekGlobals(args)
|
||||
diary.Bootstrap(os.Stderr, diary.FromGlobals(g))
|
||||
cfg, err := compass.Open(compass.Options{Dir: "config", Env: g.Env})
|
||||
@@ -70,10 +91,12 @@ func run(args []string, out io.Writer) int {
|
||||
if err := diary.Setup(cfg, diary.FromGlobals(g)); err != nil {
|
||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||
}
|
||||
// ...
|
||||
root, err := bonfire.NewRoot("acme", commands, out,
|
||||
bonfire.WithVersion(bonfire.BuildVersion()), bonfire.OnGlobals(diary.ApplyGlobals))
|
||||
// ...
|
||||
if err != nil {
|
||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||
}
|
||||
return bonfire.Execute(context.Background(), root, args)
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
package diary_test
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"io"
|
||||
"log/slog"
|
||||
"os"
|
||||
"testing"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/bonfire"
|
||||
"git.golem15.com/golem15/summercms/modules/compass"
|
||||
"git.golem15.com/golem15/summercms/modules/diary"
|
||||
)
|
||||
|
||||
@@ -32,3 +37,49 @@ func ExampleFor() {
|
||||
// Output:
|
||||
// level=INFO msg="post published" component=blog id=7
|
||||
}
|
||||
|
||||
// run is the body of the generated main, which calls
|
||||
// os.Exit(run(os.Args[1:], os.Stdout, commands)).
|
||||
func run(args []string, out io.Writer, commands []bonfire.Command) int {
|
||||
g := bonfire.PeekGlobals(args)
|
||||
diary.Bootstrap(os.Stderr, diary.FromGlobals(g))
|
||||
cfg, err := compass.Open(compass.Options{Dir: "config", Env: g.Env})
|
||||
if err != nil {
|
||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||
}
|
||||
if err := diary.Setup(cfg, diary.FromGlobals(g)); err != nil {
|
||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||
}
|
||||
root, err := bonfire.NewRoot("acme", commands, out,
|
||||
bonfire.WithVersion(bonfire.BuildVersion()), bonfire.OnGlobals(diary.ApplyGlobals))
|
||||
if err != nil {
|
||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||
}
|
||||
return bonfire.Execute(context.Background(), root, args)
|
||||
}
|
||||
|
||||
// TestDocsRun runs a command through run in an application directory
|
||||
// without a config/ directory, then restores the process logger.
|
||||
func TestDocsRun(t *testing.T) {
|
||||
t.Chdir(t.TempDir())
|
||||
t.Cleanup(diary.Reset)
|
||||
publish := bonfire.Command{
|
||||
Name: "blog:publish",
|
||||
Description: "Publish a post",
|
||||
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
|
||||
blogLog.InfoContext(ctx, "post published", "id", 7)
|
||||
out.Println("published")
|
||||
return nil
|
||||
},
|
||||
}
|
||||
var out bytes.Buffer
|
||||
if code := run([]string{"blog:publish", "-vv"}, &out, []bonfire.Command{publish}); code != bonfire.ExitOK {
|
||||
t.Fatalf("exit code %d, output %q", code, out.String())
|
||||
}
|
||||
if out.String() != "published\n" {
|
||||
t.Fatalf("output = %q", out.String())
|
||||
}
|
||||
if diary.Verbosity() != 2 {
|
||||
t.Fatalf("verbosity = %d after -vv, want 2", diary.Verbosity())
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user