Files
summercms/modules/bonfire/example_test.go
Jakub Zych a0f5b5e561 docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)
- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
2026-11-18 19:39:50 +01:00

230 lines
7.1 KiB
Go

package bonfire_test
import (
"context"
"errors"
"fmt"
"io"
"os"
"strings"
"git.golem15.com/golem15/summercms/modules/bonfire"
)
func ExampleCall() {
commands := []bonfire.Command{{
Name: "acme:greet",
Description: "Greet someone by name",
Args: []bonfire.Arg{{Name: "name", Required: true}},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
name, _ := in.Argument("name")
out.Printf("Hello, %s\n", name)
return nil
},
}}
if err := bonfire.Call(context.Background(), commands, "acme:greet", []string{"blog"}, os.Stdout); err != nil {
fmt.Println(err)
}
// Output: Hello, blog
}
func ExampleCatalog() {
publish := bonfire.Command{
Name: "blog:publish",
Description: "Publish a post",
Args: []bonfire.Arg{{Name: "slug", Description: "Post slug", Required: true}},
Flags: []bonfire.Flag{
{Name: "dry-run", Description: "Report without writing", Bare: true},
{Name: "tag", Description: "Tag to add (repeatable)", Repeatable: true},
},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
slug, _ := in.Argument("slug")
dryRun := bonfire.FlagBool(in, "dry-run")
out.Printf("publish %s, tags %v, dry run %v\n", slug, in.Flags("tag"), dryRun)
return nil
},
}
// The generated main publishes a catalog of every command on the app.
catalog := bonfire.NewCatalog([]bonfire.Command{publish})
args := []string{"hello-world", "--tag", "news", "--tag", "go", "--dry-run"}
if err := catalog.Call(context.Background(), "blog:publish", args, os.Stdout); err != nil {
fmt.Println(err)
}
// Output: publish hello-world, tags [news go], dry run true
}
func ExampleExample() {
export := bonfire.Command{
Name: "blog:export",
Description: "Export published posts as JSON",
Long: "Writes every published post, newest first, to a JSON file.",
Flags: []bonfire.Flag{
{Name: "path", Description: "Output file", Default: "posts.json"},
},
Examples: []bonfire.Example{
{Command: "blog:export --path=backup.json", Description: "Export to another file"},
},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
return nil
},
}
// Hidden commands run, but list shows them only with --all.
cleanup := bonfire.Command{
Name: "blog:cleanup",
Description: "Remove orphaned uploads",
Hidden: true,
}
root, err := bonfire.NewRootIO("acme", []bonfire.Command{export, cleanup}, strings.NewReader(""), os.Stdout, os.Stdout)
if err != nil {
fmt.Println(err)
return
}
bonfire.Execute(context.Background(), root, []string{"help", "blog:export"})
// Output:
// Description:
// Export published posts as JSON
//
// Usage:
// blog:export [options]
//
// Options:
// --path=PATH Output file [default: "posts.json"]
//
// Global options:
// -h, --help Display help for the given command
// -q, --quiet Do not output any message
// -v|vv|vvv Increase verbosity
// --ansi|no-ansi Force (or disable) ANSI output
// -n, --no-interaction Do not ask any interactive question
// --env The environment the command runs under
//
// Help:
// Writes every published post, newest first, to a JSON file.
//
// Examples:
// # Export to another file
// bin/acme blog:export --path=backup.json
}
func ExampleWithHint() {
publish := bonfire.Command{
Name: "blog:publish",
Description: "Publish a draft post",
Args: []bonfire.Arg{{Name: "slug", Description: "Post slug", Required: true}},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
slug, _ := in.Argument("slug")
return bonfire.WithHint(fmt.Errorf("blog: no draft named %q", slug),
"Only drafts can be published; published posts keep their slug.",
"{bin} blog:drafts")
},
}
root, err := bonfire.NewRootIO("acme", []bonfire.Command{publish}, strings.NewReader(""), os.Stdout, os.Stdout)
if err != nil {
fmt.Println(err)
return
}
code := bonfire.Execute(context.Background(), root, []string{"blog:publish", "hello-world"})
fmt.Println("exit code:", code)
// Output:
// ERROR blog: no draft named "hello-world"
//
// Only drafts can be published; published posts keep their slug.
//
// Try:
// bin/acme blog:drafts
//
// Run with -v for details.
//
// exit code: 1
}
func ExampleCheckDocs() {
commands := []bonfire.Command{
{
Name: "blog:publish",
Description: "Publish a draft post",
Long: "Publishes the draft with the given slug and notifies subscribers.",
Args: []bonfire.Arg{{Name: "slug", Description: "Post slug", Required: true}},
Examples: []bonfire.Example{{Command: "blog:publish hello-world"}},
},
{
Name: "blog:reindex",
Description: "Rebuild the search index",
Flags: []bonfire.Flag{{Name: "batch", Default: "500"}},
},
}
for _, problem := range bonfire.CheckDocs(commands) {
fmt.Println(problem)
}
// Output: blog:reindex: missing long help, examples, option --batch description
}
// importPostsCommand is the blog:import command of the acme binary.
func importPostsCommand() bonfire.Command {
return bonfire.Command{
Name: "blog:import",
Description: "Import posts from a feed",
Args: []bonfire.Arg{{Name: "url", Description: "Feed URL", Required: true}},
Flags: []bonfire.Flag{
{Name: "dry-run", Description: "Report without writing", Bare: true},
{Name: "tag", Description: "Tag to apply (repeatable)", Repeatable: true},
},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
url, _ := in.Argument("url")
dryRun := bonfire.FlagBool(in, "dry-run")
return out.Spinner("Importing "+url, func() error {
out.Table([]string{"Tag"}, [][]string{{"news"}})
if dryRun {
out.Warning("dry run: nothing written")
}
return nil
})
},
}
}
// acmeMain is the body of the acme binary's main function, which calls
// os.Exit(acmeMain(os.Args[1:], os.Stdout, os.Stderr)).
func acmeMain(args []string, stdout, stderr io.Writer) int {
g := bonfire.PeekGlobals(args)
root, err := bonfire.NewRoot("acme", []bonfire.Command{importPostsCommand()}, stdout,
bonfire.WithVersion(bonfire.BuildVersion()))
if err != nil {
return bonfire.Fail(stderr, "acme", err, g)
}
return bonfire.Execute(context.Background(), root, args)
}
func ExampleExecute() {
code := acmeMain([]string{"blog:import", "--dry-run", "https://example.com/feed"}, os.Stdout, os.Stdout)
fmt.Println("exit code:", code)
// Output:
// [...] Importing https://example.com/feed
// Tag
// news
// ⚠ dry run: nothing written
// exit code: 0
}
func ExampleCatalog_Has() {
ctx := context.Background()
catalog := bonfire.NewCatalog([]bonfire.Command{importPostsCommand()})
if catalog.Has("blog:import") {
err := catalog.Call(ctx, "blog:import", []string{"--dry-run", "https://example.com/feed"}, os.Stdout)
fmt.Println(err)
}
err := catalog.Call(ctx, "blog:export", nil, os.Stdout)
fmt.Println(errors.Is(err, bonfire.ErrUnknownCommand)) // not registered in this binary
// Output:
// [...] Importing https://example.com/feed
// Tag
// news
// ⚠ dry run: nothing written
// <nil>
// true
}