grumble

README

Grumble - A powerful modern CLI and SHELL

There are a handful of powerful go CLI libraries available (spf13/cobra, urfave/cli). However sometimes an integrated shell interface is a great and useful extension for the actual application. This library offers a simple API to create powerful CLI applications and automatically starts an integrated interactive shell, if the application is started without any command arguments.

Hint: The API might change slightly, until a first 1.0 release is published.

Introduction

Create a grumble APP.

var app = grumble.New(&grumble.Config{
	Name:        "app",
	Description: "short app description",

	Flags: func(f *grumble.Flags) {
		f.String("d", "directory", "DEFAULT", "set an alternative directory path")
		f.Bool("v", "verbose", false, "enable verbose mode")
	},
})

Register a top-level command. Note: Sub commands are also supported...

app.AddCommand(&grumble.Command{
    Name:      "daemon",
    Help:      "run the daemon",
    Aliases:   []string{"run"},
    Usage:     "daemon [OPTIONS]",
    AllowArgs: true,

    Flags: func(f *grumble.Flags) {
        f.Duration("t", "timeout", time.Second, "timeout duration")
    },

    Run: func(c *grumble.Context) error {
        fmt.Println("timeout:", c.Flags.Duration("timeout"))
        fmt.Println("directory:", c.Flags.String("directory"))
        fmt.Println("verbose:", c.Flags.Bool("verbose"))

        // Handle args.
        fmt.Println("args:")
        fmt.Println(strings.Join(c.Args, "\n"))

        return nil
    },
})

Run the application.

err := app.Run()

Or use the builtin grumble.Main function to handle errors automatically.

func main() {
	grumble.Main(app)
}

Shell Multiline Input

Builtin support for multiple lines.

>>> This is \
... a multi line \
... command

Samples

Check out the sample directory for some detailed examples.

The grml project uses grumble.

Additional Useful Packages

• https://github.com/AlecAivazis/survey
• https://github.com/tj/go-spin

Credits

This project is based on ideas from the great ishell library.

License

MIT

Documentation

Overview

Package grumble is a powerful modern CLI and SHELL.

Index

• func Main(a *App)
• type App
  • func New(c *Config) (a *App)
  • func (a *App) AddCommand(cmd *Command)
  • func (a *App) Commands() *Commands
  • func (a *App) Config() *Config
  • func (a *App) IsShell() bool
  • func (a *App) OnInit(f func(a *App, flags FlagMap) error)
  • func (a *App) OnShell(f func(a *App) error)
  • func (a *App) PrintError(err error)
  • func (a *App) Run() (err error)
  • func (a *App) RunCommand(args []string) error
  • func (a *App) SetDefaultPrompt()
  • func (a *App) SetInterruptHandler(f func(a *App, count int))
  • func (a *App) SetPrintASCIILogo(f func(a *App))
  • func (a *App) SetPrintCommandHelp(f func(a *App, c *Command, shell bool))
  • func (a *App) SetPrintHelp(f func(a *App, shell bool))
  • func (a *App) SetPrompt(p string)
• type Command
  • func (c *Command) AddCommand(cmd *Command)
  • func (c *Command) Parent() *Command
• type Commands
  • func (c *Commands) Add(cmd *Command)
  • func (c *Commands) All() []*Command
  • func (c *Commands) FindCommand(args []string) (cmd *Command, rest []string, err error)
  • func (c *Commands) Get(name string) *Command
  • func (c *Commands) Sort()
  • func (c *Commands) SortRecursive()
• type Config
  • func (c *Config) SetDefaults()
  • func (c *Config) Validate() error
• type Context
  • func (c *Context) Stop()
• type FlagMap
  • func (f FlagMap) Bool(long string) bool
  • func (f FlagMap) Duration(long string) time.Duration
  • func (f FlagMap) Float64(long string) float64
  • func (f FlagMap) Int(long string) int
  • func (f FlagMap) Int64(long string) int64
  • func (f FlagMap) String(long string) string
  • func (f FlagMap) Uint(long string) uint
  • func (f FlagMap) Uint64(long string) uint64
• type FlagMapItem
• type Flags
  • func (f *Flags) Bool(short, long string, defaultValue bool, help string)
  • func (f *Flags) BoolL(long string, defaultValue bool, help string)
  • func (f *Flags) Duration(short, long string, defaultValue time.Duration, help string)
  • func (f *Flags) DurationL(long string, defaultValue time.Duration, help string)
  • func (f *Flags) Float64(short, long string, defaultValue float64, help string)
  • func (f *Flags) Float64L(long string, defaultValue float64, help string)
  • func (f *Flags) Int(short, long string, defaultValue int, help string)
  • func (f *Flags) Int64(short, long string, defaultValue int64, help string)
  • func (f *Flags) Int64L(long string, defaultValue int64, help string)
  • func (f *Flags) IntL(long string, defaultValue int, help string)
  • func (f *Flags) String(short, long, defaultValue, help string)
  • func (f *Flags) StringL(long, defaultValue, help string)
  • func (f *Flags) Uint(short, long string, defaultValue uint, help string)
  • func (f *Flags) Uint64(short, long string, defaultValue uint64, help string)
  • func (f *Flags) Uint64L(long string, defaultValue uint64, help string)
  • func (f *Flags) UintL(long string, defaultValue uint, help string)

