go-cli: github.com/motemen/go-cli Index | Examples | Files | Directories

package cli

import "github.com/motemen/go-cli"

Package cli is a simple framework for creating CLI apps with commands. Its subpackage github.com/motemen/go-cli/gen provides a way to generate commands from document comments in the code.

Code:

cli.Default.Name = "eg"             // defaults to os.Args[0]
cli.Default.ErrorWriter = os.Stdout // defaults to os.Stderr

cli.Use(&cli.Command{
    Name:  "foo",
    Short: "description in one line",
    Long: `foo [-v] <arg>

Description in paragraphs, starting with a usage line.
Blah blah blah`,
    Action: func(flags *flag.FlagSet, args []string) error {
        verbose := flags.Bool("v", false, "set verbosity")
        flags.Parse(args)

        args = flags.Args()
        if len(args) < 1 {
            return cli.ErrUsage
        }

        if *verbose {
            log.Println("showing foo...")
        }

        fmt.Println("foo", args[0])

        if *verbose {
            log.Println("succeeded.")
        }

        return nil
    },
})
cli.Run(os.Args[1:])

Output:

Usage: eg <command> [<args>]

Commands:
    foo    description in one line

Index

Examples

Package Files

cli.go

Variables

var (
    // Default implementation of App. Its name is set to os.Args[0].
    Default = &App{
        Commands:          Commands,
        ErrorWriter:       os.Stderr,
        FlagErrorHandling: flag.ExitOnError,
    }
    // Commands is default value of Default.Commands.
    Commands = map[string]*Command{}
)
var ErrUsage = fmt.Errorf("usage error")

ErrUsage is the error indicating the user had wrong usage.

func Dispatch Uses

func Dispatch(args []string) error

Dispatch is shortcut for Default.Dispatch.

func Run Uses

func Run(args []string)

Run is a shortcut for Default.Run.

func Use Uses

func Use(cmd *Command)

Use is a shortcut for Default.Use.

type App Uses

type App struct {
    Name     string
    Commands map[string]*Command

    ErrorWriter       io.Writer
    FlagErrorHandling flag.ErrorHandling
}

App represents for a CLI program with commands.

func (*App) Dispatch Uses

func (app *App) Dispatch(args []string) error

Dispatch is yet another entry point which returns error

func (*App) PrintUsage Uses

func (app *App) PrintUsage()

PrintUsage prints out the usage of the program with its commands listed.

func (*App) Run Uses

func (app *App) Run(args []string)

Run is the entry point of the program. It recognizes the first element of args as a command name, and dispatches a command with rest arguments.

func (*App) Use Uses

func (app *App) Use(cmd *Command)

Use registers a app command cmd.

type Command Uses

type Command struct {
    Name string

    // Short (one line) description of the command. Used when the program as
    // invoked without a command name
    Short string

    // Long description of the command. The first line of Long should be a
    // usage line i.e. it starts with the command name. Used when invoked with -h
    Long string

    // The actual implementation of the command. The function will receive two
    // arguments, namely flags and args.  flags is an flag.FlagSet and args are
    // the command line arguments after the command name.  flags is not
    // initialized, so declaring flag variables and arguments parsing with
    // flags.Parse(args) should be called inside the function.
    //
    // Return ErrUsage if you want to show user the command usage.
    Action func(flags *flag.FlagSet, args []string) error
}

Command represents one of commands of App.

func (Command) Usage Uses

func (c Command) Usage(flags *flag.FlagSet) string

Usage returns a usage documentation of a command.

Directories

PathSynopsis
_example
_example/_tools
genPackage gen generates github.com/motemen/go-cli.Command from function docs in files specified.

Package cli imports 8 packages (graph) and is imported by 2 packages. Updated 2018-01-05. Refresh now. Tools for package owners.