pkg: github.com/genuinetools/pkg/cli Index | Examples | Files

package cli

import "github.com/genuinetools/pkg/cli"

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

Package Files

cli.go doc.go version.go

type Command Uses

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 Uses

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 Uses

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 Uses

func NewProgram() *Program

NewProgram creates a new Program with some reasonable defaults for Name, Description, and Version.

Code:

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()
}

Code:

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

func (*Program) Run Uses

func (p *Program) Run()

Run is the entry point for the program. It parses the arguments and executes the commands.

Package cli imports 10 packages (graph) and is imported by 62 packages. Updated 2018-09-11. Refresh now. Tools for package owners.