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
This commit is contained in:
@@ -53,18 +53,12 @@ Use cases:
|
||||
|
||||
## Usage
|
||||
|
||||
```go
|
||||
package main
|
||||
A command declares its arguments and flags and gets an injected console:
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/bonfire"
|
||||
)
|
||||
|
||||
func main() {
|
||||
importPosts := bonfire.Command{
|
||||
```go src=modules/bonfire/example_test.go#importPostsCommand
|
||||
// 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}},
|
||||
@@ -84,28 +78,43 @@ func main() {
|
||||
})
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
args := os.Args[1:]
|
||||
The binary's main function calls this with os.Args[1:], os.Stdout and os.Stderr and exits with the code it returns:
|
||||
|
||||
```go src=modules/bonfire/example_test.go#acmeMain
|
||||
// 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{importPosts}, os.Stdout,
|
||||
root, err := bonfire.NewRoot("acme", []bonfire.Command{importPostsCommand()}, stdout,
|
||||
bonfire.WithVersion(bonfire.BuildVersion()))
|
||||
if err != nil {
|
||||
os.Exit(bonfire.Fail(os.Stderr, "acme", err, g))
|
||||
return bonfire.Fail(stderr, "acme", err, g)
|
||||
}
|
||||
os.Exit(bonfire.Execute(context.Background(), root, args))
|
||||
return bonfire.Execute(context.Background(), root, args)
|
||||
}
|
||||
```
|
||||
|
||||
Running a command in-process, with empty stdin so prompts take their defaults:
|
||||
|
||||
```go
|
||||
catalog := bonfire.NewCatalog(commands)
|
||||
```go src=modules/bonfire/example_test.go#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)
|
||||
if errors.Is(err, bonfire.ErrUnknownCommand) {
|
||||
// not registered in this binary
|
||||
}
|
||||
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
|
||||
```
|
||||
|
||||
## API reference
|
||||
|
||||
Reference in New Issue
Block a user