Documentation
¶
Overview ¶
Package cli provides a minimal framework for creating and organizing command line Go programs. It is designed to be easy to understand and write.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command interface {
Name() string // "foobar"
Args() string // "<baz> [quux...]"
ShortHelp() string // "Foo the first bar"
LongHelp() string // "Foo the first bar meeting the following conditions..."
// Hidden indicates whether the command should be hidden from the help output.
Hidden() bool
// Register command specific flags.
Register(*flag.FlagSet)
// Run executes the function for the command with a context and the command arguments.
Run(context.Context, []string) error
}
Command defines the interface for each command in a program.
type ContextKey ¶
type ContextKey string
ContextKey defines the type for holding keys in the context.
const ( // GitCommitKey is the key for the program's GitCommit data. GitCommitKey ContextKey = "program.GitCommit" // NameKey is the key for the program's name. NameKey ContextKey = "program.Name" // VersionKey is the key for the program's Version data. VersionKey ContextKey = "program.Version" )
type Program ¶
type Program struct {
// Name of the program. Defaults to path.Base(os.Args[0]).
Name string
// Description of the program.
Description string
// Version of the program.
Version string
// GitCommit information for the program.
GitCommit string
// Commands in the program.
Commands []Command
// FlagSet holds the common/global flags for the program.
FlagSet *flag.FlagSet
// Before defines a function to execute before any subcommands are run,
// but after the context is ready.
// If a non-nil error is returned, no subcommands are run.
Before func(context.Context) error
// After defines a function to execute after any commands or action is run
// and has finished.
// It is run _only_ if the subcommand exits without an error.
After func(context.Context) error
// Action is the function to execute when no subcommands are specified.
// It gives the user back the arguments after the flags have been parsed.
Action func(context.Context, []string) error
}
Program defines the struct for holding information about the program.
func NewProgram ¶
func NewProgram() *Program
NewProgram creates a new Program with some reasonable defaults for Name, Description, and Version.
Example (WithCommand) ¶
package main
import (
"context"
"flag"
"fmt"
"os"
"github.com/genuinetools/pkg/cli"
)
const yoHelp = `Send "yo" to the program.`
func (cmd *yoCommand) Name() string { return "yo" }
func (cmd *yoCommand) Args() string { return "" }
func (cmd *yoCommand) ShortHelp() string { return yoHelp }
func (cmd *yoCommand) LongHelp() string { return yoHelp }
func (cmd *yoCommand) Hidden() bool { return false }
func (cmd *yoCommand) Register(fs *flag.FlagSet) {}
type yoCommand struct{}
func (cmd *yoCommand) Run(ctx context.Context, args []string) error {
fmt.Fprintln(os.Stdout, "yo")
return nil
}
func main() {
// Create a new cli program.
p := cli.NewProgram()
p.Name = "yo"
p.Description = `A tool that prints "yo" when you run the command "yo"`
// Set the GitCommit and Version.
p.GitCommit = "ef2f64f"
p.Version = "v0.1.0"
// Setup the global flags.
var (
debug bool
)
p.FlagSet = flag.NewFlagSet("global", flag.ExitOnError)
p.FlagSet.BoolVar(&debug, "d", false, "enable debug logging")
// Set the before function.
p.Before = func(ctx context.Context) error {
// Set the log level.
if debug {
// Setup your logger here...
}
return nil
}
// Add our commands.
p.Commands = []cli.Command{
&yoCommand{},
}
// Run our program.
p.Run()
}
Output: yo
Example (WithSingleAction) ¶
package main
import (
"context"
"flag"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"github.com/genuinetools/pkg/cli"
)
func main() {
// Create a new cli program.
p := cli.NewProgram()
p.Name = "yo"
p.Description = `A tool that prints "yo"`
// Set the GitCommit and Version.
p.GitCommit = "ef2f64f"
p.Version = "v0.1.0"
// Setup the global flags.
var (
debug bool
)
p.FlagSet = flag.NewFlagSet("global", flag.ExitOnError)
p.FlagSet.BoolVar(&debug, "d", false, "enable debug logging")
// Set the before function.
p.Before = func(ctx context.Context) error {
// Set the log level.
if debug {
// Setup your logger here...
}
return nil
}
// Set the main program action.
p.Action = func(ctx context.Context, args []string) error {
// On ^C, or SIGTERM handle exit.
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)
signal.Notify(c, syscall.SIGTERM)
go func() {
for sig := range c {
log.Printf("Received %s, exiting.", sig.String())
os.Exit(0)
}
}()
fmt.Fprintln(os.Stdout, "yo")
return nil
}
// Run our program.
p.Run()
}
Output: yo
Source Files
Click to show internal directories.
Click to hide internal directories.