Functions

func Main

func Main(a *App)

Main is a shorthand to run the app within the main function. This function will handle the error and exit the application on error.

Types

type App

type App struct {
	closer.Closer
	// contains filtered or unexported fields
}

App is the entrypoint.

func New

func New(c *Config) (a *App)

New creates a new app. Panics if the config is invalid.

func (*App) AddCommand

func (a *App) AddCommand(cmd *Command)

AddCommand adds a new command. Panics on error.

func (*App) Commands

func (a *App) Commands() *Commands

Commands returns the app's commands.

func (*App) Config

func (a *App) Config() *Config

Config returns the app's config value.

func (*App) IsShell

func (a *App) IsShell() bool

IsShell indicates, if this is a shell session.

func (*App) OnInit

func (a *App) OnInit(f func(a *App, flags FlagMap) error)

OnInit sets the function which will be executed before the first command is executed. App flags can be handled here.

func (*App) OnShell

func (a *App) OnShell(f func(a *App) error)

OnShell sets the function which will be executed before the shell starts.

func (*App) PrintError

func (a *App) PrintError(err error)

PrintError prints the given error.

func (*App) Run

func (a *App) Run() (err error)

Run the application and parse the command line arguments. This method blocks.

func (*App) RunCommand

func (a *App) RunCommand(args []string) error

RunCommand runs a single command.

func (*App) SetDefaultPrompt

func (a *App) SetDefaultPrompt()

SetDefaultPrompt resets the current prompt to the default prompt as configured in the config.

func (*App) SetInterruptHandler

func (a *App) SetInterruptHandler(f func(a *App, count int))

SetInterruptHandler sets the interrupt handler function.

func (*App) SetPrintASCIILogo

func (a *App) SetPrintASCIILogo(f func(a *App))

SetPrintASCIILogo sets the function to print the ASCII logo.

func (*App) SetPrintCommandHelp

func (a *App) SetPrintCommandHelp(f func(a *App, c *Command, shell bool))

SetPrintCommandHelp sets the print help function for a single command.

func (*App) SetPrintHelp

func (a *App) SetPrintHelp(f func(a *App, shell bool))

SetPrintHelp sets the print help function.

func (*App) SetPrompt

func (a *App) SetPrompt(p string)

SetPrompt a new prompt.

type Command

type Command struct {
	// Command name.
	// This field is required.
	Name string

	// Command name aliases.
	Aliases []string

	// One liner help message for the command.
	// This field is required.
	Help string

	// More descriptive help message for the command.
	LongHelp string

	// HelpGroup defines the help group headline.
	// Note: this is only used for primary top-level commands.
	HelpGroup string

	// Usage should define how to use the command.
	// Sample: start [OPTIONS] CONTAINER [CONTAINER...]
	Usage string

	// Define all command flags within this function.
	Flags func(f *Flags)

	// Define if the command is allowed to get arguments.
	AllowArgs bool

	// Function to execute for the command.
	Run func(c *Context) error

	// Completer is custom autocompleter for command.
	// It takes in command arguments and returns autocomplete options.
	// By default all commands get autocomplete of subcommands.
	// A non-nil Completer overrides the default behaviour.
	Completer func(prefix string, args []string) []string
	// contains filtered or unexported fields
}

Command is just that, a command for your application.

func (*Command) AddCommand

func (c *Command) AddCommand(cmd *Command)

AddCommand adds a new command. Panics on error.

func (*Command) Parent

func (c *Command) Parent() *Command

Parent returns the parent command or nil.

type Commands

type Commands struct {
	// contains filtered or unexported fields
}

Commands collection.

func (*Commands) Add

func (c *Commands) Add(cmd *Command)

Add the command to the slice. Duplicates are ignored.

func (*Commands) All

func (c *Commands) All() []*Command

All returns a slice of all commands.

func (*Commands) FindCommand

func (c *Commands) FindCommand(args []string) (cmd *Command, rest []string, err error)

FindCommand searches for the final command through all children. Returns a slice of non processed following command args. Returns cmd=nil if not found.

func (*Commands) Get

func (c *Commands) Get(name string) *Command

Get the command by the name. Aliases are also checked. Returns nil if not found.

func (*Commands) Sort

func (c *Commands) Sort()

Sort the commands by their name.

func (*Commands) SortRecursive

func (c *Commands) SortRecursive()

SortRecursive sorts the commands by their name including all sub commands.

type Config

