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 // // true }