gocli

README

About gocli

gocli is yet another package to aid with parsing command line arguments.

Unlike many other libraries, it focuses mainly on support of subcommands. Define as many subcommands as you want, they are handled by using FlagSets recursively. Simple yet powerful enough for many scenarios.

The help output format is inspired among others by codegangsta's cli library.

Status

The API has been tagged with v1.0.0, please use gopkg.in to lock your dependencies.

Usage

import "gopkg.in/tchap/gocli.v2"

Documentation

GoDoc

Example

See app_test.go.

License

MIT, see the LICENSE file.

Documentation

Overview

gocli is yet another package to aid with parsing command line arguments.

Unlike many other libraries, it focuses mainly on support of subcommands. Define as many subcommands as you want, they are handled by using FlagSets recursively. Simple yet powerful enough for many scenarios.

The help output format is inspired among others by codegangsta's cli library.

Index

• Variables
• type App
  • func NewApp(name string) *App
• type Command
  • func (cmd *Command) DefaultFlagsString() string
  • func (cmd *Command) MustRegisterSubcommand(subcmd *Command)
  • func (cmd *Command) Name() string
  • func (cmd *Command) Run(args []string)
  • func (cmd *Command) Usage()

Examples

• App

Variables

var AppHelpTemplate = `` /* 321-byte string literal not displayed */

Default App help template.

var CommandHelpTemplate = `` /* 242-byte string literal not displayed */

Default Command help template.

Types

type App

type App struct {
	*Command

	Name    string
	Version string
}

The root object that starts the chain of subcommands.

Example

// Create the root App object.
app := NewApp("app")
app.Short = "my bloody gocli app"
app.Version = "1.2.3"
app.Long = `
  This is a long description of my super uber cool app.`

// A verbose switch flag.
var verbose bool

// Create a subcommand.
var subcmd = &Command{
	UsageLine: "subcmd [-v]",
	Short:     "some kind of subcommand, you name it",
	Long:      "Brb, too tired to write long descriptions.",
	Action: func(cmd *Command, args []string) {
		fmt.Printf("verbose mode set to %t\n", verbose)
	},
}

// Set up the verbose switch. This can be as well called in init() or so.
subcmd.Flags.BoolVar(&verbose, "v", false, "print verbose output")

// Register the command with the parent command. Also suitable for init().
app.MustRegisterSubcommand(subcmd)

/*
	Run the whole thing.

	app.Run([]string{}) would lead into:

	APPLICATION:
	  app - my bloody gocli app

	OPTIONS:
	  -h=false: print help and exit

	VERSION:
	  1.2.3

	DESCRIPTION:
	  This is a long description of my super uber cool app.

	SUBCOMMANDS:
	  subcmd	 some kind of subcommand, you name it

	, app.Run([]string{"subcmd", "-h"}) into something similar.
*/

app.Run([]string{"subcmd"})
app.Run([]string{"subcmd", "-v"})

Output:

verbose mode set to false
verbose mode set to true

func NewApp

func NewApp(name string) *App

App constructor. Unfortunately App could not be written in a way that would allow to simply use a struct literal.

type Command

type Command struct {
	// Fitting to be set in the Command struct literal.
	UsageLine string
	Short     string
	Long      string
	Action    func(cmd *Command, args []string)

	// Flag set for this subcommand.
	Flags flag.FlagSet

	// All subcommands registered. Although it can be accessed directly,
	// it is not supposed to be used like that. Use MustRegisterSubcmd().
	// This is exported only for the templates to be able to access it.
	Subcmds []*Command
	// contains filtered or unexported fields
}

Command represents a node in the chain of subcommands. Even App uses it, it is embedded there.

func (*Command) DefaultFlagsString

func (cmd *Command) DefaultFlagsString() string

Returns the same as flag.FlagSet.PrintDefaults, but as a string instead of printing it directly into the output stream.

func (*Command) MustRegisterSubcommand

func (cmd *Command) MustRegisterSubcommand(subcmd *Command)

Register a new subcommand with the command. Panic if something is wrong.

func (*Command) Name

func (cmd *Command) Name() string

Get name from the usage line. The name is the first word on the usage line.

func (*Command) Run

func (cmd *Command) Run(args []string)

Run the command with supplied arguments. This is called recursively if a subcommand is detected, just a prefix is cut off from the arguments.

func (*Command) Usage

func (cmd *Command) Usage()

Print help and exit.