type Config struct {
	// Name specifies the application name. This field is required.
	Name string

	// Description specifies the application description.
	Description string

	// Define all app command flags within this function.
	Flags func(f *Flags)

	// Persist readline historys to file if specified.
	HistoryFile string

	// Specify the max length of historys, it's 500 by default, set it to -1 to disable history.
	HistoryLimit int

	// NoColor defines if color output should be disabled.
	NoColor bool

	// Prompt defines the shell prompt.
	Prompt      string
	PromptColor *color.Color

	// MultiPrompt defines the prompt shown on multi readline.
	MultiPrompt      string
	MultiPromptColor *color.Color

	// Some more optional color settings.
	ASCIILogoColor *color.Color
	ErrorColor     *color.Color

	// Help styling.
	HelpHeadlineUnderline bool
	HelpSubCommands       bool
	HelpHeadlineColor     *color.Color
}

Config specifies the application options.

func (*Config) SetDefaults

func (c *Config) SetDefaults()

SetDefaults sets the default values if not set.

func (*Config) Validate

func (c *Config) Validate() error

Validate the required config fields.

type Context

type Context struct {
	// Reference to the app.
	App *App

	// Args containes the command arguments.
	Args []string

	// Flags contains all command line flags.
	Flags FlagMap

	// Cmd is the currently executing command.
	Command *Command
}

Context defines a command context.

func (*Context) Stop

func (c *Context) Stop()

Stop signalizes the app to exit.

type FlagMap

type FlagMap map[string]*FlagMapItem

FlagMap holds all the parsed flag values.

func (FlagMap) Bool

func (f FlagMap) Bool(long string) bool

Bool returns the given flag value as boolean. Panics if not present. Flags must be registered.

func (FlagMap) Duration

func (f FlagMap) Duration(long string) time.Duration

Duration returns the given flag value as duration. Panics if not present. Flags must be registered.

func (FlagMap) Float64

func (f FlagMap) Float64(long string) float64

Float64 returns the given flag value as float64. Panics if not present. Flags must be registered.

func (FlagMap) Int

func (f FlagMap) Int(long string) int

Int returns the given flag value as int. Panics if not present. Flags must be registered.

func (FlagMap) Int64

func (f FlagMap) Int64(long string) int64

Int64 returns the given flag value as int64. Panics if not present. Flags must be registered.

func (FlagMap) String

func (f FlagMap) String(long string) string

String returns the given flag value as string. Panics if not present. Flags must be registered.

func (FlagMap) Uint

func (f FlagMap) Uint(long string) uint

Uint returns the given flag value as uint. Panics if not present. Flags must be registered.

func (FlagMap) Uint64

func (f FlagMap) Uint64(long string) uint64

Uint64 returns the given flag value as uint64. Panics if not present. Flags must be registered.

type FlagMapItem

type FlagMapItem struct {
	Value     interface{}
	IsDefault bool
}

FlagMapItem holds the specific flag data.

type Flags

type Flags struct {
	// contains filtered or unexported fields
}

Flags holds all the registered flags.

func (*Flags) Bool

func (f *Flags) Bool(short, long string, defaultValue bool, help string)

Bool registers a boolean flag.

func (*Flags) BoolL

func (f *Flags) BoolL(long string, defaultValue bool, help string)

BoolL same as Bool, but without a shorthand.

func (*Flags) Duration

func (f *Flags) Duration(short, long string, defaultValue time.Duration, help string)

Duration registers a duration flag.

func (*Flags) DurationL

func (f *Flags) DurationL(long string, defaultValue time.Duration, help string)

DurationL same as Duration, but without a shorthand.

func (*Flags) Float64

func (f *Flags) Float64(short, long string, defaultValue float64, help string)

Float64 registers an float64 flag.

func (*Flags) Float64L

func (f *Flags) Float64L(long string, defaultValue float64, help string)

Float64L same as Float64, but without a shorthand.

func (*Flags) Int

func (f *Flags) Int(short, long string, defaultValue int, help string)

Int registers an int flag.

func (*Flags) Int64

func (f *Flags) Int64(short, long string, defaultValue int64, help string)

Int64 registers an int64 flag.

func (*Flags) Int64L

func (f *Flags) Int64L(long string, defaultValue int64, help string)

Int64L same as Int64, but without a shorthand.

func (*Flags) IntL

func (f *Flags) IntL(long string, defaultValue int, help string)

IntL same as Int, but without a shorthand.

func (*Flags) String

func (f *Flags) String(short, long, defaultValue, help string)

String registers a string flag.

func (*Flags) StringL

func (f *Flags) StringL(long, defaultValue, help string)

StringL same as String, but without a shorthand.

func (*Flags) Uint

func (f *Flags) Uint(short, long string, defaultValue uint, help string)

Uint registers an uint flag.

func (*Flags) Uint64

func (f *Flags) Uint64(short, long string, defaultValue uint64, help string)

Uint64 registers an uint64 flag.

func (*Flags) Uint64L

func (f *Flags) Uint64L(long string, defaultValue uint64, help string)

Uint64L same as Uint64, but without a shorthand.

func (*Flags) UintL

func (f *Flags) UintL(long string, defaultValue uint, help string)

UintL same as Uint, but without a shorthand.